byre/docs/operations.md

Operations

Layout

• cmd/byre: byre serve runs the server; byre run drives one Claude session in the current directory from the terminal.
• api/openapi.yaml is the API source of truth. go generate ./internal/api regenerates internal/api/api.gen.go, whose types are also the store's model types.
• internal/store: SQLite (WAL). Every mutation and its event commit in one transaction; events are published to SSE subscribers in seq order.
• internal/server: HTTP handlers, identity, SSE, the worktree file browser (see "Files"), terminals (see "Terminals").
• internal/git: worktrees, the task changes view (see "Changes"), snapshots (see "Snapshots"), unmerged-change summaries, squash merges, merge notes and pushes.
• internal/agents: the agent session manager. It owns the running agent processes, task agents, lead agents (see "Lead agent") and reviewers (see "Reviews") alike, and records their activity as events.
• internal/claude: the Claude Code stream-json client (see docs/claude-protocol.md).
• internal/codex: the codex app-server JSON-RPC client, with types generated from the CLI's schema by go generate ./internal/codex (see docs/codex-protocol.md).
• internal/tailscale: tailscale serve for task previews (see "Previews").
• internal/workflow: validating workflow definitions and reading and writing their YAML files (see "Workflows").
• web/: the SPA, frameworkless TypeScript compiled file-by-file to ES modules (no bundler). web/src/*.ts is the source; web/src/api.gen.ts holds types generated from api/openapi.yaml, and web/src/api.ts is the typed client over them. go generate ./web runs npm ci, regenerates the types and compiles web/dist/, which is committed so go install needs no Node. The binary embeds index.html, style.css, dist/, src/ (for source maps), fonts/ and vendor/ (Mermaid, see "Inbox"; xterm.js, see "Terminals"). byre serve --dev serves ./web from disk instead (run from the repo root); pair it with npm --prefix web exec tsc -- --watch.

Data

State lives in the directory given by byre serve --data, by default the byre directory under Go's os.UserConfigDir() (on macOS, ~/Library/Application Support/byre): byre.db, worktrees/<project-id>/<task-id>, leads/<login> (each lead agent's working directory, the login path-escaped), and blobs/<blob-id> (uploaded images; the blobs table maps each id to its content type and its path relative to this directory). Task branches are byre/<task-id> in the project's repo.

Schema changes are the migrations slice in internal/store/store.go: named entries, each with a short kebab-case name saying what it does. On open, byre applies, in slice order, every entry whose name isn't in the migrations table, each in its own transaction that also records the name. Each runs with foreign keys off, so a migration can rebuild a table other tables reference, and PRAGMA foreign_key_check must come back empty before it commits. byre is deployed from task branches that each append their own migrations, so after a merge a migration can land before others the database has already applied, and it still runs. Give a new migration a name no other branch will use, and make any data migration safe to run twice. sqlite3 byre.db 'SELECT * FROM migrations' lists what has been applied. A database from before the table existed is moved over on open: the first PRAGMA user_version entries are recorded as applied, and user_version is no longer read or written.

Worktree setup and ports

Every task worktree is made by createTask (internal/agents/tasks.go): new tasks, create_task, start_todo and forks alike.

• Ports. Each active task holds a block of store.PortBlock ports starting at tasks.port_base (port_base on the Task). Store.CreateTask gives a new task the lowest block from byre serve --ports (default store.DefaultPortFirst) up that no active task holds, so a merged or discarded task's block is reused. The agent's claude process gets PORT (the first port, which most dev servers read on their own), and the session guidance names the range, says to run dev servers on it listening on 127.0.0.1, and points at expose_port (see "Previews"). sqlite3 byre.db "SELECT id, port_base FROM tasks WHERE status = 'active'" lists the blocks in use.
• Setup. byre runs nothing in a new worktree. The session guidance says the worktree starts with only what git tracks and tells the agent to do any setup the project's AGENTS.md describes before other work, so installing dependencies or copying untracked files such as .env is the project's own instruction, carried out by the agent with its own tools. A project's checkout is the parent of git rev-parse --path-format=absolute --git-common-dir in the worktree.

Closing a task

A task ends merged or discarded; either way its sessions are stopped, its snapshot refs, worktree and branch are removed, its open inbox items become dismissed (resolved by whoever closed it), and its record and events remain. GET /api/tasks/{id}/unmerged reports what would be lost or merged: commits on the branch that aren't on the default branch, and files, lines and uncommitted paths that differ from the merge base. The UI's Merge and Discard buttons each ask a confirmation (Merge's holds the editable commit title), opened just below the button like the task picker's switcher (centred when ⌘S opens Merge's from a tab without the button), and are disabled while the task's session is running. Merge is also disabled until unmerged reports a commit or a changed file; the transcript fetches it when the task is opened and again shortly after each tool result or turn end.

POST /api/tasks/{id}/merge-in (the transcript's Sync from main button, labelled with the default branch) brings the default branch into the task branch through the agent: it sends mergeInPrompt (internal/agents/mergein.go) as a byre message to the task's session, or starts a session with it when the task has none. The prompt has the agent run git merge --no-ff --no-commit, resolve conflicts, regenerate generated files rather than hand-merging them, check the build and tests, and leave the merge uncommitted; byre's end-of-turn commit concludes it as a merge commit. If resolving the conflicts took substantive changes rather than combining both sides as written, the prompt tells the agent to stop there and end its turn describing them; the turn's snapshot then gets its review like any other (see "Reviews"). byre doesn't inspect the merge itself: whether a change is substantive, and whether to stop, is the agent's call. On a Merge turn the prompt adds that byre squashes and pushes when the turn ends, and tells the agent to call the stop_merge MCP tool first if it stops (see below). The prompt ends by showing the task's current merge title and asking the agent to set a better one with set_merge_title if it no longer describes all the work on the branch. It is refused (409) while a session is running.

A task's merge_title is the title of the squash commit Merge makes. It is the task title until the agent calls the set_merge_title MCP tool (internal/agents/mergein.go), which it may do until a merge is confirmed: one line of at most 72 characters (maxMergeTitle, checked by cleanMergeTitle), stored in tasks.merge_title (empty there means "use the title"), recorded as a task.merge_title event that the transcript shows as a note. Malformed titles are rejected with a corrective message, and so is a call once the task is closed or while merging_by or merge_queued_by is set. The Merge confirm dialog shows the title in a text field the human can edit (Enter confirms), lists the co-authors, and sends the field's value as merge_title in the body of POST /api/tasks/{id}/merge. Merge validates it like the tool does (400 when malformed) and, when it differs from the stored title, stores it with the human as the event's actor before starting or holding the merge.

A task's participants are the users who put a message bubble with their name in its transcript, derived from its events (Store.Participants): the actors of its user.message events, joined to users so byre and agent drop out. That covers messages sent to the agent and inbox answers, whose delivery message carries the name of the first responder in it (Deliver in internal/agents/inbox.go); dismissing an item puts nothing in the transcript and doesn't count. A fork's participants also include the user who forked it, the actor of its task.created event (whose payload carries forked_from), whose "forked this task" note opens its transcript. They are ordered by their first such event. GET /api/tasks/{id}/co-authors returns the participants other than the caller, with their git name and email from PUT /api/me (empty for a user who hasn't set one). The Merge confirm fetches it and lists Name <email> for each co-author, and separately those with no git identity, who get no trailer.

POST /api/tasks/{id}/merge starts the same turn, with the prompt's closing invitation to revise the title left out since the human just confirmed it, and records in tasks.merging_by that the task is to be merged by the requesting user, who must have a git identity (400 otherwise). Every turn end of the task's session reads and clears it. It survives a byre restart during the turn: startup resumes the session with the restart notice, and the merge happens when that resumed turn ends. When that turn ends normally (not interrupted, not an error), byre squashes the worktree, now containing the default branch, onto it with git merge-tree --merge-base, makes one commit titled with the task's merge_title with git commit-tree, authored and committed by the merging user with no agent attribution, its body one Co-authored-by: Name <email> trailer per co-author with a git identity (squashMessage in internal/agents/mergein.go; the co-authors are computed when the squash runs, relative to the user who clicked Merge), and pushes that commit to the default branch on the origin remote of the project's checkout together with its note (below), in one atomic push (git push --atomic --porcelain origin <commit>:refs/heads/<default branch> <notes commit>:refs/notes/byre, run in the checkout), so either both land or neither does. Only once the push is accepted does it point the checkout's refs/notes/byre at the notes commit, run git merge --ff-only in the project's checkout (which must have the default branch checked out) and close the task; the task.merged event carries the commit and pushed (origin/<default branch>), and the transcript shows both. When the merge changes nothing, no commit is made and nothing is pushed.

Before starting the turn, Merge runs git fetch origin (every configured refspec, so the notes too) and git merge --ff-only origin/<default branch> in the checkout, so the agent merges in what the remote has; the request waits for the fetch, and a failure (network, or a checkout with commits the remote lacks) is returned as the request's error. If the push is still refused, for example because someone pushed during the turn, or fails for any other reason, byre files the error in the inbox and the task stays active; clicking Merge again fetches and goes round once more. A refused push leaves the checkout's default branch where it was, since the squash commit was never moved onto it. If the squash fails, for example because the default branch moved again during the turn, byre also files an error and the task stays active. The agent calls stop_merge (internal/agents/mergein.go) with a reason when its conflict resolution took substantive changes: it clears merging_by and releases the project's merge at once, and records a task.merge_stopped event carrying the reason, which the transcript shows as a note. The turn then ends without a squash, the task stays active, its snapshot is reviewed, and the human clicks Merge again when satisfied. Called with no merge pending (a Sync turn, say), it changes nothing and tells the agent so. An interrupted or failed turn, an agent process that exits mid-turn, or a session that can't be resumed after a restart clears merging_by and leaves the task active without squashing. POST /api/tasks/{id}/discard removes everything without merging.

Each squash commit gets a git note under refs/notes/byre, the durable record of the task (mergeNote in internal/agents/notes.go): a Markdown heading with the merge title; the task's id, title, creator, merging user, TODO item and fork source; a pointer to the full transcripts as the task's events in byre (GET /api/events?task_id=<id>), which the note doesn't copy; every handoff its sessions wrote on compaction (the result of each turn.ended with handoff: true); each review's state, error, change and summary, by snapshot; and each answered question with its context and the responses to it. Plans and eval results aren't recorded yet, since byre has neither. git.NoteCommit builds the notes commit on top of the checkout's current refs/notes/byre in a temporary index, authored as the merging user, without moving the ref, so a refused push leaves the checkout's notes as they were. Notes don't fetch by default, so registering a project (POST /api/projects), and every byre startup for each existing project, adds the refspec refs/notes/byre*:refs/notes/byre* to the checkout's remote.origin.fetch if it isn't there (git.ConfigureNotesFetch); it's a pattern because git refuses a fetch whose exact refspec names a ref the remote doesn't have yet, as it doesn't before the first note is pushed. Another clone adds the same refspec with git config --add remote.origin.fetch 'refs/notes/byre*:refs/notes/byre*'. git log --notes=byre shows the notes, and git notes --ref=byre show <commit> one commit's.

One merge runs per project at a time. The Manager keeps the task holding each project's merge in memory (mergeHolders in internal/agents/manager.go), from just before the fetch until the merge closes the task, fails, or is abandoned as above, or the task is discarded; on startup it is rebuilt from the active tasks with merging_by set. Merge on another task of that project while one is held doesn't fetch or start a turn: it records the request in tasks.merge_queued_by and merge_queued_at (merge_queued_at on the Task), emits task.merge_queued (a transcript note), and returns the task with 202. A second Merge on a held or merging task is a 409. Whenever a project's merge is released, any task turn in it ends, and on startup, byre starts the oldest held merge in the project whose task session is not running: it clears the request (emitting task.merge_unqueued, not drawn) and goes through the same fetch and turn as a direct Merge by the user who asked, so it merges in what the earlier merge pushed. If that start fails (the fetch, or the user has no git identity), byre files the error in the task's inbox and tries the next held merge. The Merge button reads Merge held, disabled, while the task has merge_queued_at; discarding the task drops the request. sqlite3 byre.db "SELECT id, merge_queued_by, merge_queued_at FROM tasks WHERE merge_queued_by != ''" lists held merges.

Running as a service

The listen address is byre serve --listen, whose default is in cmd/byre/serve.go (go run ./cmd/byre serve --help prints it); keep it on loopback, since identity relies on requests arriving from tailscale serve.

go install ./cmd/byre
cp deploy/run.fc.byre.plist ~/Library/LaunchAgents/
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/run.fc.byre.plist
tailscale serve --bg --https=<listen port> http://<listen address>

byre gets its own HTTPS port on the machine's ts.net name rather than a path under another service: the SPA and API use absolute paths, which break under a path prefix. tailscale serve status shows the URL and what else the machine serves.

After rebuilding: go install ./cmd/byre && launchctl kickstart -k gui/$(id -u)/run.fc.byre. Logs go to ~/Library/Logs/byre.log.

Clients reach tailscale serve over HTTP/2; it proxies to byre over HTTP/1.1 and passes SSE through unbuffered.

Previews

An agent shows the human a server it runs with the expose_port MCP tool (internal/agents/preview.go): name labels it, port is where it listens. The agent starts the server itself, usually as a background command; byre doesn't supervise it, so it dies with the agent's claude process (a byre restart, compaction, the task closing) and the agent starts it again when asked. The call is refused when port is outside the task's block or nothing accepts a connection on 127.0.0.1:<port>. Otherwise byre runs tailscale serve --bg --https=<port> http://127.0.0.1:<port> (internal/tailscale, which runs the macOS CLI at /Applications/Tailscale.app/Contents/MacOS/Tailscale, since byre's environment has no tailscale on its PATH), so the server is at https://<byre's ts.net name>:<port>/ with Tailscale's identity headers, and records a row in the previews table (task, name, port, time) with a preview.exposed event, which the transcript shows as a note linking the URL. Each port gets its own HTTPS port rather than a path under byre's, since path-prefix proxying breaks apps that use absolute paths. Exposing a name or port the task already has replaces that row, and a port it no longer uses is turned off with tailscale serve --https=<port> off. A server must listen on 127.0.0.1: while tailscale serve holds a port, binding 0.0.0.0 on it fails with "address already in use". When the task is merged or discarded, byre turns off each of its ports (Manager.Unexpose); the rows stay. GET /api/tasks/{taskId}/previews lists a task's rows by name, and tailscale serve status shows what is served.

The Preview tab (web/src/preview.ts) lists the task's previews by name and port, shows the selected one (the first by default; the choice is kept per task in memory) in an iframe, and links it in a new tab. It fetches the list when it opens, when the selected task changes, and on each preview.exposed in the task's stream, which also reloads the iframe.

Previewing byre

A task's build of byre runs alongside the service with its own empty state, from the worktree root, on the task's port, and the agent exposes it with expose_port:

go run ./cmd/byre serve --dev --data "$PWD/.preview" --listen 127.0.0.1:$PORT --ports 51000

It must never share the service's data directory: nothing locks the database, and startup resumes every session marked running in its recorded worktree. --ports puts the preview's own tasks' port blocks in a range the service's tasks don't use; each instance only knows its own tasks, so with the default both would hand out blocks from the same first port, starting with the one the preview listens on. .preview/ is gitignored, so the end-of-turn commit leaves it out. The preview starts with no users, projects or sessions; set a git identity with PUT /api/me and add a project to try things. A project's Merge pushes to its checkout's origin, so a preview project should be a clone whose origin is a local bare repository (git clone --bare <checkout> .preview/origin.git, then clone that), never the real checkout.

Identity

tailscale serve adds Tailscale-User-Login and Tailscale-User-Name to proxied requests. The server accepts API requests only from loopback and only with both headers; anything else gets 401 or 403. The SPA's static files need no identity. Users are created on first request; each sets their commit identity with PUT /api/me.

To call the API locally without Tailscale, send the headers yourself:

curl -H 'Tailscale-User-Login: you@example.com' -H 'Tailscale-User-Name: You' http://<listen address>/api/me

Agent sessions

POST /api/tasks/{id}/sessions starts a Claude session in the task's worktree and sends the prompt as its first turn; POST /api/sessions/{id}/messages starts later turns and POST /api/sessions/{id}/interrupt ends the current one. A message sent while a task session's turn is running is queued (Manager.Message in internal/agents/queue.go) in task_inputs, keyed by task so it survives a handoff to a new session, and the request returns the running session with 202. A model it carries is applied to the session at once and takes effect from the next turn. The agent gets queued messages after its next tool call, the same way as inbox answers (see "Inbox"): each is recorded as its own user.message with the sender as actor and mid_turn: true, and the agent reads them, headed " sent you this message while you were working", in the hook's additionalContext (Codex: turn/steer). Messages are handed over oldest first, stopping at the first one with images, since mid-turn delivery carries only text; none are handed over during a handoff turn. Whatever is still queued when the turn ends goes out one message per turn, ahead of held inbox answers, from Deliver; startup does the same for idle sessions. Closing the task deletes its queued messages. sqlite3 byre.db 'SELECT * FROM task_inputs' lists them. A task has at most one session that isn't completed. A message may carry model; when it differs from the session's, byre writes it to agent_sessions.model, records a session.model event (shown as a note), and sends the live CLI a set_model control request before the message, so the switch applies from that turn and survives a resume (--model) or compaction. The composer's model menu sends model only when the choice differs from the session's model, or from the session.context model when the session has none. The session's commits use the git identity of the user who created it, so that user must have set one with PUT /api/me.

Images: POST /api/blobs takes a raw image body (type sniffed from the bytes, PNG, JPEG, GIF or WebP only, at most 5 MiB; ImageTypes and MaxBlobBytes in internal/store/blob.go) and returns its id; GET /api/blobs/{id} serves it. A message or session prompt may carry images, a list of blob ids (unknown ids are a 400); a message may then have empty text. byre reads each blob when the turn is sent and passes it before the text: to Claude as a base64 image content block (claude.Session.Send), to Codex as an image input with a data: URL (codex.Session.Send). The user.message event records the ids as images. In the composer, pasting or dropping an image adds a thumbnail with a × to remove it; images upload when the message is sent, and the transcript shows them on the user's message, each linking to the full image.

Compaction is vendor-agnostic: POST /api/sessions/{id}/compact (the transcript's Compact button, always shown and enabled only while the task has an idle session) sends the agent handoffPrompt (internal/agents/compact.go) as a byre message, asking for a handoff covering the goal, decisions and why, current state, dead ends, open questions and files. That turn files no inbox summary and isn't bounced for questions. When it ends normally, its turn.ended carries handoff: true, the session is completed, and a new session on the same task and model starts with handoffPreamble plus the handoff as its first message (actor byre; its user.message carries continuation: true). The context meter tracks the new session. The request's user.message carries handoff: true, and from it the transcript puts the request and everything the agent does in that turn into one collapsed note reading "writing a handoff…", without streaming the agent's text; when the turn ends its summary becomes the turn.ended note, or "handoff not written" if the turn ended without one. The transcript never draws the new session's first message (continuation: true), so that note, which holds the handoff, is the only marker of the switch. If byre restarts during the handoff turn, the continuation is lost and the old session simply goes idle.

Agents spawn parallel work with the create_task MCP tool (internal/agents/tasks.go): title, prompt, base and optional model (default: the caller's session model). It creates a task in the caller's project exactly as POST /api/projects/{id}/tasks does, and starts a session there with prompt as the first message (actor agent), created by the caller's session creator so commits use that user's git identity. base is the agent's choice: default_branch starts from the project's default branch, this_task from the caller's worktree HEAD, which leaves out uncommitted edits from the current turn. The tool returns the new task's id at once; the new session is independent of the caller.

Agents don't commit; byre does. Each user.message event that starts a turn records head, the worktree's HEAD when the turn started. When a turn ends, byre runs git add --all and commits if anything changed (git.CommitAll), as the session's creator, with the first sentence of the turn's final message as the message (commitMessage in internal/agents/manager.go); turn.ended then carries the new sha as commit. A failed commit is logged and the turn still ends.

A session runs on one of two vendors, picked by the model it is created with (vendorOf in internal/agents/process.go): gpt-* models run on Codex (codex app-server), every other model on Claude Code. The UI's model list is models in web/src/task.ts; a live session's picker offers only its own vendor's models, and the API refuses (400) a switch to the other vendor's model. Both vendors sit behind agentProcess (internal/agents/process.go), and both end a turn through the same turnEnded, so commits, turn summaries, snapshots, handoffs, merges and deliveries don't depend on the vendor.

For Claude, byre chooses the session ID (vendor_session_id) up front. Codex picks its own thread id: a Codex session is created with an empty vendor_session_id, and byre stores the thread id when its first process starts (startCodex); a session with an id resumes it with thread/resume. Processes start on demand: the first message after a restart resumes the session (--resume for Claude). Sessions are running from the moment a turn is sent until it ends (Claude's result, Codex's turn/completed); on startup, every session still marked running was cut off mid-turn, and byre resumes it and sends a message telling the agent to re-check the working tree. Stopping the server kills all agent processes. Merging or discarding a task kills its sessions and marks them completed.

Every session gets byre's guidance (guidance in internal/agents/guidance.go): ask questions with ask_human, end each turn with a final message that summarizes it (including every departure from the plan), put everything the human needs in a blocking question's context since that turn has no summary, don't commit (byre commits each turn), and don't push, touch other branches or run git maintenance. A task agent's guidance also names its port range and tells it to do the setup AGENTS.md describes in a new worktree (see "Worktree setup and ports"). A task started from a TODO.md item gets one more line naming the item and telling the agent to remove it from TODO.md in its worktree when the work is done (taskGuidance; see "TODO"). For Claude it is passed as --append-system-prompt, which Claude Code records on a session's first request and reuses on resume, so a running session keeps the text it started with; a UserPromptSubmit hook also attaches it as additionalContext to every user turn, which reaches existing sessions too. For Codex it is the thread's developerInstructions, and every turn/start also carries it as additionalContext under the key byre. The guidance names byre's tools vendor-neutrally ("byre's ask_human tool"): Claude sees them as mcp__byre__<name>, Codex as <name> in the namespace byre (Codex reserves the mcp__ prefix).

A turn whose final message asks the human something in prose is bounced once (takeBounce in internal/agents/guidance.go): if ask_human wasn't called during the turn and the final message has a sentence ending in ? outside code spans, code blocks, quotes and blockquotes, the agent is told to ask through ask_human and carries on. For Claude this is a Stop hook (bounceProseQuestion) that blocks the stop; Claude Code reports the block as a "Stop hook error" notification, which is expected. For Codex, byre doesn't end its turn on turn/completed: it records the nudge as a byre user.message with mid_turn: true and starts another Codex turn with it, and only that turn's end ends byre's turn. The per-turn flags reset when the next user message is sent. An agent told explicitly to ask in plain text will refuse the bounce.

A turn's final message is its summary, and it lives only in the transcript: nothing is filed in the inbox, so the human reads it once. When a task turn ends normally (not an error, not interrupted, not a handoff) with non-empty result text and didn't call ask_human with blocking true, its turn.ended event carries summary: true. That flag drives the lead's "finished a turn" signal and the "Turn summaries" notification (see "Lead agent" and "Notifications"). A turn that asked a blocking question has no summary, since the final message comes after the question it explains; the guidance tells agents to put everything the human needs in the question's context. There is no report tool: models write a closing recap whatever they are told, so byre uses it rather than asking for a second one.

Every turn starts as soon as it is sent; byre doesn't cap how many run at once. Whether a turn resumes the Claude conversation is decided by whether the session has ever sent one.

When Claude Code reports a rate-limit status of rejected and the turn then fails, or a Codex turn fails with codexErrorInfo usageLimitExceeded or rateLimitExceeded, the inbox gets a rate_limited item carrying the vendor's status instead of a generic error.

Codex runs with its own home, codex under the data directory (CODEX_HOME, set by startCodex), so the human's ~/.codex/config.toml (its notify program, MCP servers and plugins) doesn't apply and byre's threads stay out of the ChatGPT app's history. That home needs its own login, once: CODEX_HOME="$HOME/Library/Application Support/byre/codex" codex login. Until then a Codex turn fails with 401 Unauthorized, filed as a session error. The codex binary comes from PATH; see docs/codex-protocol.md.

Status

GET /api/admin/status reports running_turns (task sessions now running, as session, task and vendor; lead turns aren't listed); rate_limits, the latest status each vendor sent since byre started (Claude's rate_limit_info unchanged; Codex's account/rateLimits/updated reshaped by codexRateLimit in internal/agents/codex.go into the same status, rateLimitType and unifiedWindows fields); agent_processes, zombies, stuck_after_seconds and protocol_errors (below); and server counts (start time, agent processes, projects, active tasks, SSE clients, database size including WAL, last event seq).

Agent health is internal/agents/health.go:

• Processes. agent_processes lists every process byre is tracking (idle sessions keep theirs), with session, task, vendor, pid, the session's state, last_event_at (when the process last wrote any line to stdout, or when it started; claude.Session.LastLine) and health. health is exited when the stream has closed or kill(pid, 0) says the pid is gone, stuck when the session is running and nothing has arrived for StuckAfter, otherwise ok. The stream does mark long tool calls: while a tool runs, Claude Code sends a tool_progress line with "heartbeat": true every 30 seconds, so a long go test keeps last_event_at fresh and a silent stream means nothing is happening.
• Zombies. running_without_process: a session marked running whose process byre isn't tracking or has exited. process_without_session: a claude child of the byre process (from ps -A -o pid=,ppid=,comm=) whose pid belongs to no tracked process, or a tracked process still alive for a completed session. A live process for an idle session is normal and not a zombie.
• Watching. Manager.Watch recomputes health every healthInterval. When the set of problems (non-ok processes and zombies) changes, it logs each new one as agent health problem and broadcasts an unstored admin.health event (seq 0). Nothing is killed or repaired automatically.
• Protocol errors. internal/claude reports a stdout line that isn't a JSON object, doesn't parse, or has a type outside knownTypes (the line is still passed on), and the manager adds lines whose content it fails to decode. protocol_errors.counts counts them per vendor since byre started; recent holds the last keptBadLines, newest first, each with session, time, reason, the raw line cut to badLineBytes and its full size. They live in memory only, and each one also broadcasts admin.health.

The Status modal (the navbar's Status button; Esc, ×, a click outside it or following a task link closes it) shows, from the top: a Problems section only when there are zombies or protocol errors (one line per zombie, and per vendor the error count with the latest line folded under it); each running turn, linking to its task, with the time since its process's last event and stuck or exited when it is; each vendor's rate-limit status with its reset time and per-window utilization, and the server counts. It refetches the status when a session.created, session.state, task.*, project.created or admin.health event arrives, when an agent.vendor event carries a rate_limit_event, and when the SSE stream reconnects. Other events advance the last-event seq it shows, and any event carrying a process's agent_session_id (stored or not, such as agent.delta) moves that process's last-event time forward, re-rendering at most once a second per process. A re-render keeps the scroll position and which folded lines are open. There is no timer, so "time since last event" and the "in 2h 10m" beside a reset time are as of the last render; a process going quiet long enough to be stuck shows up when the next health check broadcasts admin.health.

Agent activity becomes events with agent_session_id set: user.message, agent.message, agent.thinking, agent.tool_call, agent.tool_result, turn.ended, session.state, session.model, and session.context. Anything else Claude Code emits (rate-limit status, task progress, state changes) is recorded unchanged as agent.vendor. Codex items map onto the same kinds (handleCodex in internal/agents/codex.go): an agentMessage becomes agent.message, a reasoning item's summary agent.thinking, and commandExecution (as Bash), fileChange (as apply_patch), dynamicToolCall, mcpToolCall and webSearch items an agent.tool_call when they start and an agent.tool_result when they complete. Other completed items and the error and warning notifications are recorded as agent.vendor; the remaining notifications (thread status, MCP startup and the like) aren't recorded. item/agentMessage/delta becomes agent.delta, and thread/tokenUsage/updated session.context. The one exception is partial output: each top-level text_delta is broadcast to SSE clients as an agent.delta event (payload.text, seq 0) that is never stored, and the transcript grows a live message from them until the finished agent.message replaces it. A turn.ended event carries summary: true when its result is the turn's summary (see above). Activity inside a subagent (agent.message, agent.thinking, agent.tool_call, agent.tool_result) carries payload.parent_tool_use_id, the ID of the tool call that started the subagent, and never updates session.context. session.context records the context size whenever it changes: used is the last assistant message's input, cache-read, cache-creation and output tokens, and window is the model's context window from the turn's result (modelUsage[model].contextWindow), so it is 0 until the session's first turn after a server start ends. The task header's Compact button shows the latest one as a background fill across the button, proportional to the window, tinted amber from 70% and red from 90%; the exact count is in its tooltip.

Event payloads are stored whole in events.payload, and agent.tool_result content (full command output, file reads, diffs) dominates the log's size; a task's transcript stream starts from after=0, so opening a task sends all of it. sqlite3 byre.db "SELECT kind, count(*), sum(length(payload)) FROM events GROUP BY kind ORDER BY 3 DESC" shows the split, and sqlite3 byre.db "SELECT kind, count(*), sum(length(payload)) FROM events WHERE task_id = '<task-id>' GROUP BY kind ORDER BY 3 DESC" one task's.

Messages byre itself sends an agent (actor byre: the restart notice, Sync and Merge prompts, Compact's handoff request) show collapsed like a tool call, labelled byre with the first line as the brief; expanding it shows the full text. The transcript view has a border in the task's colour (see "Task colours"; the accent in the lead pane) while the session is running and its transcript has an open turn (ctx.open: a drawn turn-starting user.message, not mid-turn, with no turn.ended after it), and a braille spinner on its last line in the same colour, cycling ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏ every 0.8s. It is one element with one CSS animation: the ten frames are drawn side by side in an inline SVG used as the .spinner mask over a coloured background, and the braille keyframes in web/style.css step the mask position through them. Orion freezes animated GIFs and per-dot step-end opacity animations partway through a turn, so it stays a single element with a single animation. The session list (GET /api/me/lead/sessions or the task's sessions) is fetched separately from the event stream, so it says running a little before the turn's user.message arrives and a little after its turn.ended; requiring the open turn as well keeps the spinner and border from flashing on in those gaps. Consecutive tool calls (with any thinking between them) collapse into one group whose summary counts calls per tool and file, and file paths show relative to the worktree. byre's own tools show without their mcp__byre__ prefix, in title case (mcp__byre__create_task shows as Create Task; toolLabel in web/src/task.ts); other tools show under the name the agent used. A Claude Code subagent call (the Agent or Task tool) stands on its own, collapsed, labelled with its subagent_type and description; expanding it shows the prompt and the call's result. Its summary carries a status from the agent.vendor system events whose tool_use_id names it (task_started: running, or running in the background; task_progress: its description; task_notification: its status, red unless completed). The subagent's own messages, thinking and tool calls (events whose parent_tool_use_id names the call) stream inline with the main agent's, in arrival order, each marked ↳ <subagent_type> with the description as its tooltip; its messages also get an accent rule down their left edge. A run of tool calls groups only calls from the same agent, so a call from another agent starts a new group. A subagent's messages never end the main agent's live message, count as a turn's final message or hide a quiet turn. Claude Code streams a background subagent's activity, but for a foreground one only its prompt, so a foreground subagent shows only as its call, its status and its result. Selecting a task that has never had a session focuses the composer. In the composer, Enter sends and Shift-Enter adds a newline; unsent text is kept per task in memory, so it survives switching tabs or tasks but not a page reload. The composer has no @-file mentions or path picker: text reaches the agent exactly as typed (stream-json doesn't expand @path the way the interactive CLI does), and the agent reads any file the message names with its own tools. The composer is the same whether or not the task has a live session, and stays enabled while a turn runs: Send posts to the session's messages, or starts a session with the text when there is none or the last one completed. A sent message shows at once as a bubble reading "queued…" while the session is running and "sending…" otherwise, replaced by the server's user.message event with the same text when it arrives, and removed (text and images back in the composer) if the request fails.

The task switcher (⌘K, or the project ▸ task picker centred in the right pane's top row) lists active tasks with their session state and open inbox item count, and merge held on a task with merge_queued_at, live while it is open. Tasks with inbox items come first; within each group, the task least recently visited in this browser comes first (never-visited tasks before all others, ties in the server's order: projects by name, tasks newest first). Visit times are kept in the browser's localStorage under byre.visits, stamped when a task is selected and again when it is left. After the tasks come the projects, one row each; picking one points the right pane at the project with no task, on the Project tab. Typing filters both and adds a last row that creates a task with the typed text as its title, in the right pane's project (the first project when there is none); Enter picks the highlighted row. Picking a task points the right pane at it on the Inbox tab when it has open inbox items, otherwise on the Transcript tab (see "Lead agent").

Task colours. Each task has a colour, tasks.color (color in the API), an index into the palette of --task-0 … --task-N custom properties at the top of web/style.css, one set for light and one for dark, all at least 4.5:1 against the backgrounds so they work as text. CreateTask assigns it in the same transaction as the task's row: of the store.TaskColors colours, one no active task holds, and among those the one given out longest ago (the lowest max(rowid) of tasks with that colour, never-used first), so a new task doesn't take the colour of one just closed. Active tasks have distinct colours until more than TaskColors are active at once. TaskColors must match the number of palette entries. An element styled with taskStyle(id) (web/src/taskcolor.ts) sets --task for itself and its children from the task's color; --task defaults to the accent, which is also what a task the page doesn't know gets. The right pane sets it for the selected task, which tints the picker's row, colours the task picker's text, the selected tab's underline, the composer's border and the running border and spinner. Everywhere a task is named it shows in its colour: task titles in the switcher, the Project tab and the Status modal (.task-name), and task links (a.task-link), including any Markdown link to #/task/<id> or #/task/<id>/<tab>. The lead's guidance tells it to link every task it names that way, using #/task/<id>/inbox when it points the human at the task's inbox, and clicking one points the right pane at the task, selecting the named tab if there is one.

Lead agent

Each user has one long-running lead agent, shown in the left pane. It is not tied to a project: it watches every task, tells the human what needs them, points the right pane at it, and acts on the other agents. Its code is internal/agents/lead.go (sessions, held input, signals) and internal/agents/leadtools.go (its MCP tools).

• Sessions. A lead session is an agent_sessions row with owner set to the user's login, role lead and no task_id. Its events carry owner and no project or task. It runs in leads/<login> with leadGuidance (passed and re-attached the same way as a task agent's guidance) and the lead tools instead of the task tools. It has no Stop-hook bounce, no snapshots, no end-of-turn commit and no turn summary; a turn that ends in error records the error on its session.state event, which the pane shows as a note.
• Messages. POST /api/me/lead/messages sends the caller's message to their lead, starting a lead session when there is none. While the lead is mid-turn the message is held in lead_inputs; the lead's PostToolUse hook (Codex: turn/steer after each completed tool item) hands held messages over after its next tool call, like a task's queued messages (see "Agent sessions"), and any still held become its next turn. Signals are never handed over mid-turn. The composer stays enabled. GET /api/me/lead/sessions lists the caller's lead sessions; interrupt and compact use the usual session endpoints.
• Signals. Every published event goes through Manager.Observe. These become signals in lead_inputs for every user who has a lead session: inbox.created (a question with its choices and recommendation, an error or rate limit), inbox.updated when a human answered a question or error, task.created (naming the TODO item it was started from, if any), task.merged, task.discarded, and turn.ended with summary: true (" finished a turn:" with its result cut to 1500 characters). The human switching the right pane is not a signal. A signal caused by the lead itself (actor <login> (lead)) is skipped, as is the update from an answer it gave. A task's task.created event carries the actor that created it, separately from its created_by login: tasks the lead creates with create_task or start_todo keep the human's login as created_by but have actor <login> (lead). Whenever the lead is idle, byre sends the oldest held message from the human as its own turn, or else every held signal as one byre message headed "Signals since your last turn (n)". Its guidance tells it not to respond to the human's own actions, and to make its final message exactly NO_REPLY when a batch needs nothing from it. A transcript (quietReply in web/src/task.ts) never draws an agent.message whose last line is NO_REPLY (the model sometimes writes a sentence before it), and hides the live partial message while its text is still a prefix of it; the partial message starts hidden and is first shown by its 100ms render, so an empty one never takes up space. A lead turn that byre starts without a handoff (a signal batch or a handoff continuation) is held (ctx.held): its byre message isn't drawn and doesn't open the turn, so the spinner stays off, and its partial message stays hidden, until the lead draws something else, such as a tool call, thinking or a real message, which draws the byre message ahead of it. When such a turn ends in NO_REPLY, everything it drew is removed with it (its byre message, tool calls, thinking), so the transcript keeps nothing of it; a turn that ends in a real message keeps all of it.
• Tools. list_tasks (each project's active tasks, then a line listing the titles of its TODO.md items on the default branch that no active task was started from), read_transcript (a task's events in brief, the last limit or those after after_seq), read_inbox, answer_question (an option, other or dismiss response recorded as the user, through the same checks as POST /api/inbox/responses), send_message (starts the task's agent if it has none; refused while it is mid-turn), create_task and start_todo (each with an optional workflow to freeze), interrupt, compact_task, merge_task, discard_task, show, compact_self, and the workflow tools (see "Workflows"). The lead also has Claude Code's own tools and reads worktrees by path. Messages it sends task agents have actor <login> (lead), so they don't make the user a participant; tasks, merges, discards and answers are done as the user. Its guidance says to answer a question only when the answer is clear or the human gave it, and to merge or discard only when the human asks.
• Focus. users.focus holds what the user's right pane shows: project_id, task_id, tabs (the tabs put first, in order) and tab (the selected one). With a task_id, project_id is always that task's project, filled in by the server; with only a project_id, the pane shows that project with no task, which only the Project tab has anything for. GET /api/me/focus reads it; PUT /api/me/focus and the lead's show set it, refusing an unknown tab, a task that isn't active or an unknown project, and record a focus.updated event owned by the user. The page applies the focus on load and on every focus.updated it didn't cause itself; the human's own changes (⌘K, the right pane's task picker, clicking a tab, a task link, a notification) are sent with PUT /api/me/focus. The URL follows the focus: #/task/<id>, #/project/<id>, or #/ for neither.
• Pane lock. A show of what the pane already shows (the same task, or the same project with no task, on the same selected tab; sameView) tells the lead so and applies only its tabs order, whether or not the human is in the pane, so the human's selected tab stays selected. Otherwise, while the human is working in the right pane, the lead's show is refused with an error telling it to say in chat what it would have shown, unless its selected tab is project (the fallback the lead shows when nothing needs the human, so the human being there doesn't hold it) or the pane is finished (Manager.paneFinished): its task is merged or discarded, or its selected tab is inbox and the task has no open items. When an inbox.updated, task.merged or task.discarded event leaves a user's focused task finished that way, that user's signal for it gets a line "Your right pane is free: has nothing left in its inbox." (or "is merged."/"is discarded."), even when the event itself makes no signal, such as a dismissed error; inbox.updated on a task that is no longer active adds none. The lead's guidance tells it to show the next thing that needs the human on that line, or, when nothing does, the project's Project tab with a short status in chat: one line per active task, then up to three TODO items it would start next, each with a reason, starting one only when the human picks it. It writes each item as a link to #/todo/<project_id>/<URL-encoded title>; Markdown views draw that (web/src/todolink.ts) as the title with a Start button that calls POST /api/projects/{id}/todo/tasks with the first model, as the Project tab's does, or, once an active task was started from that item, the task's colour, dot and state, linking to it. A chat view refills them whenever its transcript grows or tasks or sessions change. When that status says nothing new since its last one, it replies NO_REPLY instead. The page sends PUT /api/me/pane-focus with focused whenever that changes: true while the browser window has focus and the focused element is inside the right pane. The pane itself is focusable (tabIndex -1), so a click anywhere in it counts, not only on inputs and buttons; a re-render that removes the focused element hands focus back to the pane rather than counting as leaving. The page sends false on pagehide (with keepalive) and resends true when its event stream reconnects. byre keeps the flag in memory per user (Manager.paneFocused), so it starts false after a restart until the page resends it.
• Start hold. Start on a TODO item in the Project tab leaves the pane where it is. When the user starts one themselves (StartTodo with the user as actor, not the lead's start_todo), byre sets Manager.startedTodo for them, and while it is set and the pane's selected tab is project, every show that would change the view is refused, focused or not, with an error telling the lead the human is likely to start more. The user's own PUT /api/me/focus (switching task or tab) or a message to the lead clears it. It is in memory, so a restart clears it.
• Compaction. The pane's Compact button asks the lead for a handoff (leadHandoffPrompt). The lead can also call compact_self at a logical point; when that turn ends normally, byre sends the same request. The handoff turn ends the session, and a new lead session starts from leadHandoffPreamble plus the handoff; held input follows once that turn ends.
• Restarts. On shutdown, byre marks each running lead session idle with "byre stopped mid-turn" and holds a restart notice for it, so a lead is never left running for a build without lead support to find. After a crash, startup resumes a running lead like a task session. Startup then delivers any held input.

The UI is two panes: the left is the lead's transcript and composer (the same view as a task transcript, with only the Compact button in its header), the right shows the focused task, or project with no task: a top row holding only the task picker, centred, then the tab strip, then the selected tab's view with its own header. The tabs are Transcript, Changes, Files, Terminal, Preview, Inbox, Reviews and Project, the lead's tabs first. Preview shows only once the task's stream has a preview.exposed, Reviews only once it has a review.* event, and Inbox only while the task has open items; the selected tab always shows. Tabs that don't fit in the strip move, from the end, into a More ▾ menu (web/src/panes.ts); the selected tab never moves there, and More carries the Inbox highlight and count when Inbox is in it. ⌘P (Ctrl+P elsewhere) selects the Project tab, keeping the right pane's task, and replaces the browser's print shortcut. ⌘L (Ctrl+L elsewhere) puts the cursor in the lead's composer, and replaces the browser's address bar shortcut. ⌘S (Ctrl+S elsewhere) opens the right pane's task's Merge confirmation, from any tab, when the Merge button would be enabled, and replaces the browser's save shortcut.

TODO

A project's TODO.md is read from the root of its default branch in the project's checkout (git cat-file blob <default branch>:TODO.md), so it shows what has been merged, not uncommitted edits in the checkout. GET /api/projects/{id}/todo returns exists and the parsed items (internal/todo): every top-level list item (-, *, +, 1. or 1) at the start of a line) is an item. Its first line, with any [ ] checkbox removed, is its title; the lines indented under it (and lines continuing it without a blank line between) are its body, with the common indentation removed; section is the nearest heading above it. Checked items ([x]) are skipped, list markers inside fenced code don't count, and paragraphs between items are ignored.

The title is the item's identity. POST /api/projects/{id}/todo/tasks with a title re-reads TODO.md, refuses an unknown title (404) or one an active task already has (409), creates a task from the default branch with that title and todo_item (the tasks.todo_item column, empty for other tasks), and starts its session as the requesting user with todoPrompt (internal/agents/tasks.go): the item as written, and an instruction to remove it from TODO.md in the worktree when the work is done. The agent's guidance names the item too (taskGuidance, see "Agent sessions"), so the instruction survives compaction and resumes. The agent removes the item on its own branch, so the removal lands on the default branch in the same squash commit as the work.

The Project tab is the dashboard of the right pane's project (the focused task's, or the project focused with no task). Under Tasks it lists the project's active tasks in the server's order (newest first), each with its session state, open inbox item count and merge held when it has merge_queued_at, as links that point the right pane at the task's transcript; the focused task is highlighted. Under TODO it lists the TODO.md items, grouped by section, with each body rendered as Markdown. An item with an active task whose todo_item equals its title shows that task's session state as a link to the task instead of a Start button. Start posts the item with the composer's default model and points the right pane at the new task's transcript. The task list follows byre's live state; the tab fetches the project's TODO.md when it opens, when the right pane moves to another project, when the project list changes, when the SSE stream reconnects, and on task.merged; a change pushed to the default branch outside byre shows the next time one of those happens.

Inbox

Agents ask questions with the ask_human MCP tool. Each question carries a context with the background the human needs to answer without reading the transcript, and its choices are written inline in that context as Markdown list items: - ( ) text for pick-one choices, with exactly one - (*) text marking the recommendation, or - [ ] text for pick-any choices, with - [x] text marking the recommended ones. There is no separate list of options. byre parses the choices out of context (internal/agents/choices.go; list items inside code fences and blockquotes don't count) and stores their text in the payload as options, with multiple (pick-any) and recommended. The UI renders the context as Markdown with a radio button or checkbox in place of each choice's marker. A malformed call (no context or why_blocked, fewer than two choices, pick-one and pick-any choices mixed, a pick-one question without exactly one recommendation, two choices with the same text, an unknown attachment kind, a foreign thread_id) is rejected with a message saying what to fix, and nothing is filed. The call returns the item's id as question_id. An agent withdraws a question it no longer needs answered (the human answered it in a chat message, say) with the cancel_question MCP tool and that id: an open question of its own session becomes dismissed with no resolved_by (its inbox.updated event has actor agent), which also stops a blocking one from holding back delivery; anything else is rejected with a message saying why. Each agent error (a turn that ends in error without a human interrupt, a process that dies mid-turn) also files an item.

GET /api/inbox is one query over open items, oldest first; project_id and task_id narrow it to a project or task view, and state picks another state. Blocking questions and errors are blocked; non-blocking questions are fyi. The Inbox tab is task-specific: it shows one of the selected task's open items at a time, the oldest, and the next one once that is answered or dismissed; it shows nothing when no task is selected. The tab is hidden while the task has no open items, unless it is selected. While the selected task has open items, the Inbox tab's button is highlighted in the warn colours (.attention in web/style.css) and carries their count. Answering or dismissing the task's last open item from the Inbox tab switches the pane to the Transcript tab. The other way round, a new question from the selected task arriving while the Transcript tab is shown switches the pane to the Inbox tab; questions already open when the page loaded don't.

POST /api/inbox/responses answers any number of items in one submission. Response types and what they do to the item:

type	allowed on	item becomes
option (the chosen choices' text in options: exactly one for pick-one, one or more for pick-any; a pick-any one may also carry text, delivered after the checked list)	questions	answered
other (free text in text: an answer, a question back, or new instructions)	questions, errors	answered
dismiss	errors	dismissed

Answers reach the agent as one message holding every undelivered option and other response of the session (deliveryMessage in internal/agents/inbox.go), never while one of its blocking questions is still open; until then they stay held (inbox_responses.delivered_at empty). While a turn is running, the task session's PostToolUse hook (afterTool in internal/agents/snapshots.go, through deliverMidTurn) hands them over after the agent's next tool call as the hook's additionalContext, after any queued messages (see "Agent sessions"), so the agent reads them alongside that tool's result without being interrupted (for Codex, after each completed tool item, deliverMidTurn hands them over with turn/steer instead); the user.message event recording it carries mid_turn: true and no head, and the transcript doesn't treat it as a turn start. A turn that makes no further tool call leaves them to Deliver, which runs after each submission and when a turn ends, and sends them as a new turn once the session is idle. The log traces each answer: inbox response recorded when it is stored, deliver held with the reason, deliver sent mid-turn, deliver sent with the session's state and whether its agent process had exited or byre was closing, and undelivered responses with a reason wherever a session has held answers when its turn ends in a handoff or merge, its agent process ends, startup resumes it, or startup finds it idle. sqlite3 byre.db "SELECT * FROM inbox_responses WHERE delivered_at IS NULL" lists the answers held now.

Notifications

An open byre page shows a browser notification for each new inbox item, raised by the page itself from the inbox.created events on its SSE stream (notifyInbox in web/src/notifications.ts). With no byre page open, nothing notifies. byre has no service worker and never uses one; on load the page unregisters any worker left in the browser from earlier versions and, if one was controlling the page, reloads.

• Preferences. users.notification_prefs holds which item kinds notify the user, returned as notification_prefs on GET /api/me and set with PUT /api/me/notifications: blocking_questions (on by default), questions (non-blocking), reports (task turns that end with summary: true on turn.ended, labelled "Turn summaries"), errors (session_error) and rate_limits. The page checks them against each item or turn.ended event as it arrives.
• Content. The title is byre · <task title> and the body the question (or the turn summary's first line, the error, or "Rate limited"), cut at 200 characters. The notification's tag is the item's ID, or turn-<seq> for a turn summary, so several byre pages open in one browser show it once.
• Clicking a notification focuses the page and points the right pane at the item's task.

The Settings modal (the navbar's Settings button) asks the browser for notification permission and edits the preferences.

The Inbox tab shows one item at a time, the task's oldest, filling the tab without a card frame; the next appears when it is answered. Each item is answered on its own; there is no batch submission. A pick-one question's choices are clickable blocks, and clicking one sends that answer at once. A choice's block (or a pick-any choice's checkbox label) holds the whole list item: its first line, which is the choice's text, and everything under it, such as an example's paragraph or code block. A pick-any question's choices are checkboxes, sent with the Submit button at the bottom of the card. Below the choices, an "Other…" block in the same style opens the only text field. A card has at most one Submit button: on a pick-any question it sends the checked choices with the Other text alongside (one option response), or the Other text alone as other when nothing is checked. An error has a "Reply…" block (other) and a Dismiss button. The Other and Reply text boxes send with the Submit button under them or on Enter (Shift+Enter for a newline), like the message box, and fold back into their block when left empty. The list updates in place: a card stays attached while its item is unchanged, so task and inbox updates from other agents don't pull focus out of a text box being typed in.

There is no snoozing. The snoozed_until and snooze_until columns are still in the schema, always empty, so builds from older branches keep working against the same database; nothing reads them.

Every Markdown view (inbox items and the transcript) renders a line <details><summary>Title</summary> (or <details> with the <summary> on the next line), Markdown content, and a line </details> as a collapsed section (web/src/markdown.ts; sections nest) showing only the title; session guidance and the ask_human schema tell agents to put long supporting detail in them.

Markdown images (![alt](src), or ![alt](<src>); the plain form also accepts spaces, since worktree paths under Application Support have one) render inline, linking to the full image. A src that is an absolute path, a path relative to the worktree or a file:// URL is loaded from GET /api/tasks/{taskId}/image?path= for the item's or event's task; a data:image/ URL of PNG, JPEG, GIF or WebP is used as is; any other scheme, http(s) included, shows as a link with the alt text and is never fetched. An image that fails to load is replaced by "image not available: ". An inbox image attachment renders the same way from its image (data URL) or path.

A code block fenced as mermaid, and an inbox diagram attachment, render as a Mermaid diagram (web/src/mermaid.ts). The library is vendored: web/package.json pins mermaid as a devDependency, and go generate ./web copies node_modules/mermaid/dist/mermaid.min.js and its LICENSE into web/vendor/, which is committed and embedded. To upgrade, change the pinned version, npm --prefix web install, and regenerate. Nothing loads it until the first diagram is drawn; that injects one <script src="/vendor/mermaid.min.js"> and initializes Mermaid with securityLevel: "strict" and the base theme, coloured from the custom properties in web/style.css as they resolve at that moment (so a light/dark switch applies from the next page load). Each diagram shows its source until its SVG is ready; source Mermaid rejects stays as source with "diagram not rendered: " under it. The endpoint (internal/server/images.go) serves PNG, JPEG, GIF, WebP and SVG by extension, resolves symlinks on both the worktree and the file and answers 403 for anything outside the worktree, 404 for a missing file, 400 for another extension or a non-file, and 409 once the task is closed (its worktree is gone). Responses carry X-Content-Type-Options: nosniff and a sandboxing Content-Security-Policy, so an SVG opened directly runs no script, and Cache-Control: no-cache with Last-Modified, so a changed file is refetched.

Answers reach the agent as one message, listing each answer under the question or error it responds to, once the session is idle and none of its blocking questions are still waiting for the human. An other answer to a question tells the agent that if it asks something back, it should answer with ask_human using the item's thread_id. Every item change is an inbox.created or inbox.updated event carrying the whole item, including who resolved it.

Changes

GET /api/tasks/{taskId}/changes snapshots the task's worktree as if everything were staged: it copies the worktree's index to a temporary file, runs git add --all against that copy (GIT_INDEX_FILE), and git write-trees it, so committed, staged, unstaged and untracked work is included, .gitignore is respected, and the worktree's real index is never touched. Starting from the real index rather than read-tree HEAD keeps git's stat cache, so unchanged files aren't rehashed. The tree is compared with git merge-base HEAD <default branch>, or with since when given, using rename detection, giving per-file status and line counts. Work already merged into the default branch therefore drops out. The Changes view toggles between Since main and This turn, which passes the latest user.message event's head as since; the summary above the inbox always shows since main. GET /api/tasks/{taskId}/diff returns one file's patch between a base and tree from that response. Each request writes the changed blobs and a tree into the repo's object store as loose objects.

The Changes view lists the files with their counts, opens a file's diff on click (open files stay open across refreshes), and refreshes when it opens, when the selected task changes, and 1.5s after the selected task's last tool result or turn end. It can also be pinned to a snapshot (see "Snapshots"). The Inbox view shows just its summary line (file count, +/− totals, base) for the selected task at the top.

Files

The Files tab browses the selected task's worktree, read-only (internal/server/files.go). GET /api/tasks/{taskId}/dir?path= lists one directory, directories first and then by name, without entries named .git; GET /api/tasks/{taskId}/file?path= returns one regular file. Both take a slash-separated path relative to the worktree root and work only while the task is active (409 otherwise). Every path is opened through an os.Root on the worktree, so a path that leaves it, through .., an absolute path or a symlink at any depth, is a 400; a path with a .git component is also refused. A listing reports each entry as dir, file (with its size) or other, following symlinks that stay inside the worktree (symlink marks them); a symlink that leaves the worktree or points nowhere is other and can't be opened. Gitignored entries are listed with ignored set: one git check-ignore --stdin per listing (git.Ignored) over the entries' paths, taken from the directory's real path so a listing reached through an in-worktree symlink is checked where it really lives; untracked paths under an ignored directory count as ignored, tracked files never do. The view shows them dimmed with ignored beside them, and they open like anything else. A listing stops at maxDirEntries entries with truncated set. A file read sends at most maxFileBytes, cut back to a whole UTF-8 character, with truncated set when the file is longer; a file with a NUL byte or invalid UTF-8 in that part is binary and comes back with no text.

The view shows a breadcrumb from worktree down to the current directory or file, the directory's entries (a ../ row to go up), or the file's text with line numbers and a note when only its start is shown. Where you are is kept per task in memory, so switching tasks or tabs returns to it, but a page reload starts at the root. It refetches what it shows 1.5s after the selected task's last tool result or turn end, keeping the scroll position.

Terminals

Each active task can have one terminal: a login shell ($SHELL -l, from byre's environment) on a PTY (github.com/creack/pty), started in the task's worktree with byre's environment plus TERM=xterm-256color, COLORTERM=truecolor and the task's PORT (internal/server/terminal.go). GET /api/tasks/{taskId}/terminal?cols=&rows= is a WebSocket (github.com/coder/websocket), the only WebSocket in byre: it attaches to the task's terminal, starting the shell at that size if none is running, and works only while the task is active (409 otherwise). The server first sends the last terminalBacklog bytes the terminal printed, then its output as it comes, as binary messages; the client sends keystrokes as binary messages and a TerminalSize JSON text message on every resize. Any number of sockets can attach to one terminal: they all get its output and all type into it, and the last resize wins. A socket that falls terminalClientBuf reads behind is closed and the page reconnects. When the shell exits, every socket is closed with code 4000 and the exit status (exit status 0, signal: hangup) as the reason, and the next attach starts a new shell. Merging or discarding the task, and stopping byre, sends the shell's process group SIGHUP and closes the PTY, so terminals don't survive a restart. The WebSocket handshake checks that Origin matches Host, so another site can't open one through the user's Tailscale identity. The log records terminal started and terminal ended with the task, pid and exit status.

The Terminal tab (web/src/terminal.ts) draws it with xterm.js, vendored like Mermaid: web/package.json pins @xterm/xterm and @xterm/addon-fit, and go generate ./web copies their ES module builds, xterm.css and licenses into web/vendor/. Nothing loads them until the tab first opens, which imports the modules, adds the stylesheet and waits for the font. The terminal uses the UI font and is coloured from the custom properties in web/style.css (background, text, accent cursor, accent-tint selection); ANSI colours are xterm.js's defaults. It fits the pane and resizes with it. Opening the tab, or selecting another task while it is open, opens one socket for the selected task; switching tab or task closes it, and the shell keeps running, so coming back replays its recent output. A socket that drops for any other reason reconnects after 2s while the task is active; after a byre restart that starts a new shell. When the shell exits the header shows shell ended: <status> and a New shell button; when it can't be started (the socket closes with 1011, the error in byre's log as start terminal), the header says so, with the same button to try again. Ctrl key combinations typed in the terminal go to the shell, not to byre's Ctrl+K, Ctrl+P, Ctrl+L and Ctrl+S shortcuts; ⌘K, ⌘P, ⌘L and ⌘S still work.

Snapshots

byre snapshots each task's worktree at the end of every turn (internal/agents/snapshots.go, internal/git/snapshot.go), so a snapshot always sits on a turn boundary, the only place a Codex conversation can be forked. A snapshot builds the tree the same way as the Changes view (a copy of the real index, git add --all, git write-tree), commits it with git commit-tree whose parent is the worktree's HEAD, authored as the session's creator with the message byre snapshot <n> (<trigger>), and points refs/byre/tasks/<task-id>/snap/<n> at it (git update-ref with an empty old value, so an existing ref is never overwritten). A row in the snapshots table records id, task, session, n (from 1 per task), commit and tree shas, event_seq (the task's latest event when the snapshot started, at or after the turn's turn.ended, so the tree holds at least the work up to that event), the trigger and the time, and the same transaction records a snapshot.created event carrying the row.

The trigger is turn_end: the snapshot starts after byre's end-of-turn commit and the turn.ended event. Snapshots taken by earlier builds also carry message (mid-turn, when the agent wrote text after tool calls), tool_call, ask_human and timer. A snapshot whose tree equals the task's latest snapshot's tree is skipped, so a turn that changed no files leaves none. Snapshots run one at a time per task: a trigger that arrives while one is running replaces any already waiting one, and the waiting one runs when the current one finishes. Failures are logged and dropped.

Merging or discarding a task stops new snapshots for it, waits for one in progress, and deletes its refs/byre/tasks/<task-id>/ refs; the rows stay. GET /api/tasks/{taskId}/snapshots lists a task's rows, oldest first. git for-each-ref refs/byre/ in the project's repo lists the live refs.

GET /api/tasks/{taskId}/changes?snapshot=<n> reports a snapshot instead of the live worktree: its tree is the snapshot's tree, and base is the merge-base of the snapshot's commit and the default branch, or with step=true the previous snapshot's tree (for snapshot 1, the same merge-base: the snapshot commit's parent is the worktree's HEAD, which already holds whatever byre committed at the end of the turn). It reads the stored shas, so it works only while the task is active and its refs keep the objects; since with snapshot is a 400. GET /api/tasks/{taskId}/diff takes that base and tree as usual.

The transcript is the timeline. The UI learns a task's snapshots from the snapshot.created events in its transcript (snapshots in web/src/state.ts). A snapshot is a point between the agent's events, not part of one, so each gets its own row in the transcript, a divider reading snapshot #n (its trigger and time in the tooltip), placed where its snapshot.created event falls in the task's event order: just after the turn end it belongs to (after the triggering text for an old message snapshot). A snapshot row ends the current group of tool calls, so calls after it start a new group. The row's changes button pins the snapshot (state.pinned, cleared when the selected task changes) and switches the right pane to the Changes tab; its fork button forks it (see "Forking") and points the right pane at the new task; its review button sets state.reviewed (cleared when the selected task changes) and switches the right pane to the Reviews tab. The Reviews tab shows one snapshot's review at a time: a header with a snapshot picker and ← → steps to the neighbouring reviewed snapshots (all setting state.reviewed), then that snapshot's latest review, or the newest review when nothing is picked. Pinned, the Changes header reads snapshot <n> · <trigger> · <time> with ← and → to step to the neighbouring snapshots, and the range buttons are Since main and This step (step=true, the default when pinning) plus Live, which unpins. A pinned view doesn't refresh on tool results, since a snapshot never changes.

Forking

POST /api/tasks/{taskId}/snapshots/{n}/fork (the fork button on a snapshot's transcript row) starts a new task from a snapshot (internal/agents/fork.go). Its branch and worktree start from the snapshot's commit, so the fork's worktree holds exactly the snapshot's tree, uncommitted work of the time included, as the branch's first commit. The task is titled <title> (fork of #n), keeps the source's merge_title and todo_item, and records forked_from (the source task) and forked_at (n) in the tasks columns of those names. It gets an idle session, created by the requesting user (who needs a git identity), on the snapshot session's model, with forked_from set to that session's vendor_session_id and forked_at to the cut point below. Nothing runs until the first message is sent to it; that turn starts Claude Code with --resume=<forked_from> --resume-session-at=<forked_at> --fork-session --session-id=<new id>, or Codex with thread/fork (threadId forked_from, lastTurnId forked_at) whose new thread id byre then stores, so the new conversation is the source's up to the cut, under its own id, and later starts resume the new id as usual. A forked Codex thread keeps the source's byre tools. Refused (409) while the source task is closed (its snapshot refs are gone) and when there is no cut point; 404 for an unknown snapshot.

The cut point comes from vendor_uuid: every top-level agent.message, agent.thinking, agent.tool_call and agent.tool_result event (not a subagent's) carries the uuid of the Claude Code stream-json line it came from, which is the id of that entry in the CLI's own session transcript. forkPoint takes the last such event of the snapshot's session at or before the snapshot's event_seq, then extends the cut through the following tool calls and results until every tool call it has kept has its result, so the fork never resumes on an unanswered tool call. For a turn_end snapshot the cut is the turn's last message. A Codex session's events carry no vendor_uuid except its turn.ended, which carries the turn id, so for Codex forkPoint picks the last turn that ended at or before the snapshot. Snapshots whose session recorded no vendor_uuid by then, such as those from before byre recorded it, can't be forked.

A fork of a task that froze a workflow gets a copy of the source's frozen workflow, not the library's current one (see "Workflows").

The fork's session guidance gets one more line (forkGuidance in internal/agents/guidance.go) naming the source task, the snapshot, the fork's branch and worktree and the source's worktree, telling the agent that everything before the fork happened in the other worktree and to work only in its own. Claude Code can reuse the system prompt recorded for the source conversation on a fork, the source's cwd included, so the UserPromptSubmit hook's copy is what reliably tells it. The fork's transcript starts with a note from its task.created event, "forked this task from at snapshot #n", linking the source while it is active; the lead's signal for it reads " was forked by from at snapshot n", and list_tasks notes the source. The fork's transcript shows only its own events, not the source's history.

Reviews

Every new snapshot of a task gets a review: a separate agent session on the vendor the task's agent doesn't use reads the change and reports on it (internal/agents/review.go, internal/store/review.go). A turn that changes no files makes no snapshot and so no review, and a snapshot whose change (the diff below) has no files runs no reviewer: it gets a reviews row in state skipped, with no session, vendor or model. The snapshot at the end of a Merge turn that finishes into the squash (the turn ended cleanly with merging_by still set, read by turnEnded before it asks for the snapshot) gets no review and no reviews row at all, since the task closes a moment later; a Merge turn that errors, is interrupted, or calls stop_merge is reviewed as usual. Nothing else starts a review, and nothing waits for one: reviews ride along for the human to look at when they want.

• Starting. After takeSnapshot creates a snapshot, afterSnapshot runs startReviewer: it picks the vendor opposite the task's latest implementer session (reviewVendor) and that vendor's model in reviewModels, checks the snapshot's commit out detached at worktrees/<project-id>/review-<review-id>, creates an agent_sessions row with role reviewer on the task (created by the task's creator), a reviews row (running, one per snapshot), and sends reviewPrompt as its first turn (actor byre): the change as git diff from the previous snapshot (the merge-base with the default branch for the first) with its changed files, the merge-base diff of all the task's work for context, and the task's first message to its agent.
• Running. Reviewer sessions get reviewGuidance and only the submit_review tool, whose arguments (reviewSchema: change, a few sentences of Markdown on what the change does, required and non-empty; a Markdown summary, which the guidance and schema require to be exactly "No significant findings." when there are no findings and otherwise a bulleted list with one line per finding; findings, each with severity, category, title, detail, path, line, end_line and images; and top-level images) become the review's result and mark it done. The guidance encourages, without requiring, Mermaid blocks for a data flow, call graph, state machine or schema the change alters, and screenshots when the change alters something visible.
• Screenshots. Reviewer sessions also get the Playwright MCP server (playwrightMCP in internal/agents/review.go: npx @playwright/mcp at a pinned version, headless Chrome, isolated profile, absolute file paths), passed to Claude as a stdio entry in --mcp-config and to Codex as mcp_servers in the thread's config. Its automatically named files go to worktrees/<project-id>/review-<review-id>-media, removed with the checkout. Each images entry is {path, caption}, the path absolute or relative to the checkout; at submit_review byre reads every one, refuses the whole submission (nothing recorded) for a missing file or one that isn't one of store.ImageTypes within store.MaxBlobBytes, then stores each as a blob and replaces its path with blob, since the files are deleted with the checkout. They run without the Stop-hook bounce, mid-turn delivery, end-of-turn commit, snapshots or turn summaries, and their user.message events carry no head. When the reviewer's turn ends byre completes its session, kills its process and removes the worktree; a review still running then fails with why (no submission, with the final message; an error; an interrupt). A process that exits mid-turn fails the review the same way. Merging or discarding the task fails its running reviews ("the task was closed") and ends their reviewers. On startup, a running reviewer resumes like any session, and a running review whose reviewer isn't running fails.
• Questions. A question's reviews is the review of the first snapshot the task took after the question was filed, the one at the end of the turn that asked it, computed when the item is read; the Inbox tab shows it under the question once it starts.
• Events. review.started and review.finished (state done, failed or skipped; a skipped review emits only review.finished) carry the whole review, with the task's ids and no agent_session_id. A reviewer's own events carry its session id and the task's ids: the transcript skips every event of a session whose session.created has role reviewer, and draws each review.finished as a note with its outcome; the lead's read_transcript leaves the reviewer's events out and shows each review.finished with its summary and findings (reviewLine). GET /api/tasks/{taskId}/sessions and everything that looks for the task's agent (ListSessions) see only implementer sessions.
• UI. The Reviews tab (web/src/reviews.ts) shows one review at a time, picked by snapshot (see "Snapshots" for the picker): its snapshot, state or severity counts, error, change, summary, screenshots and findings. A finding with path and line shows, under its title, the lines line to end_line plus 3 either side from that file's diff for the snapshot's step (changes?snapshot=<n>&step=true, the diff the reviewer was given), with new-file line numbers and the finding's own lines marked; it shows nothing when those lines aren't in the diff, and "diff not available" with the error once the task is closed. Screenshots link to the full image. Each finding has a fix button (also on review cards in the inbox) that sends the finding's severity, title, location and detail to the task's agent as a message from the user: through POST /api/sessions/{id}/messages to its latest live session (queued like any message while the agent is mid-turn, see "Agent sessions"), or starting a session when it has none. Once sent, the right pane switches to that task's Transcript tab. It loads when it opens, when the task changes, and on each review.* event in the task's stream. When the finished review of the highest-numbered snapshot has findings, the tab (or the More menu holding it) is highlighted with a badge of the finding count. Each snapshot row's review button carries a mark over its top-right corner from that snapshot's latest review.* event: a spinner while the review runs, a grey ● when it was skipped, a green ✓ when it finished with no findings, and, when it has findings, the button highlighted with the count in a badge. A failed review leaves the button unmarked. GET /api/tasks/{taskId}/reviews lists a task's reviews oldest first. sqlite3 byre.db "SELECT id, task_id, snapshot_n, vendor, state, error FROM reviews ORDER BY created_at DESC LIMIT 20" shows recent ones.

Workflows

A workflow is a named sequence of stages, each a stage name, a vendor, a model and the stage agent's prompt written out in full. Workflows live in byre's database, in the workflows table (name, and the definition's JSON as definition), shared by every project and never in a repo. Nothing runs a workflow yet: byre stores, validates, exports, imports and freezes them.

• Names. The name is the workflow's key and is shown to the human on buttons and pickers, so it is free text: one line of 1 to 100 characters, trimmed (workflow.CleanName). It isn't part of the definition, so the file doesn't carry it. In URLs it is a path-escaped segment.
• File. One workflow per file: the WorkflowDefinition (api/openapi.yaml) as YAML, an optional description and its stages. workflow.Format writes it with multi-line prompts as literal blocks; workflow.Parse reads YAML or JSON and refuses unknown fields. The download is named after the workflow with /\:*?"<>| replaced by _ (workflow.Filename).
• Validation. workflow.Validate refuses a definition (400, everything wrong listed) with no stages, a stage name that isn't a valid one-line name or repeats another stage's, an empty prompt, or a vendor that isn't the one that runs its model (workflow.VendorOf, the same rule sessions use: gpt-* is Codex, everything else Claude Code).
• API. GET /api/workflows lists every workflow's name and description. GET /api/workflows/{name} downloads its file; PUT takes a file as the body and creates or replaces the workflow; DELETE removes it. Each save or delete records a workflow.updated or workflow.deleted event carrying the name. sqlite3 byre.db 'SELECT name FROM workflows' lists them. Saves and reads go through the Manager (internal/agents/workflows.go) so the HTTP API and the lead's tools share them.
• Lead tools. list_workflows, read_workflow (name, or task_id for a task's frozen copy), save_workflow (name and definition, the file as YAML) and delete_workflow, with the same checks and errors as the API. Task agents don't get them.
• Freezing. POST /api/projects/{id}/tasks, and the lead's create_task and start_todo, take an optional workflow (404 when there is none of that name). The task copies the workflow's name and definition as they are at that moment into tasks.workflow_name and tasks.workflow_definition, so later saves or deletes don't change it. The Task's workflow is the name; GET /api/tasks/{id}/workflow returns the copy as {name, definition} with the definition as YAML (404 for a task without one). A task agent's create_task and the Project tab's Start create tasks without one; a fork copies its source's.

Events

GET /api/events is server-sent events: id is the event's seq, data the Event JSON. Reconnecting with Last-Event-ID (EventSource does this itself) or ?after= replays everything after that seq before going live. ?task_id= limits the stream, replay and live, to one task's events (404 for an unknown task); ?lead=true to the events of the caller's lead agent sessions. An event with an owner (a lead agent's events, a user's focus.updated) goes only to that user's streams; the others never see it. Unstored events (seq 0, currently only agent.delta) go out live only, without an id line, so they don't move Last-Event-ID. A client that falls further behind than its subscriber buffer (subscribe in internal/server/hub.go) is disconnected and catches up by reconnecting. Every 15s the server sends an event: ping so clients can tell a live stream from a dead one. The web UI (subscribe in web/src/api.ts) tracks the last seq it saw and opens a new stream from it when nothing (event or ping) has arrived for 40s, 2s after the browser gives up on one (as it does when tailscale serve answers 502 while byre restarts), when the browser comes back online, and on becoming visible if the stream is stale. While disconnected the navbar shows a red dot and "reconnecting…"; partial output (agent.delta) sent while disconnected is lost, and the finished agent.message replaces it.

The web UI keeps three streams: one for all events from the page's load onward, which drives the task, session, inbox and lead session lists, the right pane's focus and the navbar's connection dot; one per selected task (selectTask in web/src/state.ts), opened with ?task_id= and after=0 so it replays the task's whole history and then stays live; and one for the lead (startLeadStream), opened with ?lead=true and after=0. Each transcript is drawn only from its own stream, so a reconnect after a byre restart fills in both the history and anything missed. Selecting another task closes the old task stream. Events arriving together are drawn in one batch.