Codex release guide

Bread is distributed as a standalone local binary plus an optional Codex plugin hook surface. This keeps the binary, daemon lifecycle, and native rollback local while Codex owns plugin installation and hook trust.

Install

For a reproducible published release, replace <release-tag> with the exact tag to install. The installer verifies the downloaded archive against that release's SHA256SUMS file before placing the binary on your PATH.

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

To install the newest release rather than a pinned version:

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

Codex plugin

After the binary is available on your PATH, 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 target repository, open /hooks, and review/trust Bread's exact command hook. The plugin invokes the installed bread binary; it never downloads or executes a binary itself.

Project-local hook alternative

Use this instead of the plugin path when you want Bread configured only for the current repository:

bread install codex

The installer adds only Bread-owned entries to .codex/hooks.json and stores a private pre-install backup under .bread/. It preserves unrelated hook entries and is safe to run again. Do not use it with the plugin path: both hook surfaces would run the same Bread policy twice.

Build from an immutable revision

git checkout <release-tag-or-commit>
cargo install --path . --locked

When testing a particular revision through the plugin path, add --ref <release-tag-or-commit> to the marketplace command above.

After installation:

1. Start Codex in the target repository.
2. Open /hooks.
3. Review and trust the exact Bread command hook.
4. Run a harmless Bash command and the non-destructive restricted-path fixture below.

The reviewed configuration has one Bread command hook for each of these event bindings. Its command ends with hook codex; the absolute binary path is installation-specific.

Start a normal Codex session in the target repository first so the workspace daemon is available, then run this adapter fixture. It only submits JSON to Bread; it never creates or edits .env.

printf '%s\n' '{"hook_event_name":"PreToolUse","tool_name":"apply_patch","tool_input":{"file_path":".env"}}' \
  | bread hook codex

The output must contain permissionDecision set to deny. If it is empty, the hook or daemon is unavailable and Codex will use native behavior instead.

Codex requires review of non-managed project hooks and re-review when their definition changes. Bread never bypasses that trust boundary in normal use.

Rollback

Remove the marketplace-installed plugin with:

codex plugin remove bread@bread

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

bread uninstall codex

Uninstall removes only Bread-owned hook entries from the current configuration, preserving unrelated entries and changes made after installation. It then removes Bread's private backup; rollback is configuration-safe rather than a byte-for-byte restore.

Release checks

Run before publishing a release:

cargo fmt --all -- --check
cargo test --all-features
cargo clippy --all-targets --all-features -- -D warnings
cargo run --quiet -- scorecard

Then rebuild the semantic-enabled binary only when validating the opt-in tier, copy it into .bread/cli-sandboxes/codex, and run the cumulative Codex smoke with the cheapest capable model (gpt-5.6-terra, low reasoning). The default smoke remains model-download-free; opt into semantic smoke explicitly with BREAD_SEMANTIC_SMOKE=on after its local model is available.

The deterministic release smoke is:

scripts/codex-release-smoke

Security and compatibility

• Hooks fail open when the daemon is unavailable or unhealthy.
• Restricted paths are denied before disk access only when an installed, trusted, healthy hook successfully evaluates Bread policy. A fail-open path leaves the native tool behavior in control.
• Unsupported Codex fields remain pass-through.
• updatedInput is emitted only with permissionDecision: allow.
• UserPromptSubmit injection is conservative, provenance-tagged, budgeted, and disabled by BREAD_INJECT=off.
• SessionStart returns one static cue that advertises bread inventory. It carries no workspace data, runs no filesystem scan, and does not change the UserPromptSubmit decision path.
• bread inventory is a manual, metadata-only overview: it classifies files by name and extension, reads non-following metadata, applies the same ignore, hidden-file, .git//.bread/, and denied-path boundaries as retrieval, and reports only bounded aggregates. It never opens contents, follows symlinks, builds the index, calls a model, uses the network, or extracts media or documents.
• bread status exposes the persisted index generation, schema, coverage, record counts, and semantic-checkpoint presence without exposing source.
• Do not put OAuth tokens, credentials, or sandbox state in the repository.

Distribution decision

Bread supports both release binaries and the Codex marketplace. The binary owns daemon state and policy; the marketplace plugin owns the reviewed hook surface. Keeping those layers separate preserves fail-open behavior and avoids silent binary downloads from plugin installation.