Skip to main content

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

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)

Source distribution for crumbs-cli 0.4.0
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)

Table of built distributions (wheels) for crumbs-cli 0.4.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page