branchgraph/AGENTS.md

branchgraph

Job: let a lead review every open branch of one repository fast: see what a branch changes (diff --stat, then the diff), run it in its own worktree, and send comments on lines, files or commits to a coding agent working there. The branch graph is the navigation. It changes the user's own checkout only on an explicit Check out or Merge in a branch's menu.

• Product design: docs/design.md (source doc: https://claude.ai/code/artifact/f81e88f0-1704-4ff7-9427-293ba42d312c).
• Target look: docs/mockup.png (screenshot of the build, demo repo).

Owner decisions (2026-10-08)

• Binary and crate name: branchgraph. The folder stays gitui; the name gitui clashes with the TUI installed at /usr/bin/gitui.
• Architecture: option A of the design, a local binary that serves the page on localhost. The artifact prototype (milestone 1) is skipped.
• Work starts at milestone 2. The LLM ask box is milestone 3: do not build it yet.

Owner decisions (2026-10-08, revision 4)

• The product is the review loop, not the graph (owner: "I can browse branches but that's it").
• Writes allowed: worktree creation (and the local tracking branch it needs), and running the configured run command in that worktree. Still never: checkout in the user's worktree, merge, rebase, push, branch delete.
• "Send to agent" runs a user-set command template (agent in the branch's .branchgraph, see the hard rules), any agent CLI; values only as environment variables.

Owner decisions (2026-10-09)

• .branchgraph settings: see the hard rules.
• Clicking a branch label opens a menu, as gitk does: Review, Check out, Merge into the branch checked out in the user's checkout, Preview merge, Compare with this, Copy name.
• Base selector in the top bar: the branch "All" compares with (merge base with it), main by default, kept while moving between branches and shown in amber whenever it is not main.

Current milestone: 3, the review loop

Scope: docs/design.md, revision 5. Milestone 2 (the live graph) is built and becomes the graph overlay and the data layer.

Gate (done when a test shows it):

• A branch's stat equals git diff --numstat -M <merge-base> <tip> for every branch of a fixture repo.
• Run or Send on a remote-only branch creates a worktree that git worktree list shows, on a local branch tracking origin; the user's checkout (HEAD, index, status, local branches) is unchanged; branchgraph.copy files are copied and branchgraph.setup ran once.
• Send runs branchgraph.agent in the worktree with the BG_* variables; the brief holds every draft with its anchor and excerpt; a branch name holding shell syntax runs nothing extra; the drafts are marked sent.
• Stop sends SIGTERM to the run's main process (a trap in the script shows it).
• POST endpoints and run output refuse requests without the page token.
• branchgraph brief prints the unsent brief of the current worktree's branch; --ack marks it sent.

Hard rules

• Writes to the clone: fetch (objects, remote-tracking refs and their reflogs; never prune, wait while a *.lock exists) and worktree creation. Merge previews run in object memory. Check out and merge touch the user's checkout only from a branch's menu: refused over modified tracked files, a conflicting merge is aborted, never in another worktree, never pushed. gix cannot switch or merge a working tree yet, so these two run the git CLI with arguments, never a shell. No rebase, push or branch delete.
• Commands (run, setup, copy, agent, verify) come from the branch's .branchgraph (owner, 2026-10-09): the file in its worktree, else as committed on the branch, else main's. No git-config source: settings are shared through the repository, not kept per machine. A command the branch adds over main's is shown and asked about once before it runs; one the user saved in the page counts as approved. Commands start only on a user action, and every route needs the page's per-launch token.
• .branchgraph is the only file branchgraph edits in a checkout, saved from the page into the branch's worktree. It never commits or pushes it.
• Bind 127.0.0.1 by default. --bind <ip> (owner, 2026-10-08) listens wider, for example 0.0.0.0: then any Host is accepted, every route still needs the token, an Origin must match the Host, and startup warns that the page is plain HTTP and can run code.
• Network: only git fetch and the GitHub API. No other host, no telemetry. branchgraph calls no LLM; the agent it starts is the user's own tool.
• GitHub token: read from GH_TOKEN (run as GH_TOKEN=$(gh auth token) branchgraph). Never log it, put it in a URL or write it to disk. Without a token, draw the graph without PR labels and say so on the page.
• Native libraries over shelling out: read and fetch with gix. Tests may use the git CLI to build fixture repos and to check results.
• Bounded work: cap commits per lane, diff size (200 KB for the diff pane, 2 MB for one file loaded on its own) and API pages.

Default stack

Change only with a stated reason: gix, tokio + axum, maud for HTML, SVG drawn on the server, clap for arguments, reqwest for one GitHub GraphQL query (PRs with draft, mergeable and review state). Little or no client JS.

Approved additions (2026-10-08): serde + serde_json, futures-util, anyhow, tempfile (dev).

Ask the owner before adding a dependency outside this list, calling another host, or writing to the repository.

Workflow

• UI work (comps, templates, CSS, client script, UI review): read .agents/skills/quiet-ui/SKILL.md first and keep to its budgets. Design canvas: https://claude.ai/artifact/Jxue8Rvy2AayN9xDDvcCwV
• cargo fmt, cargo clippy --all-targets -- -D warnings, cargo test. Zero warnings.
• Prove each behavior with the smallest test. Build fixture repos in temp directories.
• Comments explain why, never what.
• Commits: short subject and tight bullets. Never add Co-Authored-By or other AI attribution anywhere
• Use the code review skill ./.agents/skills/code-review/ in a loop until satisfied