Skip to content

CLAUDE.md

Latest commit

 

History

History
150 lines (108 loc) · 6.79 KB

CLAUDE.md

File metadata and controls

150 lines (108 loc) · 6.79 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Python commands

Always use python instead of python3 in commands — python3 does not work reliably on Windows.

Commit style

Do not add Co-Authored-By trailers to commits. Commit messages should be plain, without AI attribution lines.

What this repo is

Chub is the all-in-one infrastructure layer for AI-assisted development teams. Built as a high-performance Rust rewrite of Context Hub, it provides:

  • Context — curated, versioned API docs served to any AI coding agent via CLI + MCP
  • Tracking — session lifecycle recording, token/cost analytics, and reasoning capture across Claude Code, Cursor, Copilot, Gemini CLI, Codex, and more
  • Security — secret scanning (gitleaks/betterleaks-compatible) with AI transcript awareness, automatic transcript redaction
  • Team — git-tracked sharing of docs, annotations, profiles, agent configs, and usage reports

Format-compatible with the original JS Context Hub and entire.io checkpoint format. See docs/plan.md for roadmap.

Commands

Build & run

cargo build                          # debug build
cargo build --release                # optimised binary → target/release/chub
cargo run -- search "stripe"         # run directly (debug)
cargo run -- get openai/chat --lang python

Test

cargo test --all                     # all tests in all crates
cargo test -p chub-core              # core library only
cargo test -p chub-core search       # tests whose name contains "search"

Unit tests are inline #[cfg(test)] blocks. Integration tests: crates/chub-core/tests/team_features.rs, crates/chub-core/tests/search_parity.rs.

Lint & format

cargo fmt --all                      # format all crates
cargo fmt --all -- --check           # check only (CI mode)
cargo clippy --all -- -D warnings    # lint; warnings are errors

Pre-commit (installed)

pre-commit run --all-files           # run all hooks manually

Version bump

./scripts/set-version.sh 0.2.0      # set version across all packages

The version is defined in 9 files across Rust, npm, and Python. Always use the script — never edit version strings by hand. After bumping, run cargo check to regenerate Cargo.lock.

Build the content registry (content → dist/)

cargo run --release -- build ./content -o ./dist
cargo run --release -- build ./content --validate-only
cargo run --release -- build ./content --base-url https://cdn.aichub.org/v1

Architecture

Three crates: chub-core (library — all business logic), chub-cli (library — CLI commands, MCP server, output), and chub (thin binary wrapper — the cargo install chub entry point). chub → chub-cli → chub-core.

For detailed architecture, data flow, conventions, and team feature design, use chub's own project context:

  • chub get project/architecture — crate layout, data flow, design decisions
  • chub get project/conventions — error handling, serialization, CLI output, testing patterns
  • chub get project/team-features — feature map, adding new features, config inheritance

Key paths

Area Location
Core library crates/chub-core/src/
CLI commands crates/chub-cli/src/commands/ (one file per command)
Team features crates/chub-core/src/team/
MCP server crates/chub-cli/src/mcp/
Secret scanning crates/chub-core/src/scan/ (config, finding, report, scanner)
Search pipeline crates/chub-core/src/search/ (tokenizer → BM25 → inverted index → lexical boost)
Shared helpers crates/chub-core/src/util.rs
Content registry content/<author>/docs/<entry>/<lang>/DOC.md
npm wrapper npm/chub/bin/chub.js (thin platform binary resolver)

Key env vars

Var Purpose
CHUB_DIR Override ~/.chub data directory
CHUB_BUNDLE_URL Override the default CDN URL
CHUB_PROJECT_DIR Override project root
CHUB_PROFILE Override active context profile
CHUB_ANNOTATION_SERVER Override org annotation server URL
CHUB_ANNOTATION_TOKEN Auth token for org annotation server
CHUB_TELEMETRY Set to 0 to disable telemetry
CHUB_FEEDBACK Set to 0 to disable feedback

Config: ~/.chub/config.yaml (personal) → .chub/config.yaml (project, git-tracked) → .chub/profiles/<name>.yaml (role).

Format compatibility

All on-disk formats (registry.json, search-index.json, annotation JSONs) are byte-for-byte identical with the original JS Context Hub. The serde(rename) attributes on types.rs structs enforce camelCase field names.

Integrations

Chub integrates with AI agents via MCP (runtime tools) and agent config generation (static rules). See docs/guide/agent-config.md and docs/reference/mcp-server.md for full setup guides.

MCP tools

Available via chub mcp (stdio server): chub_search, chub_get, chub_list, chub_context, chub_pins, chub_annotate, chub_feedback, chub_track.

Agent config generation

chub agent-config sync generates rules files from .chub/config.yaml. See docs/guide/agent-config.md for the full target list and setup guides.

Skills (slash commands)

Command What it does
/docs <query> Search or fetch documentation
/annotate <id> <note> Record a team annotation
/setup Initialize chub for the current project

Project context

Pinned docs (.chub/pins.yaml): serde/derive, clap/derive, tokio/runtime, axum/routing.

Project context docs (.chub/context/): architecture.md, conventions.md, team-features.md. Access via chub get project/<name> or chub_context MCP tool.

Doc review checklist

When asked to review docs, verify claims against source code. Hard numbers (counts, lists) should live in one canonical doc; other docs should reference it instead of duplicating.

Fact Source of truth Canonical doc
MCP tool names crates/chub-cli/src/mcp/tools.rs docs/reference/mcp-server.md
CLI commands crates/chub-cli/src/lib.rs (Commands enum) docs/reference/cli.md
Agent config targets crates/chub-core/src/team/agent_config.rs docs/guide/agent-config.md
Dep detection file types crates/chub-core/src/team/detect.rs docs/reference/cli.md
BM25 params, search fields crates/chub-core/src/search/bm25.rs .chub/context/architecture.md
Frontmatter schema crates/chub-core/src/frontmatter.rs docs/guide/content-guide.md
Benchmark numbers scripts/benchmark.sh output docs/guide/vs-context-hub.md
Version string Cargo.toml workspace version (use ./scripts/set-version.sh)