<p align="center">
<img src="website/assets/logo.svg" width="80" height="80" alt="Chub">
</p>
<h1 align="center">Chub</h1>
<p align="center">
<strong>Serve curated, versioned API docs to AI coding agents — so they stop hallucinating your APIs.</strong>
</p>
<p align="center">
<a href="https://www.npmjs.com/package/@nrl-ai/chub"><img src="https://img.shields.io/npm/v/@nrl-ai/chub?color=0ea5e9&label=npm" alt="npm"></a>
<a href="https://pypi.org/project/chub/"><img src="https://img.shields.io/pypi/v/chub?color=0ea5e9&label=pypi" alt="PyPI"></a>
<a href="https://crates.io/crates/chub"><img src="https://img.shields.io/crates/v/chub?color=0ea5e9&label=crates.io" alt="crates.io"></a>
<a href="https://github.com/nrl-ai/chub/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-0ea5e9" alt="License"></a>
</p>
<p align="center">
<a href="https://chub.nrl.ai">Docs</a> · <a href="https://chub.nrl.ai/guide/getting-started">Getting Started</a> · <a href="https://github.com/nrl-ai/chub/releases">Releases</a>
</p>
---
## 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
```
Built on [Context Hub](https://github.com/andrewyng/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, and content integrity verification.
---
## How It Works
```
┌──────────────┐ ┌─────────────┐ ┌──────────────────┐
│ AI Agent │────▶│ Chub MCP │────▶│ Doc Registry │
│ (Claude, │ │ Server │ │ (CDN / local) │
│ Cursor) │◀────│ │◀────│ │
└──────────────┘ └─────────────┘ └──────────────────┘
Gets accurate Searches, 1,500+ curated
API docs on caches, and docs covering
demand verifies docs major APIs
```
1. **Agent needs API docs** — asks Chub via MCP (or you run `chub get`)
2. **Chub searches the registry** — BM25 search with lexical boosting, 19x faster than the JS version
3. **Returns the right version** — respects your team's pins, language preference, and version locks
4. **Appends team knowledge** — annotations, project context, and profile rules travel with the doc
---
## Quick Start
### Install
```sh
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](https://github.com/nrl-ai/chub/releases) — single 10 MB binary, no runtime dependencies.
### Use
```sh
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 `.mcp.json` (Claude Code) or `.cursor/mcp.json` (Cursor):
```json
{
"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.
---
## 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.
```sh
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
```sh
chub pin openai/chat --lang python --version 4.0 --reason "Use v4 API"
chub pin stripe/api --lang javascript
chub get --pinned # fetch all pinned docs at once
```
### Add team knowledge that follows the docs
```sh
chub annotate openai/chat "Always use streaming for chat completions" --team
chub annotate stripe/api "We use Stripe Connect, not standard Checkout" --team
```
When any agent fetches these docs, your annotations appear alongside the official content — clearly marked as team-contributed.
### Scope context by role
```sh
chub profile use backend # backend devs get backend-relevant docs
chub profile use frontend # frontend devs get frontend-relevant docs
```
### Keep versions fresh
```sh
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
```sh
chub agent-config generate # generate CLAUDE.md, .cursorrules, AGENTS.md from one source
chub agent-config sync # update only if changed
```
---
## CLI Reference
### Search and Fetch
```sh
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
```sh
chub pin openai/chat --lang python --version 4.0 --reason "Use v4 API"
chub pins # list all pins
chub unpin openai/chat # remove a pin
chub get --pinned # fetch all pinned docs at once
```
### Context Profiles
```sh
chub profile use backend # activate a profile
chub profile use none # clear profile
chub profile list # list available profiles
```
### Team Annotations
```sh
chub annotate openai/chat "Use streaming API" --team # git-tracked
chub annotate openai/chat "My local note" --personal # local only
```
### Dependency Detection
```sh
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`.
### Agent Config Sync
```sh
chub agent-config generate # generate CLAUDE.md, .cursorrules, etc.
chub agent-config sync # update only if changed
chub agent-config diff # preview changes
```
### Snapshots and Freshness
```sh
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
```sh
chub update # refresh cached registry
chub cache status # show cache state
chub cache clear # clear local cache
```
---
## MCP Server
```sh
chub mcp # start MCP stdio server
chub mcp --profile backend # with a profile
```
### Available tools
| `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, 7 skills). Median of 5 runs on Windows 11, Node.js v22, Rust release build.
### Performance
| `search "stripe payments"` | 1,060 ms | **56 ms** | **19x** |
| `build --validate-only` | 1,920 ms | **380 ms** | **5x** |
| `build` (1,560 entries) | 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
| 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
| CLI commands | 7 | **20** |
| MCP tools | 5 | **7** |
| Team features (pins, profiles, snapshots, etc.) | — | **Yes** |
| Content integrity verification | — | **Yes** |
| Auto version detection (`--match-env`) | — | **Yes** |
| Registry format compatibility | — | **Identical** |
---
## Content Registry
### Build your own docs
```sh
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
```sh
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](docs/private-content.md) for details.
---
## Test Suite
99 tests covering behavioral parity with Context Hub and all team features:
| Tokenizer | 6 | Stop words, punctuation, edge cases |
| BM25 search | 7 | Scoring, ranking, limits, field weights |
| Inverted index | 1 | Parity with linear scan |
| Frontmatter parser | 9 | YAML, CRLF, BOM, empty, numeric |
| Language normalization | 4 | Aliases, case, unknown |
| Build integration | 15 | Output format, validation, structure |
| Search parity | 20 | Multi-word, tags, descriptions |
| Team features | 33 | Pins, profiles, annotations, snapshots, detect, freshness |
```sh
cargo test --all # run all tests
```
---
## Documentation
Full documentation at [chub.nrl.ai](https://chub.nrl.ai):
- [Getting Started](https://chub.nrl.ai/guide/getting-started) — install and first commands
- [Installation](https://chub.nrl.ai/guide/installation) — all platforms and package managers
- [Why Chub](https://chub.nrl.ai/guide/why-chub) — comparison with Context Hub
- [Doc Pinning](https://chub.nrl.ai/guide/pinning) — lock doc versions
- [Context Profiles](https://chub.nrl.ai/guide/profiles) — role-scoped context
- [Team Annotations](https://chub.nrl.ai/guide/annotations) — shared knowledge
- [Project Context](https://chub.nrl.ai/guide/project-context) — custom docs
- [CLI Reference](https://chub.nrl.ai/reference/cli) — all commands and flags
- [Configuration](https://chub.nrl.ai/reference/configuration) — config file format
- [MCP Server](https://chub.nrl.ai/reference/mcp-server) — agent integration
- [Showcases](https://chub.nrl.ai/guide/showcases) — real-world usage examples
---
## Contributing
```sh
cargo build # debug build
cargo test --all # run tests
cargo fmt --all # format
cargo clippy --all -- -D warnings # lint
```
---
## License
MIT