branchgraph/docs/design.md

Branch Graph — product design

2026-10-09, revision 5. Revision 3 (the live graph, now built) is in git history.

Value

A lead has ten branches open, by people and by agents. Each one has to end merged, fixed, or sent back with clear instructions. Today that takes a GitHub review, a copied link, a paragraph to the agent explaining what to do with it, a checkout and a run, for every branch.

Branch Graph shortens that loop to one screen per branch: see what the branch changes (diff --stat first, then the diff), run it in its own worktree with one key, write comments on lines, files or commits, and send them to a coding agent working in that worktree. The graph of branches stays, as navigation.

Revision 3 answered "where are the branches". It drew topology well and stopped at "copy this command". The owner's review found the gaps: no branch-level diff, no diff --stat, no way to run a branch, no path from a comment to an agent.

User and loop

The user is a git CLI power user who runs coding agents (opencode, Claude Code) in parallel. The loop, per branch:

1. Pick: the queue shows which branches need them: new commits since they last looked, then conflicts or failing CI, then recency.
2. Understand: diff --stat against the fork point, grouped by directory, then the diff of any file; the commits if the story matters.
3. Try: a worktree for the branch, created on demand, never touching the user's own checkout; the project's run command started there, output on the page.
4. Act: comment on a line range, a file, a commit or the branch. The comments form the branch's brief. Send the brief to the agent, which works in the same worktree. Or check the merge preview and merge from the label's menu.
5. Follow: the agent's commits appear live in the branch; the brief marks which comments were sent.

Screen

One screen, review-first. Layout at 1440 × 900:

• Top bar, 48 px: repository, Base selector, filter field (name or @author), live dot, fetch. Base is the branch "All" compares with: main, or any open branch, then the stat and diff show what the branch adds since it split from that one, as a pull request into it would. It stays while the user moves between branches. Off main it turns amber, and a line above the stat says "Compared with feat/x, not main · use main": a review against the wrong base is costly.
• Rail, 400 px, left: the commit graph, as gitk or git log --graph draws it, so the user sees how every branch ties back to main. One row per commit, newest first; main in the first column, each branch in its own column, forks and merges drawn. Main between fork points and merges folds into a count (+37); a branch shows its newest 30 commits. Branch tips carry a label: state on its border (red conflicts, amber CI failing, green ready), an accent dot for commits not seen yet. Lines stay neutral; the selected branch's rows and nodes take the accent. A label opens its menu, as gitk's branch heads do: Review, Check out, Merge into (the branch checked out in the user's checkout), Preview merge, Compare the open branch with this, Copy name; a modified click opens the branch in a tab; a commit opens it narrowed to that commit; j/k move between branch labels. The graph waits while the pointer is on it. Hollow nodes are not pushed. "3 merged or stale · show" at the bottom; the filter field (name or @author) redraws the graph for the matching branches.
• Stat, 300 px:
  • Header: branch name; one muted line: author · PR #182 draft (or no PR) · worktree path when there is one. Two commands on the name line: Run and Send (n), n the number of draft comments.
  • Toggle "All vs | Since last review". "Since last review" is the default when the branch moved since the user last reviewed it, typically after an agent pushed.
  • The changed files against the merge base, grouped by directory: +a −r per file, a thin bar on directory rows, churn order inside a directory, lock files in a muted group at the end.
  • A commit picked in the graph narrows stat and diff to it, with "a11c09e · clear" above the files.
• Diff, rest of the width: every file, one scroll, in the stat's order, each under a sticky header (path, counts, comment on file). A file clicked in the stat scrolls to the top of the pane; the stat marks the file being read as the pane scrolls; [/] step between files. The pane holds the first 200 KB of the diff; a file past that shows "Load diff", which loads it alone (up to 2 MB). Drag down the line numbers to select lines; the comment box opens on release. Drafts sit inline under their lines. ⌘↵ saves a draft; esc closes the box and keeps the text.
• Drawer, under stat and diff: closed, one 28 px status line (the run command, "running", "port 20431" as a link to the app, "agent idle"), hidden until something ran. Open (o), 280 px: Run and Agent tabs on the left, the output on the right. Stop is the Run button in the stat header, which turns into Stop while the run lives.
• Send dialog, 760 px, centred: the review as it will go out, compact like a submitted GitHub review. Header: branch, "5 comments on 3 files", base and the tip reviewed. Tabs: Review, Markdown (the exact brief). Review: the instruction, then the comments grouped by file in line order, each with its spot (L40–52, file, commit), a short excerpt and its text; branch and commit comments last. Every text is editable in place and saves as you type; each comment can be deleted. Actions: Copy brief (paste it into a running agent session), then Mark as sent so it does not go out twice (the page's way to do what branchgraph brief --ack does for an agent); Send to agent (⌘↵) runs the agent command in the worktree. The footer says where the agent runs. It refuses while a comment box in the diff is still open, or an agent job runs in that worktree.
• Comments written on an older tip show "outdated".

Keys

j/k branch, [/] file, r run, s send, o drawer, m merge preview, p pause the live graph, / filter, ? keys; ⌘↵ saves a comment or sends, esc closes a box, dialog or menu.

Actions

Action	What it does
Worktree (implicit)	Run and Send need one: reuse the worktree where the branch is checked out, else create <clone>.worktrees/<slug> with gix (a remote-only branch gets a local tracking branch). On creation, copy the untracked files named by branchgraph.copy (for example .env*) from the main worktree, then run branchgraph.setup once.
Run	branchgraph.run in the worktree, one per branch, BG_PORT stable per branch. Output in the drawer, last 2 000 lines. Stop sends SIGTERM to the main process only, SIGKILL 10 s later; the command (a dev.sh) decides what else stops.
Comment	On a line range, a file, a commit or the branch; a draft until sent.
Send	Writes the brief, runs branchgraph.agent in the worktree, marks the drafts sent. One agent job per worktree at a time.
Merge preview	m: the merge preview, with copy-commands.
Check out	From a label's menu: git switch in the user's checkout (a remote-only branch gets a tracking branch). Refused over modified tracked files, from a detached HEAD (its commits would be left unnamed) and for a branch checked out in another worktree. Says so when the local branch is not at the tip shown.
Merge into	From a label's menu: git merge of the tip the page shows into the branch checked out in the user's checkout. Refused over modified tracked files or on a detached HEAD; a conflict is aborted at once and its files listed, so the checkout is never left mid-merge. Never pushed.

Commands: the branch's .branchgraph

Settings travel with the code, in .branchgraph at the repository root, git-config syntax:

[branchgraph]
	run = cd recordum && bash localdev.sh
	setup = cargo fetch
	copy = .env*
	agent = opencode run -c -f "$BG_BRIEF" "Apply the review in the attached brief."
	verify = cargo test

Read for the branch being run: the file in its worktree (an edit counts before it is committed), else as committed on the branch, else main's. No git-config source, so a setting is never one person's machine only.

Settings (the gear in the branch header) opens the file in an editor and saves it into the branch's worktree (made if needed). It is the only file branchgraph edits; the user commits and pushes it.

A branch can change what Run executes. When its commands differ from main's, Run (or Send) shows them in the drawer and asks once; "Run it" approves what was shown for that branch, so a command that arrived since is asked about again. Copying files into a new worktree (copy) counts as a command. Commands the user saved in the editor count as approved.

Each command runs with sh -c in the worktree. Values reach it only as environment variables: BG_BRANCH, BG_SLUG, BG_WORKTREE, BG_BRIEF, BG_PORT. The default agent command continues the worktree's last opencode session, which is the agent that wrote the branch, not a stranger.

The server prints every command it runs, its directory, its output (one line per output line, prefixed with the branch) and its exit status to the terminal it was started from. A refused Run or Send shows its reason in the drawer.

Brief

A Markdown file an agent acts on without a follow-up question:

• branch, base, merge-base sha and the tip sha reviewed, so it can detect drift;
• the overall instruction, what done means, the verify command (branchgraph.verify; without it, "run the project's tests"), and the push rule (default: do not push);
• each comment: anchor (src/fleet/vehicle.rs:40-52 @ a11c09e2), code excerpt, text;
• rules: one commit per comment citing its anchor; skip an ambiguous comment and say why rather than ask.

As an agent skill

skill/branchgraph/SKILL.md lets opencode or Claude Code use the tool. The CLI reads the repository and the state directory directly; open and run-log need the server.

• branchgraph open [branch] starts the server for the repository if none runs (detached, port file in the state directory) and prints the URL, so an agent can end with "review here: URL".
• branchgraph queue prints the queue with each branch's stat.
• branchgraph brief [branch] prints the unsent brief; the branch defaults to the one checked out in the current directory. --ack marks it sent once the agent has acted.
• branchgraph run-log [branch] prints the run output, so the agent reads the error without the user copying it.

Trust boundaries

• Commands come from the branch's .branchgraph; one that main does not run is asked about once before it runs, so a teammate's branch cannot run new code on a click without the user seeing it.
• Run executes the branch's code; it starts only on the user's click or key.
• Every route needs a per-launch token: the printed URL carries it once and the browser keeps it as an HttpOnly, SameSite=Strict cookie named per port. The server binds 127.0.0.1, where it also checks the Host name; --bind 0.0.0.0 listens on the network over plain HTTP, accepts any Host, still requires the token and a same-origin Origin, and warns at start.
• Writes to the clone: fetch, worktree creation and the local tracking branch it needs, and Check out or Merge in the user's checkout from a branch's menu, on that click only. Never a rebase, push or branch delete. Agents write in their worktree; that is their job.
• Briefs, review state and logs live in $XDG_STATE_HOME/branchgraph/<repo id>/ (default ~/.local/state), written atomically.

Data

Data	Source	Bound
Branch stat	Tree diff of merge base and tip, line counts per file	1 000 files; blobs over 1 MB counted as changed, not diffed
File diff	Blob diff, every file loads with the page	200 KB for the pane; 2 MB for one file loaded alone
Queue rank	Seen commits (state dir), conflicts, PR state	—
Run output	Child process	2 000 lines per run, one run per branch
Agent job	Child process	Last job per branch, 2 000 lines

Scope of this milestone

In: the one-screen review (rail, stat, diff, drawer, send sheet), comments and brief, implicit worktrees with copy and setup, Run, Send through the command template, the commit graph in the rail, the CLI subcommands and the skill file.

Not yet (owner, 2026-10-08): posting reviews to GitHub. Later: replies from the agent inline, several agent targets per branch, n/p hunk keys.