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. Skipsnode_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
crumbs indexthe repos you work across (once, or on acrumbs refreshcron).- Ask Claude to run
crumbs map <repo>orcrumbs 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:
-
Bump the version in all three places:
pyproject.toml,crumbs/__init__.py, andplugin/.claude-plugin/plugin.json(keep them in sync). -
Commit the bump and push to
main. -
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
Metadata
Release files for crumbs-cli 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| crumbs_cli-0.4.0.tar.gz | 25.9 kB | With provenance | Details for crumbs_cli-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| crumbs_cli-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for crumbs_cli-0.4.0-py3-none-any.whl |
Total release size: 49.2 kB
Release files / crumbs_cli-0.4.0.tar.gz
| Download URL | crumbs_cli-0.4.0.tar.gz |
|---|---|
| Size | 25.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c0a49a71f24ced8d6113c8c90884fb76287a9153f73881f0409819f6f5750a27
|
|
BLAKE2b-256 checksum How to use checksums |
11f1ef558b9fff95216a737bd59234688f9dcfaa03590a92cc9345f6a88957f1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 30, 2026.
Transparency logRelease files / crumbs_cli-0.4.0-py3-none-any.whl
| Download URL | crumbs_cli-0.4.0-py3-none-any.whl |
|---|---|
| Size | 23.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d033180953bfd638ddf7f6888b345be6240ff2f8eb1e5e92f76f0b716ea5d52b
|
|
BLAKE2b-256 checksum How to use checksums |
86d885f17035904ae348ddd6d198bca361c1914469561e027e2e12736336090c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 30, 2026.
Transparency logSecurity for crumbs-cli 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for crumbs_cli-0.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 30, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.