Braid

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.

Install

On macOS arm64:

brew install xiaoland/braid/braid

Bootstrap

braid 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_KEY

The 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> --tunnel

The 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 --json

Apply 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.