chub-cli 0.1.20

chub-cli-0.1.20 is not a library.

Visit the last successful build: chub-cli-0.1.22

The Problem

AI coding agents (Claude, Cursor, Copilot) hallucinate API signatures, use deprecated endpoints, and forget what they learned between sessions. You paste docs into chat, but they get lost in context. Your teammates paste different docs. Nobody's on the same page.

The Solution

Chub is a CLI + MCP server that serves curated, versioned API documentation directly to your AI agents. Think of it as a package manager for AI context: you pin the docs you need, your agents fetch them on demand, and your whole team shares the same source of truth — tracked in git.

You type:   chub get openai/chat --lang python
Agent sees: The complete, accurate OpenAI Chat API reference for Python
           + any bugs, fixes, and best practices your team has discovered

Built on Context Hub by Andrew Ng — Chub is a high-performance Rust rewrite that extends the original with team features: shared doc pinning, git-tracked annotations, context profiles, agent config sync, content integrity verification, and self-learning agents that write back what they discover.

How It Works

┌──────────────┐     ┌─────────────┐     ┌──────────────────┐
│  AI Agent    │────▶│  Chub MCP   │────▶│  Doc Registry    │
│  (Claude,    │     │  Server     │     │  (CDN / local)   │
│   Cursor)    │◀────│             │◀────│                  │
└──────────────┘     └─────────────┘     └──────────────────┘
   Gets accurate        Searches,             1,553+ curated
   API docs on          caches, and           docs covering
   demand               verifies docs         major APIs

Agent needs API docs — asks Chub via MCP (or you run chub get)
Chub searches the registry — BM25 search with lexical boosting, 19x faster than the JS version
Returns the right version — respects your team's pins, language preference, and version locks
Appends team knowledge — annotations, project context, and profile rules travel with the doc

Quick Start

Install

npm install -g @nrl-ai/chub     # npm (recommended)
pip install chub                 # pip
cargo install chub               # cargo (build from source)
brew install nrl-ai/tap/chub     # homebrew (macOS / Linux)

Or download a prebuilt binary from GitHub Releases — single 10 MB binary, no runtime dependencies.

Use

chub search "stripe payments"                  # find docs
chub get openai/chat --lang python             # fetch a doc
chub get stripe/api --match-env                # auto-detect version from your package.json
chub list                                      # browse everything

Connect to Your AI Agent

Add to .claude/settings.json (Claude Code), .cursor/mcp.json (Cursor), or the equivalent for your agent:

{
  "mcpServers": {
    "chub": {
      "command": "chub",
      "args": ["mcp"]
    }
  }
}

Your agent now has access to chub_search, chub_get, chub_list, chub_annotate, chub_context, chub_pins, and chub_feedback tools.

Works with Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini CLI, Kiro, Cline, Roo Code, Augment, Codex, Continue.dev, and Aider. See Agent Integrations for setup guides.

Team Sharing

This is where Chub goes beyond Context Hub. Initialize a .chub/ directory in your repo and commit it — every developer and every AI agent gets the same versioned context, automatically.

chub init --from-deps            # auto-detect deps, create .chub/, pin matching docs

my-project/
├── .chub/                       # committed to git
│   ├── config.yaml              # project-level config
│   ├── pins.yaml                # locked doc versions
│   ├── annotations/             # team knowledge (e.g., "use streaming API for this endpoint")
│   ├── context/                 # your own docs: architecture, conventions, runbooks
│   └── profiles/                # role-scoped context (backend.yaml, frontend.yaml)

Pin docs to specific versions

chub pin add openai/chat --lang python --version 4.0 --reason "Use v4 API"
chub pin add stripe/api --lang javascript
chub pin get                     # fetch all pinned docs at once

Build a self-learning knowledge base

Annotations live in three tiers — each scoped for different audiences:

Tier	Storage	Visibility
Personal	`~/.chub/annotations/`	You only
Team	`.chub/annotations/` (git-tracked)	Your repo
Org	Remote HTTP API	Entire organization

Agents can write back what they discover — structured by kind so the knowledge is findable, not just buried in a notes field:

# Human adds a note
chub annotate openai/chat "Always use streaming for chat completions" --team

# Agent discovers a bug and records it (kind=issue + kind=fix)
chub annotate openai/chat "tool_choice='none' silently ignores tools" --kind issue --severity high --team
chub annotate openai/chat "use tool_choice='auto' or remove tools from array" --kind fix --team

# Agent validates a best practice
chub annotate openai/chat "Always set max_tokens to avoid unbounded cost" --kind practice --team

Annotation kinds: note, issue (with severity), fix, practice. When any agent fetches these docs, all annotations appear alongside the official content — grouped by kind, clearly marked as team-contributed. Every debugging session becomes permanent team knowledge.

Add to .chub/config.yaml to automatically instruct agents to annotate:

agent_rules:
  include_annotation_policy: true   # adds Annotation Policy section to CLAUDE.md / AGENTS.md

Scope context by role

chub profile use backend         # backend devs get backend-relevant docs
chub profile use frontend        # frontend devs get frontend-relevant docs

Keep versions fresh

chub detect                      # scan package.json, requirements.txt, Cargo.toml, etc.
chub check                       # compare pinned doc versions vs installed package versions
chub check --fix                 # auto-update outdated pins

Sync agent config files

Generate rules files from a single .chub/config.yaml — one config, every agent in sync:

chub agent-config sync           # generate/update all configured targets

Supported targets: claude.md, cursorrules, windsurfrules, agents.md, copilot, gemini.md, clinerules, roorules, augmentrules, kiro.

CLI Reference

Search and Fetch

chub search "stripe"                    # BM25 search across all docs
chub search "auth" --limit 5            # limit results
chub get openai/chat --lang python      # fetch doc by ID
chub get stripe/api --version 2.0       # specific version
chub get stripe/api --match-env         # auto-detect version from project deps
chub get openai/chat --full             # fetch all files in the entry
chub get openai/chat --file refs.md     # fetch a specific file
chub list                               # list all available docs
chub list --json                        # JSON output (works with all commands)

Doc Pinning

chub pin add openai/chat --lang python --version 4.0 --reason "Use v4 API"
chub pin list                           # list all pins
chub pin remove openai/chat             # remove a pin
chub pin get                            # fetch all pinned docs at once

Context Profiles

chub profile use backend                # activate a profile
chub profile use none                   # clear profile
chub profile list                       # list available profiles

Team Annotations

chub annotate openai/chat "Use streaming API" --team       # git-tracked
chub annotate openai/chat "My local note" --personal       # local only

Dependency Detection

chub detect                             # show detected deps with matching docs
chub detect --pin                       # auto-pin all matches

Supports: package.json, requirements.txt, pyproject.toml, Cargo.toml, go.mod, Gemfile, Pipfile, pom.xml, build.gradle, build.gradle.kts.

Agent Config Sync

chub agent-config generate              # generate rules for all configured targets
chub agent-config sync                  # update only if changed
chub agent-config diff                  # preview changes

Snapshots and Freshness

chub snapshot create v1.0               # save current pins
chub snapshot list                      # list snapshots
chub snapshot restore v1.0              # restore pin state
chub snapshot diff v1.0 v2.0            # compare snapshots
chub check                              # check pinned vs installed versions
chub check --fix                        # auto-update outdated pins

Cache Management

chub update                             # refresh cached registry
chub cache status                       # show cache state
chub cache clear                        # clear local cache

MCP Server

chub mcp                                # start MCP stdio server

To scope the session to a profile, activate it first: chub profile use backend && chub mcp.

Available tools

Tool	Description
`chub_search`	Search docs by query, tags, or language
`chub_get`	Fetch a doc by ID (supports `match_env` for auto version detection)
`chub_list`	List all available docs and skills
`chub_annotate`	Read, write, or list annotations
`chub_context`	Get optimal context for a task (pins + annotations + profile)
`chub_pins`	List, add, or remove pinned docs
`chub_feedback`	Submit quality feedback for a doc

Registry resource: chub://registry

Works with any MCP-compatible agent: Claude Code, Cursor, Windsurf, and others. The transport is stdio.

Security

Chub includes several security measures for safe use in team environments:

Content integrity verification — chub build computes SHA-256 hashes of all doc content, stored in the registry. Fetched content is verified against these hashes to detect CDN tampering.
Annotation trust framing — User-contributed annotations are clearly marked as non-official content when served to agents, mitigating prompt injection risks.
Annotation length limits — Notes are capped at 4,000 characters to prevent context flooding.
Path traversal protection — File path parameters are validated and normalized.
Graceful process lifecycle — The MCP server handles signals cleanly to prevent orphan processes.

Benchmarks

Measured on the production corpus (1,553 docs, 8 skills). Median of 5 runs. Full methodology in Chub vs Context Hub.

Performance

Operation	Context Hub (JS)	Chub (Rust)	Speedup
`search "stripe payments"`	1,060 ms	56 ms	19x
`build --validate-only`	1,920 ms	380 ms	5x
`build` (full registry)	3,460 ms	1,770 ms	2x
`get stripe/api`	148 ms	63 ms	2.3x
Cold start (`--help`)	131 ms	44 ms	3x

Resources

Metric	Context Hub (JS)	Chub (Rust)
Package size	~22 MB (`node_modules`)	10 MB (single binary)
Runtime dependency	Node.js 20+	None
Peak memory (build)	~122 MB	~23 MB (5.3x less)

Feature comparison

	Context Hub (JS)	Context7	Chub (Rust)
Team features (pins, profiles, snapshots)	—	—	Yes
Self-learning agents (structured annotations)	—	—	Yes
3-tier annotations (personal, team, org)	—	—	Yes
Agent config sync	—	—	Yes
Content integrity verification	—	—	Yes
Auto version detection (`--match-env`)	—	—	Yes
Self-hosted registry	Yes	—	Yes
Registry format compatibility	—	—	Identical

Content Registry

Build your own docs

chub build ./content -o ./dist                             # build registry
chub build ./content --validate-only                       # validate only
chub build ./content --base-url https://cdn.example.com/v1 # with CDN URL

Content format

content/
  <author>/
    docs/<entry-name>/
      <lang>/DOC.md                  # YAML frontmatter + markdown
      <lang>/<version>/DOC.md        # versioned variant
    skills/<entry-name>/
      SKILL.md

Self-host

chub serve ./dist --port 4242        # serve as HTTP registry

Add your private registry as an additional source in ~/.chub/config.yaml — no cloud required. See Private Content for details.

Test Suite

Comprehensive test coverage across unit, parity, and integration tests:

Suite	Coverage
Search	BM25 scoring, tokenizer, inverted index, lexical boost
Frontmatter	YAML parsing, CRLF, BOM, edge cases
Annotations	Kind validation, severity, 3-tier storage
Build parity	Output format matches JS Context Hub byte-for-byte
Search parity	Multi-word, tags, descriptions match JS results
Team features	Pins, profiles, snapshots, detect, freshness, org HTTP

cargo test --all                     # run all tests

Documentation

Full documentation at chub.nrl.ai:

Getting Started — install and first commands
Installation — all platforms and package managers
Why Chub — comparison with Context Hub
Doc Pinning — lock doc versions
Context Profiles — role-scoped context
Team Annotations — shared knowledge
Project Context — custom docs
CLI Reference — all commands and flags
Configuration — config file format
MCP Server — agent integration
Showcases — real-world usage examples

Contributing

cargo build                          # debug build
cargo test --all                     # run tests
cargo fmt --all                      # format
cargo clippy --all -- -D warnings    # lint

License

MIT