Introduction

Start here

The Codex CLI path is Bread’s current live-validated release gate. The latest release bootstrap downloads a platform archive and verifies its SHA-256 digest:

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

For a reproducible install, use an immutable release tag for both the installer script and release asset:

curl -fsSL https://raw.githubusercontent.com/Yabuku-xD/bread/<release-tag>/scripts/install-bread | sh -s <release-tag>

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.

Where Bread fits

Codex CLI
    │
    │ documented SessionStart, PreToolUse, PostToolUse, UserPromptSubmit events
    ▼
Bread hook and per-workspace daemon
    │
    ├── bounded search and read output
    ├── stale-edit and restricted-path checks
    ├── provenance, relevance gates, and session deduplication
    └── local lexical, structural, and optional semantic retrieval
    ▼
Native agent tools and the workspace

Unsupported events, untrusted or disabled hooks, malformed input, daemon failures, and timeouts fail open to native agent behavior. Bread is a bounded policy and context layer, not a universal interceptor.

What Bread changes

Bread uses ripgrep-compatible search crates in-process for search parity. It does not promise to outperform standalone rg at raw search throughput; its value is the bounded, safe agent workflow around that engine.

Evidence, not marketing arithmetic

All numbers below are local fixtures or matched sandbox measurements. They share a repository snapshot, policy, Codex CLI 0.144.3, gpt-5.6-terra, and low reasoning effort where stated. Sample sizes are intentionally visible because small samples and agent tool-choice variance do not establish universal outcomes.

The deterministic scorecard is deliberately narrower than the sandbox rows: it runs 128 synthetic PreToolUse pass-through decisions for a Bash ls event and reports Rust Instant percentiles; its replay reduction compresses a fixed 240-line output fixture and estimates tokens as characters divided by four. The rows labeled local sandbox n=… are separate matched observations, not scorecard medians. The five warmed release-run median described in the indexing contract applies only to its 2,000-declaration indexing fixture.

The slower README inspection is important: Bread may add hook and decision overhead to a small direct read. It earns that cost only when it removes enough downstream context, repeated work, or unsafe state to repay it.

Run the default evidence scorecard yourself:

cargo run --quiet -- scorecard

Capabilities

Bounded search, reads, and edits

• Search: ripgrep-compatible search crates, ignore-aware discovery, and structured output limits.
• Reads: ranged reads and Tree-sitter outlines preserve useful source context while attaching freshness information.
• Edits: deny rules run before disk access; stale patches are stopped before they can overwrite changed content.
• Prompt context: eligible technical prompts can receive provenance-tagged, budgeted, session-deduplicated context. Vague or instruction-like prompts remain silent.

Workspace-local codebase indexing

Bread makes a deliberately narrow, inspectable index instead of claiming to replicate a proprietary indexer.

The static registry recognizes 115 language identifiers by filename, compound suffix, extension, modeline, shebang, or selected content signature. Known filenames and extensions use direct static dispatch: no runtime catalog, glob construction, registry scan, or heap allocation on that path.

Only tested repository-local imports expand a result. The index does not guess package, URL, absolute-path, standard-library, or bare-import edges. Complete generations are published atomically, so readers get the previous complete index or its replacement—not a half-updated graph.

Read the complete indexing contract →

Optional semantic retrieval

Exact symbols and lexical candidates are always available. With an explicit semantic build and opt-in, local vector candidates are fused with lexical results. A missing model, corrupt checkpoint, or semantic failure leaves the lexical tier available.

The default build does not download a semantic model or add a runtime language catalog. Build the opt-in tier only when validating it:

cargo build --features semantic --locked
./target/debug/bread index --semantic --query "authentication flow"

Hook scope and safety

For Codex, Bread registers:

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

These boundaries are deliberate:

• Ignore and deny rules run before indexing or context assembly.
• Restricted paths never enter index records or prompt context.
• When an installed, trusted, and healthy Bread hook evaluates a request, restricted paths are denied before disk access. Disabled or untrusted hooks, malformed input, daemon failures, and timeouts fall open to native behavior; Bread policy does not execute in those cases.
• Hooks do not run compilers, language servers, external classifiers, or network downloads.
• Missing daemons, parser errors, and unavailable optional assets fall back to the strongest safe lower tier.
• The current Codex matrix has 200 local adapter cases: restricted-path denials, safe pass-throughs, concise and oversized outputs, eligible injections, and vague-prompt no-injection checks.

Commands

bread inventory is manual and metadata-only. It classifies files by name and extension and reads non-following metadata; it never opens contents, follows symlinks, builds the index, calls a model, or uses the network. Ignore rules, hidden-file policy, .git/ and .bread/ exclusion, and denied paths apply before counting, and only bounded aggregates are reported — never individual paths. Reach for it to orient in an unfamiliar workspace, then use search and ranged reads for specific code. It does not enable automatic media or document extraction. On Codex, one static session-start cue advertises it without injecting any workspace data.

Integration status

Bread does not install, upgrade, remove, or modify globally installed agent CLIs. Live integration testing stays inside an isolated sandbox with the cheapest capable model.

Release checklist

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 smoke is opt-in:

BREAD_SEMANTIC_SMOKE=on scripts/codex-release-smoke

Deep dives

• Codex release path: installation, trust, rollback, and release checks
• Codebase indexing: language recognition, graph boundaries, freshness, and validation
• Grok Build: documented hook capabilities and disposable validation