crumbs-cli 0.4.0

Local, token-efficient cross-repo context for LLMs. CLI + MCP server.

crumbs

Local, token-efficient cross-repo context for LLMs.

crumbs indexes your repositories into compact context crumbs — file maps and symbol signatures (typed function/class/type declarations + one-line docs + line ranges), never the full file bodies. An assistant like Claude can then understand many repos at once by reading a tiny map instead of paying tokens to read the entire source tree.

Indexing this very tool produces a map of ~1,200 tokens standing in for ~8,400 tokens of source — an ~86% reduction — while still naming every file and symbol. Each symbol carries its full type signature and a source line range (e.g. def build_parser() -> ArgumentParser [L125-168]), so the assistant can open just that slice of a file rather than the whole thing.

• 🪶 Zero dependencies. Pure Python 3.8+ stdlib. Runs on any device.
• 🔒 Fully local. Crumbs live in ~/.crumbs. Nothing leaves your machine.
• 🧠 Cross-repo. Search and pull context across every repo you've indexed.
• 🎯 High signal. Python is parsed via ast; JS/TS/Go/Rust/etc. via fast regex. Skips node_modules, .git, build dirs, lockfiles, and binaries.

Install

The distribution is named crumbs-cli; it provides the crumbs command.

pipx install crumbs-cli       # isolated, on your PATH (recommended)
# or, no install at all:
uvx --from crumbs-cli crumbs --help
# or, from a clone:
pip install -e .              # dev install
python3 -m crumbs --help      # run without installing

Usage

crumbs index ~/code/my-api ~/code/my-web   # index one or more repos
crumbs list                                # show indexed repos + stats
crumbs map my-api --stats                  # compact map of one repo (+ token estimate)
crumbs search "auth token"                 # rank matching symbols across all repos
crumbs context "rate limiting" --repo my-api   # LLM-ready context slice
crumbs refresh                             # re-index everything
crumbs remove my-web                       # drop a repo from the index

A repo can be referenced by name, id, or path.

Use with Claude Code (MCP)

crumbs ships an MCP server (crumbs mcp) so an MCP host — Claude Code, Claude Desktop, or any MCP client — can call it as native tools. It speaks the MCP wire protocol over stdio with zero dependencies (no SDK).

One-command install (Claude Code plugin):

/plugin marketplace add crumbs1505/crumbs
/plugin install crumbs@crumbs

This bundles the MCP server and a skill; repo paths are auto-indexed on first use. See plugin/ for details.

Manual registration (e.g. in a project .mcp.json or your Claude Code config):

{
  "mcpServers": {
    "crumbs": { "command": "uvx", "args": ["--from", "crumbs-cli", "crumbs", "mcp"] }
  }
}

uvx fetches and runs crumbs on demand, so nothing needs to be installed first. (If you installed via pipx, use "command": "crumbs", "args": ["mcp"] instead.)

The server exposes five model-controlled tools — crumbs_map, crumbs_search, crumbs_context, crumbs_index, crumbs_list — and auto-indexes a repo path on first use, so there is no manual setup step.

Workflow with Claude

1. crumbs index the repos you work across (once, or on a crumbs refresh cron).
2. Ask Claude to run crumbs map <repo> or crumbs context "<topic>" instead of reading whole files. It gets the structure and the relevant symbols for a fraction of the tokens, then reads full files only where it actually needs to.

How it stays cheap

	Full repo read	crumbs map
What	every byte of every file	file tree + typed signatures + 1-line docs + line ranges
Bodies	yes	no
Cost	grows with codebase	grows with interface size

Because every symbol records its line range, the follow-up step is cheap too: the assistant reads path:start-end for the one function it needs instead of opening the entire file.

Storage layout (~/.crumbs, override with CRUMBS_HOME):

registry.json        # id -> {name, path, indexed_at, stats}
repos/<id>.json      # full crumb data for one repo

Supported languages

Python (AST), JavaScript/TypeScript, Go, Rust, and a generic declaration matcher for Java, Ruby, PHP, C/C++, C#, Swift, Kotlin. Markdown is indexed by heading. Anything else is skipped from symbol extraction but still ignored safely.

Tests

python3 -m unittest discover -s tests -v

Releasing

Releases are published to PyPI automatically by CI (.github/workflows/publish.yml) whenever a version tag is pushed. To cut a release:

1. Bump the version in all three places: pyproject.toml, crumbs/__init__.py, and plugin/.claude-plugin/plugin.json (keep them in sync).

2. Commit the bump and push to main.

3. Tag and push it:

   git tag v0.3.1 && git push origin v0.3.1
   

CI then builds the sdist + wheel, runs twine check, and publishes to PyPI via Trusted Publishing (OIDC — no token stored in the repo). PyPI versions are immutable, so every release needs a new version number.

License

MIT