Bread

---

Give coding agents less noise, a fresher view of the workspace, and a safer path to change it.

Bread is a local Rust binary that sits beside an agent's native file workflow. It bounds oversized reads and searches, marks context with provenance, rejects stale edits before disk, and builds a workspace-local codebase index. The source, index, optional model, and vector data stay in the workspace.

Bread does not replace an agent's tools with a new tool vocabulary. It uses documented hook events around the tools the agent already has.

Current release gate: Codex CLI. Claude Code and Grok Build adapters exist, but their live validation is deliberately deferred until the Codex gate is complete.

Read the official Bread docs →

---

Before / after

A coding-agent moment	Native path	With Bread
Find code	Run a broad search and inspect all matching output	Use ripgrep-compatible in-process search, ignore rules, and bounded structured matches
Read a large file	Send the whole file into model context	Return a range or structural outline with a freshness marker
Edit after another process changed the file	Apply the old patch against drifted content	Deny the stale write, identify the drifted range, and ask for one narrow reread
Navigate an unfamiliar repository	Repeat searches and manually reconnect symbols	Retrieve bounded lexical, structural, and tested one-hop local-import context
Receive a vague prompt	Guess at useful repository text to inject	Stay silent below the relevance gate

Bread keeps the ripgrep search engine in-process for search parity. It is a policy, context, and safety layer around native tools—not a claim to beat standalone rg at raw search speed.

Start with Codex

The Codex path is the only live-validated integration today.

Install a published Bread release:

curl -fsSL https://raw.githubusercontent.com/Yabuku-xD/bread/main/scripts/install-bread | sh

Or install from a checked-out release:

cargo install --path . --locked

Codex

Add Bread's marketplace and install its plugin:

codex plugin marketplace add Yabuku-xD/bread
codex plugin add bread@bread

Start a new Codex session in the repository where you want Bread enabled, then open /hooks and review/trust Bread's exact command hook. The plugin invokes the bread binary installed above; it never downloads or executes a binary itself.

For a project-local hook instead of the plugin path, run bread install codex in the target repository. Do not use both hook surfaces: they would run the same Bread policy twice.

To remove Bread's Codex plugin:

codex plugin remove bread@bread

For the project-local hook alternative only, remove Bread-owned entries with:

bread uninstall codex

The project-local installer preserves unrelated hook entries and stores its private backup under .bread/. See the complete Codex release guide for rollback and release checks.

Numbers, with the caveats intact

The strongest observed result: a broad Cargo.lock read exposed 4,172 characters to the model with Bread versus 73,408 without it: 94.3% less in that matched local run.

These are local fixture and sandbox measurements, not universal service-level objectives. They use the same repository snapshot, sandbox policy, Codex CLI 0.144.3, gpt-5.6-terra, and low reasoning effort where indicated. Small samples and agent tool-choice variance mean the outcome will not improve on every task.

Measurement	Bread	Matched baseline	Observed change	Evidence
Broad Cargo.lock model-visible tool output	4,172 chars	73,408 chars	94.3% lower	Local sandbox, n=1
Broad Cargo.lock input tokens	43,779	70,436	37.8% lower	Local sandbox, n=1
Codex output tokens	320	1,107	71.1% lower	Matched read-only pairs, n=2
Broad Cargo.lock wall time	7.86 s	9.74 s	19.3% lower	Local sandbox, n=1
README inspection wall time	9.78 s	7.36 s	32.9% higher	Local sandbox, n=1
Replayed context-reduction scorecard	49.6% lower	Raw output baseline	Meets the 40% target	Deterministic fixture
Known stale-edit failure prevention	100%	No raw-tool prevention	All replayed failures prevented	Deterministic fixture
Pass-through hook-decision p95	0.001 ms	15 ms budget	Within budget	Deterministic scorecard
Freshness ghost results	0	0 required	No stale result	Deterministic scorecard
Literal search matches	Exact fixture set	Ripgrep reference set	Exact parity	Deterministic fixture
Index-navigation Codex smoke	2/2 correct	Exact symbol + local import	Both expected routes found	CLI 0.144.3, Terra low, read-only
Tool-call task success	3/3	Vanilla: 3/3	No observed success-rate lift	Matched read-only pairs, n=3

The slower README inspection is intentional to show the trade-off plainly: Bread can add decision and hook overhead where a direct raw read is already small. It is useful when it removes enough downstream context, repeated work, or unsafe state to repay that overhead—not as an automatic speedup.

Indexing A/B

Bread’s registry avoids a runtime catalog on its hot path. Known filenames and extensions use native static dispatch—no metadata load, glob construction, registry scan, or heap allocation.

Local release measurement	Previous registry	Native registry	Change
Known .go extension classification, 1,000,000 calls	4.477 s	25.431 ms	176.0× faster; 99.4% lower
Rust initial index, 2,000 declarations	13.283 ms	12.395 ms	6.7% lower
Rust query	226.709 µs	175.833 µs	22.4% lower
Generic Go initial index, 2,000 declarations	1.814 ms	1.676 ms	7.6% lower
Generic Go query	119.375 µs	117.625 µs	1.5% lower
Clean default release binary	8,107,984 bytes	8,090,240 bytes	17,744 bytes smaller
Clean default release build	10.00 s	8.86 s	11.4% lower, n=1

The rows above are local regression evidence. The fixture timings are medians of five interleaved warmed release runs except the one-run clean-build result; hardware, filesystem, and corpus shape matter. The generic Go extractor caps declarations at 256, so it is not an AST-for-AST comparison. The direct-classification result is the relevant hot-path regression gate.

What Bread does

Capability	Contract
Bounded search	Ripgrep-compatible search crates run in-process with ignore-aware discovery and structured, capped results
Safe reads	Ranged reads and Tree-sitter outlines keep useful source context smaller and attach freshness information
Edit safety	Restricted paths are denied before disk access; stale edits are blocked and recover through a narrow reread
Prompt context	Eligible technical prompts can receive provenance-tagged, budgeted, session-deduplicated context; vague or instruction-like prompts remain silent
Local codebase index	Exact symbols, lexical chunks, declaration-aware structure, and tested one-hop local import/dependent expansion stay in .bread/
Optional semantic retrieval	With an explicit semantic build and opt-in, local vector candidates are fused with lexical results; any semantic failure falls back to lexical retrieval

Codebase indexing

Bread provides a measurable, workspace-local indexing capability. It does not claim to reproduce any proprietary indexer.

• 115 language identifiers: native recognition covers conventional filenames, compound suffixes, extensions, Emacs modelines, shebangs, and selected content signatures.
• Native structural tier: Rust, Python, JavaScript, and TypeScript/TSX use Tree-sitter declaration ranges, syntax status, and tested local imports.
• Bounded structural tier: other recognized languages get conservative declaration-aware chunks; unknown text stays searchable through the lexical tier.
• Atomic generations: readers receive a complete prior index or a complete replacement, never a half-updated graph. Deleted and stat-mismatched chunks are excluded.
• Narrow graph rules: only tested repository-local imports expand a result; package, URL, absolute-path, standard-library, and bare-import edges are not guessed.

Read the full indexing contract for language coverage, freshness behavior, privacy boundaries, and the 240-case local Codex adapter matrix. On the recorded Apple Silicon fixture, the initial two-file index took 1.213 ms, a single-file replacement took 0.147 ms, and 128 retrieval samples measured 0.040 ms p95. Those fixture measurements are comparative evidence, not a CI gate or a corpus-wide SLO.

Scope is deliberately bounded

For Codex, Bread registers these documented events:

• SessionStart for startup, resume, clear, and compact;
• PreToolUse and PostToolUse for Bash and apply_patch; and
• UserPromptSubmit for prompt-context eligibility.

That is not a universal interceptor. Bread cannot guarantee that every user prompt, agent prompt, tool call, provider path, or Codex version is observed or changed. Unsupported events, disabled or untrusted hooks, malformed input, daemon failure, and hook timeouts fail open to native agent behavior.

The safety boundary is intentional:

• Deny and ignore rules run before indexing or context assembly.
• The default build has no semantic-model download or extra runtime language catalog.
• The hook does not run compilers, language servers, external classifiers, or network downloads.
• A missing daemon, parser error, corrupt semantic checkpoint, or unavailable optional asset leaves the strongest safe lower tier available.

Commands

Command	Purpose
bread install codex	Add only Bread-owned project Codex hook entries
bread uninstall codex	Restore the private backup or remove only Bread-owned hook entries
bread status	Report daemon state plus index generation, coverage, record counts, and semantic-checkpoint presence
bread scorecard	Run the deterministic default-feature evidence scorecard
bread inventory	Print a bounded, metadata-only JSON overview of the workspace: file categories, byte totals, an estimated text-token cost, and a top-level directory breakdown
bread index --semantic --query "..."	Build/query optional local semantic retrieval after rebuilding with the semantic feature
bread run -- command	Run a command and compact its standard output

bread inventory is a manual, metadata-only overview. It classifies files by name and extension, reads non-following filesystem metadata, and never opens file contents, follows symlinks, builds the index, calls a model, or touches the network. It applies the same boundaries as the rest of Bread — ignore rules, hidden-file policy, .git/ and .bread/ exclusion, and denied paths — before counting, and reports only bounded aggregates, never individual paths. Use it for broad orientation in an unfamiliar workspace; use search and ranged reads for specific code. It does not enable automatic media or document extraction. On Codex, a single static session-start cue points agents at the command; no workspace data is injected.

Integration status

Agent surface	Current status
Codex CLI	Live-validated release target in the shared isolated sandbox
Claude Code	Project adapter is implemented; live CLI validation is deferred
Grok Build	Project and user-hook adapters are implemented; live CLI validation is deferred

Bread does not install, upgrade, remove, or modify globally installed agent CLIs. Live integration testing stays isolated from the host’s credentials and configuration.

Verify a release

cargo fmt --all -- --check
cargo test --all-features
cargo clippy --all-targets --all-features -- -D warnings
cargo run --quiet -- scorecard
scripts/codex-release-smoke

The semantic tier is opt-in. Build it only when validating that feature, then enable its smoke explicitly with BREAD_SEMANTIC_SMOKE=on after the local model is available.

For release, rollback, hook-trust, and compatibility details, see Codex release, codebase indexing, and Grok Build.