Metadata-Version: 2.4
Name: crumbs-cli
Version: 0.3.2
Summary: Local, token-efficient cross-repo context for LLMs. CLI + MCP server.
Author: crumbs
License: MIT
Project-URL: Homepage, https://github.com/crumbs1505/crumbs
Project-URL: Repository, https://github.com/crumbs1505/crumbs
Project-URL: Issues, https://github.com/crumbs1505/crumbs/issues
Keywords: llm,context,claude,code,repo,tokens,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

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

```bash
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

```bash
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):**

```shell
/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/`](plugin/) for details.

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

```jsonc
{
  "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

```bash
python3 -m unittest discover -s tests -v
```

## Releasing

Releases are published to [PyPI](https://pypi.org/project/crumbs-cli/) automatically by
CI ([`.github/workflows/publish.yml`](.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:

   ```bash
   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](https://docs.pypi.org/trusted-publishers/) (OIDC — no token stored
in the repo). PyPI versions are immutable, so every release needs a new version number.

## License

MIT
