bobbin

Bobbin gives developers and coding agents search and context over their repositories. Use its command line, Model Context Protocol (MCP) server, or agent hooks to find code by meaning, search exact words, and discover files that change together. Local indexing and search need no API key.

Why you would want it

• Find code by meaning: search implementations with a description of their purpose.
• Collect context before editing: combine indexed code with Quipu knowledge when configured.
• Inspect related changes: use history and co-change signals alongside exact search.

The Bobbin book covers search, indexing and agent integration.

Install

curl -fsSL https://raw.githubusercontent.com/scbrown/bobbin/main/install.sh | sh

Python 3.9+, curl, and a Linux or macOS shell. Downloads the latest published archive, verifies SHA-256 and the executable version before publishing command links in ~/.local/bin. Add it to PATH. The complete versioned bundle stays in ~/.local/lib/bobbin/TAG for rollback. Published targets: Linux and macOS, x86_64 and arm64.

Set STACK_INSTALL_ROOT on the receiving shell for another prefix. Pinned releases, alternatives, configuration and removal are in the installation and usage reference.

First success in three commands

Run in a shell with Python 3 and Git installed. This creates a disposable project; initial indexing downloads the embedding model and runs locally on the CPU.

mkdir -p bobbin-demo && cd bobbin-demo && git init -q && printf 'def greeting(name):\n    return "Hello, " + name\n' > greeting.py
bobbin init --quiet && BOBBIN_GPU=0 bobbin index --quiet --skip-calibrate
bobbin grep greeting --json | python3 -c 'import json,sys; r=json.load(sys.stdin)["results"][0]; print("{}:{}-{}".format(r["name"], r["start_line"], r["end_line"]))'

The final command prints:

greeting:1-2

Bobbin found a parsed function, with its source range, in the index you just built. See the quick start for semantic search.

On your own code

Run bobbin init and bobbin index from your repository first.

Question	Command
Where is error handling implemented?	bobbin search "error handling"
What context would help fix login?	bobbin context "fix the login bug"
Where does an exact name appear?	bobbin grep greeting
What changes alongside this file?	bobbin related greeting.py
What is indexed?	bobbin status

See the CLI reference for flags and additional commands.

Wire it into your agent

From the indexed repository, bobbin serve starts an MCP server on standard input/output. Register it by absolute path: MCP clients launch servers without your shell's PATH, so a bare bobbin fails with ENOENT. For Claude Code, from the indexed repository:

claude mcp add bobbin -- "$(command -v bobbin)" serve "$PWD"

Other clients take the same command as JSON (use the output of command -v bobbin):

{"mcpServers":{"bobbin":{"command":"/absolute/path/to/bobbin","args":["serve","/path/to/repo"]}}}

For automatic Claude Code context injection, run bobbin hook install in the repository; it updates that project's .claude/settings.json. See agent setup for client configuration and hooks for gating, deduplication and removal. Prefer MCP when available, then the CLI; the HTTP API is the transport fallback.

Before you start

The installer needs Python 3.9+, curl and Linux or macOS. Initial indexing requires disk space and a model download; CPU inference works without an API key. Run indexing from the repository you want searchable. Quipu integration needs its own configuration and does not follow from local indexing alone.

What's next

• The Bobbin book: concepts and reference.
• Docs map: find every guide.
• Quick start: index a repository.

Related tools and repository knowledge

• Tambo: guided stack installation and verification.
• Camayoc: governed memory and vocabulary.
• Detailed examples and agent setup.

Load this repository’s graph: public repository-pendant assets have not yet been verified. When a release supplies the archive, checksum and provenance, follow the verified import workflow: extract the share directory and use quipu import SHARE_DIR --db repository.db. Import stages knowledge; ROOT stays unchanged.

🧺 The stack

The Quipu stack is built around a governed, bitemporal knowledge store: shared facts, decisions and work history your agents can query. Quipu can check writes against your rules, records where each fact came from, and answers what was true when.

tool	what it gives your agents
tambo	🧰 Agent Platform Toolkit - installs and configures the quipu stack
quipu	stores shared facts with provenance and history; can check writes against your rules
camayoc	prepares knowledge and vocabulary for Quipu, with checks before it is admitted
quechua	shared vocabulary and shapes for interoperable knowledge
chaski	reacts to graph changes and delivers governed notifications
bobbin	indexes your codebase and injects context from that index and Quipu knowledge
yupana	shows code impact and can read policies from Quipu to govern agent actions
desire-path	turns agent mistakes into feature requests; works on its own without Quipu
seeds	a work item tracker backed by the Quipu knowledge base
shantytown	runs crews of AI agents on work items, triggered by hand, on a schedule or by events; can share work and memory through Quipu
rikuy	live brief: status, graphs, watches and signed decisions over Quipu
shuttle	runs signed agent workflows and keeps their records in Quipu

Contributing

Run just check and just test before submitting changes.

📜 License

License.