Braid turns GitHub Issues and pull requests into durable working memory for local Coding Agents. GitHub holds the current design, implementation state, metadata, relationships, and discussion; Braid rebuilds a provider session from that state whenever prior context becomes stale.
Braid is implemented as one Rust package and one portable braid binary.
On macOS arm64:
brew install xiaoland/braid/braidbraid setup creates your own GitHub App, persists credentials outside the
repository, and writes a starter instance config. The full setup guide is in
docs/user-manual/setup.md.
braid setup owner/repository --provider pi --model deepseek-chat --api-key-environment DEEPSEEK_API_KEYThe command opens a browser for GitHub's App Manifest flow, receives the
redirect locally, and saves the App private key and webhook secret under
~/.braid/instances/<key>/ (the instance key defaults to the repository
owner). After the browser installs the App on your repository, run Braid
against that instance:
braid doctor --instance <KEY>
braid serve --instance <KEY> --tunnelThe active product and implementation contracts are:
- Product Truth
- Real end-to-end acceptance
- Rust Product TDD
- GitHub Context
- Event/session lifecycle
- Codex provider contract
- GitHub boundary
- Deployment and observability
- Glossary
The first supported delivery target is a packaged macOS arm64 binary; Linux x86_64 follows. Build and inspect the public operator surface with:
cargo build --locked
cargo run --locked -- --version
cargo run --locked -- config check --config /absolute/path/to/config.toml
cargo run --locked -- migrate plan --config /absolute/path/to/config.toml
cargo run --locked -- github probe --config /absolute/path/to/config.toml --repository owner/repository
cargo run --locked -- context issue owner/repository#123 --config /absolute/path/to/config.toml
cargo run --locked -- gh comment create owner/repository#123 --config /absolute/path/to/config.toml --profile issue-codex --body 'Concise update'
cargo run --locked -- gh pr ensure --comment 123456789 --config /absolute/path/to/config.toml
cargo run --locked -- serve --config /absolute/path/to/config.toml --tunnel
cargo run --locked -- serve --config /absolute/path/to/config.toml --transport-only
cargo run --locked -- status --config /absolute/path/to/config.toml --jsonApply all pending migrations before context; the local canonical ledger keeps
only mechanical versions, associations, and deleted-comment tombstones while
GitHub remains the content authority.
The diagnostic --page-size defaults to GitHub's maximum of 100; real campaign
helpers may lower it to force pagination while requiring byte-identical Context.
serve owns the configured Codex app-server and Issue Agent turns;
--transport-only deliberately stops at verified webhook ingress, canonical
reconciliation, reactions, and runnable debounce batches. --tunnel adds the
free supervised Quick Tunnel to either mode.
braid gh is the Braid-App-authored write surface. Comment creation prepends
the configured public Profile/role attribution and returns a durable receipt;
pr ensure uses the triggering Issue comment ID as its concurrency-safe
Implementation Request key.
Copy config.example.toml outside the checkout and
replace every placeholder path before running diagnostics, or let braid setup
generate an instance config for you. A packaged release
does not require Python, PDM, Cargo, or a source checkout.
Braid deliberately avoids a large internal fake/unit-test surface while the
workflow is being established. Diagnostic and real black-box campaign helpers
belong under scripts/tests/, but retained GitHub/provider/
OTel evidence and Human verdicts remain the acceptance oracle.