Runner Agent Guide

This file is the repo-wide guide for any coding assistant working on Runner. Keep shared conventions here instead of putting them only in a tool-specific file such as CLAUDE.md.

Contributing from outside the project? Read CONTRIBUTING.md first: it says which parts of this guide apply to your pull request and what it must prove before review.

Product Context

Runner is a local desktop app for coordinating multiple CLI coding agents from one UI. Users create reusable roles, compose them into crews, start missions, and interact with each session through a real PTY.

Core vocabulary:

• Role: a configured CLI agent runtime and system prompt, reusable across crews.
• Crew: a named set of slots, each filled by a role, with shared team conventions.
• Mission: a live run of a crew, with one session per slot.
• Session: one spawned agent process attached to a PTY.
• Event: an NDJSON log entry used for mission coordination.

Surface hierarchy (strict — do not blur these in code, docs, or UI copy):

• Window: a real OS window (⇧⌘N). Ownership is described in Surface hierarchy.
• Tab: one group of panes shown on a window's chat surface — the unit the layout picker builds and the sidebar highlights (formerly "chat group" / "split"). ⌘N starts a chat in a new tab.
• Pane: one slot inside a tab, holding a single chat session. Panes are filled from a pane's own New chat button or a sidebar pick.

Stack

• Native UI: GPUI with alacritty_terminal as the terminal model and render buffer.
• Background daemon: runnerd runs the Rust application core and SQLite via rusqlite, exposed by crates/runner-daemon; the app and CLI are clients.
• PTY runtime: portable-pty.
• Event transport: append-only NDJSON logs watched through notify.
• Bundled CLI: runner, built from the crates/runner-cli/ workspace member.

Project Map

• crates/runner-app/: GPUI application, terminal renderer, and terminal fixture corpus.
• crates/runner-daemon/: runnerd and its UI-agnostic application core, including SQLite, the session manager, event bus and router, and the client-protocol server the app and CLI connect to.
• crates/runner-cli/: the bundled runner CLI, used by spawned agents inside a mission and by people, scripts and agents outside one.
• crates/runner-core/: shared types, event-log primitives, client protocol and daemon launch/connection.
• Design sources are not in this repo: the .pen files live in runner/desktop/ of the private YeelinksCo/yeelinks_design repo (see Engineering Conventions).
• docs/arch/: architecture references (how it works).
• docs/product/: product vision and direction (why we're building this, what surfaces matter).
• docs/guide/: user documentation, with README.md as the website's navigation order; writing and generation conventions live in docs/guide-authoring.md.
• docs/features/: specs of features in development, named {tracking-issue}-{slug}.md. A feature is only an issue until its development starts; its spec is then written on the feature's branch and lands with the code. Only important shipped records stay in docs/features/archive/, indexed by its README under the archive policy.
• docs/impls/: implementation plans; retained shipped plans live in docs/impls/archive/, mission briefs in docs/impls/briefs/.
• docs/tests/: validation and smoke-test plans; records of shipped features live in docs/tests/archive/.
• docs/roadmap.md: where the project is, mirrored from the GitHub milestones and dated.
• docs/tech/: deep dives on the libraries Runner builds on (how the dependencies work), pinned to the versions in Cargo.lock.

Development Commands

• Start the native app against the development database: make run. A rebuilt sidecar replaces the development daemon of another build, unless another development app is still connected to that daemon: then the launch waits three seconds for it to disconnect and exits with an error, so quit the other app first. runner-dev daemon stop stops the daemon explicitly and hangs up every connected app's sessions.
• Format: make fmt.
• Clippy: make clippy.
• Workspace tests: make test.
• Local validation: make verify (check + test + clippy + fmt-check).

CI runs Clippy and workspace tests with the ci Cargo profile, which uses lighter dependency optimization and debug information. Install the pinned prebuilt nextest locally on macOS with curl -LsSf https://get.nexte.st/0.9.148/mac | tar zxf - -C "${CARGO_HOME:-$HOME/.cargo}/bin"; Windows installation is documented in Windows validation. Reproduce CI with cargo clippy --locked --workspace --all-targets --profile ci -- -D warnings and cargo nextest run --locked --workspace --no-fail-fast --cargo-profile ci --timings; macOS also checks formatting and Clippy with --features updater. make test continues to use cargo test. Normal development uses the dev profile; releases use level 3 optimization with thin LTO and Cargo's default codegen units.

On Windows, use .\make.cmd run to build and start the app with its CLI sidecars, or .\make.cmd build to build only. Add --release for optimized binaries under target\release; the default development binaries are under target\debug. Use .\make.cmd clean to remove the Cargo target directory, or .\make.cmd clean --release to clean only release outputs; close the development app and finish other builds first. Installed apps, user data, Rust toolchains, and Cargo's shared dependency cache are kept. The script works in PowerShell and Command Prompt without GNU Make; use the native Cargo commands in Local Windows development for checks.

Linux development uses make run and the same Cargo commands. See Linux development for dependencies, dual-architecture builds, packages and the opt-in user service. Linux updater checks and installs signed packages; make clippy runs its updater-feature pass only on macOS/Windows.

Prefer the smallest check that covers the change. For native UI changes, run the runner-app tests plus workspace clippy; for core behavior, run the relevant crate tests.

Test Scope

Feature validation covers the behavior changed by the diff and regressions directly affected by it. Before testing, list the changed behaviors and selected checks, with a concrete reason connecting each check to the change. Select relevant cases from the live regression suite and add feature-specific checks; do not run the whole suite for an ordinary feature. Unchanged IME, agent runtimes, authentication, session lifecycle and other shared behavior are not automatic feature checks merely because the tested UI contains them. For a card-padding change, for example, verify terminal backgrounds and selection stay inside the card; add IME checks only if the change affects input or composition positioning.

Broaden coverage for major changes, such as a runtime/session/daemon rewrite, a persistence migration or a refactor affecting behavior across the app, or when Jason explicitly requests broader testing. State why the change needs that coverage. Required automated gates and CI still apply. Reusing the full-smoke procedure's setup, candidate identity, isolation, evidence and cleanup rules does not expand the selected cases. An unavailable prerequisite blocks an in-scope check; an unrelated check is outside scope, not a feature blocker. A feature pass means every selected required check passed, and must not be described as a full regression pass. Preserve failures and record any later scope change explicitly.

The development app is a separate test environment (Jason, 2026-10-14): its data lives under com.wycstudios.runner-dev, apart from the installed Runner, so live testing in it is authorized standing and needs no per-mission ask. Whoever runs the selected live checks, usually the qa slot of a trio or the qa role added to a mission after its code review, may launch the development app, let its saved chats resume when the development daemon starts, and start bounded test chats and missions with real agents on the existing sign-ins: an inexpensive model, low effort, tiny prompts, each in a fresh folder under /tmp. It never types into, archives or otherwise operates development sessions it did not create, archives only its own, and never touches the installed Runner, its chats or its missions. Coders and reviewers do not run the app (Jason, 2026-10-26). The reviewer only reviews code, and decides from the diff whether live checks are needed unless the brief settles it: they are required when the change alters what a person sees or operates in the running app, and not for documentation, refactors the tests cover, or logic the in-process tests exercise; its clean review names the checks, or says why none are needed (Jason, 2026-10-23). A change expected to need live checks runs in a trio, the claude trio unless Jason asks for the codex one, whose qa slot takes the reviewed candidate from the coder and runs the checks the clean review names (Jason, 2026-11-04). When a duo's clean review names live checks, the mission's operator, usually the chat that started it, adds the codex qa role once Runner reports the mission settled: runner mission add-role <mission> qa --task-file -, with a task naming the checks and the candidate commit. Approving the mission approves this step, so the operator does not ask again. qa runs the checks on that candidate through computer use, and its verdict says which checks ran (Jason, 2026-10-24). A failure goes back to the coder, and the fixed candidate is reviewed again before qa reruns the affected checks. Changes to an agent's global configuration still follow Agent configuration isolation.

The development app and the screen are one resource, so concurrent missions' qa take turns through a shared lock (#1188). Before building a wrapper or launching the development app, qa takes it with script/qa-lock acquire --timeout 540 (python script\qa-lock on Windows), which reads the mission and handle from Runner's environment and ties the lock to the agent process that ran the command, so the OS frees it if that process dies. qa holds the lock through pauses until cleanup and releases it with script/qa-lock release once its app and daemon have exited. A qa that cannot get the lock reports the holder acquire printed, through Runner messages to whoever handed it the candidate, and keeps waiting with further bounded acquire calls; it never launches anyway and never stops another mission's app. Only qa takes the lock: a person using the development app does not, and can see who holds it with script/qa-lock status.

A live test of a pull request runs in the qa role through Runner, not in the chat that asked for it (Jason, 2026-11-04). When Jason asks a chat to live-test a pull request whose mission has ended, or that no mission produced, the chat reviews the diff, then starts a mission for qa alone in the PR's worktree, checking the branch out there first if it has none: runner mission start --title "<PR> — Live QA <topic>" --cwd <repo>/.worktrees/<flattened-branch> -q with no crew, then runner mission add-role <mission> qa --task-file -. The request approves this mission. The task names the PR, its candidate commit and the worktree, where qa launches the development app with make run; the selected checks, the PR's own plus any the chat's review adds, each with its reason; any development setting a check changes, with a backup and the value to restore; and the verdict: pass or fail per check with screenshot evidence, the results recorded in the PR description, and needs-live-test kept while any required check, on any platform, has not passed. qa changes no code. The chat is the mission's operator: Runner reports the settled mission back to it, and it passes a failure to Jason, or to the PR's crew while that mission still runs.

Full Smoke Tests

When Jason explicitly requests a complete smoke test for a major refactor or important release, follow Full smoke test procedure for setup, isolation, candidate identity, computer use and cleanup, and select cases from the maintained live regression suite: active smoke-tier rows before releases, all active rows for a complete regression. Add the change's feature-specific checks and record platform or runtime gaps explicitly. The procedure's bounded test chats and missions run under the standing development-app authorization in Test Scope; the explicit request is what decides that a full smoke runs. Use development data, preserve existing sessions, and archive only the test chats and missions you created. Record runs separately in docs/tests/runs/YYYY-MM-DD-<platform>.md using the suite's case IDs and evidence format; the #777 run is the first historical runtime example.

Issue Investigation And Fixes

An issue's route follows its readiness (Jason, 2026-11-05). The route is the default recommendation; Jason's explicit choice of crew or of inline work wins, and starting a crew still needs his approval.

1. Needs design (needs-design): the chat that took the issue finishes the design and the spec. It draws the UI in runner/desktop/specs/<issue>-<slug>.pen, settles the open questions with Jason, and writes docs/features/<issue>-<slug>.md on the feature's branch, naming the live checks the change needs as Test Scope describes. The issue drops needs-design once Jason signs the design off.
2. Designed: a signed-off design and spec go to a claude crew, the claude trio when the spec names live checks and the claude duo otherwise. A codex crew runs only when Jason asks for one.
3. Very small: a change whose brief would be longer than its diff is fixed inline, as below. A trivial change that needs no review, such as copy, a typo or an obvious one-line fix, skips the reviewer.

When Jason asks an agent to check an issue, investigate first and report the problem, likely cause, scope and relevant validation. For a small code fix, confirm that Jason wants it implemented in the current session and opened as a pull request. Once confirmed, work inline in a branch worktree, implement and validate the fix, then commit, push and open the PR. An instruction that already asks for the fix and PR is that confirmation; do not ask again. Then, unless the change is trivial, have the PR reviewed (Jason, 2026-11-04): start a mission for the codex reviewer alone in the PR's worktree, runner mission start --title "<PR> — Review <topic>" --cwd <repo>/.worktrees/<flattened-branch> -q with no crew, then runner mission add-role <mission> reviewer --runtime codex --model gpt-6-astra --effort xhigh --task-file -, with a task naming the PR, its head commit and the worktree. The fix request approves this mission. The chat is its operator: it folds must-fix findings into the PR's commit, pushes, and asks the reviewer to review the new head until the review is clean. Leave any required live checks to Jason, identify them in the PR and label it needs-live-test, following Test Scope. Doc-only fixes follow Commit And PR Conventions for branch, commit and PR handling.

For larger work, write a short problem brief with the evidence, proposed scope and validation needs, then confirm the next step with Jason before implementing or launching agents. Recommend the crew the route above names, and name the live checks you expect as Test Scope describes. Start the approved crew only through Runner and follow Crew Missions; the investigation alone does not authorize a mission or Git writes. Jason can choose to narrow the scope, defer the work or continue inline instead.

Worktrees

The checkout at the repository root stays on main. Every branch of work gets its own linked worktree under .worktrees/, named after the branch with its slashes flattened: fix/659-session-start-status lives in .worktrees/fix-659-session-start-status. Create it with git worktree add .worktrees/<flattened-branch> -b <branch> origin/main and remove it with git worktree remove once the branch has merged. Because the directory name is the branch name, an editor window's title says which work it holds, and either name can be derived from the other.

.worktrees/ is ignored, and nesting is safe in the ways that matter: git clean -xfd skips a nested worktree and reports it as a skipped repository, so removing one takes a deliberate -ff; the workspace members in Cargo.toml are explicit paths, so a nested checkout is never part of a build; and ripgrep honours the ignore, so a search from the root checkout does not cross into another branch's copy.

Each worktree carries its own target/ and pays for its own build. Do not point them at a shared CARGO_TARGET_DIR: Cargo takes an exclusive lock on the target directory, so concurrent worktrees would queue behind each other instead of building in parallel.

Work stays inside its own worktree. When several are live at once, treat the others as another machine's checkout.

Engineering Conventions

• Follow existing local patterns before adding new abstractions.
• Keep platform window chrome in crates/runner-app/src/platform_ui/{macos,windows,linux}.rs and font mappings in the adjacent fonts_{macos,windows,linux}.rs, selected at compile time. Windows/Linux custom chrome is shared in desktop.rs; layout changes must preserve the macOS implementation; share sidebar and workspace content across platforms.
• Keep changes scoped to the request. Avoid unrelated refactors.
• A pull request that changes user-visible behavior (commands, settings, shortcuts or screens) updates the relevant docs/guide/ pages in the same pull request. Feature specs name the guide pages they affect. Regenerate the CLI reference with make guide-cli when CLI help changes; CI checks it on both platforms.
• Do not revert user changes. If the working tree is dirty, inspect first and preserve unrelated edits.
• Use structured APIs and parsers when available instead of ad hoc string manipulation.
• Keep comments rare and useful. Explain non-obvious intent, not mechanics.
• Designs live in the private YeelinksCo/yeelinks_design repo under runner/desktop/ (checked out at ~/repos/yeelinks/yeelinks_design), where the Runner server's and iPhone app's designs also belong; they moved there from this repo's design/ on 2026-10-19; its README has the conventions. Keep UI aligned with the file and node referenced by the user or feature spec. The active canvas is runner/desktop/runner.pen, the product canvas of screens and cmp/ components; feature specs go in runner/desktop/specs/<issue>-<slug>.pen, one file per spec, since 2026-09-18. A spec file holds only the frames that spec needs, plus the cmp/ components they reference; it is never a full copy of runner.pen. Pull the design repo before opening a file, and commit and push there as soon as a design session ends: Pen does not autosave, and a .pen file does not merge. Docs here name a design by its path in that repo, without a link, since the repo is private. The gpui-rewrite's parity exception (plan decision 1) ended at the v0.6.0 cutover on 2026-08-23.
• README.md and README.zh-CN.md change together: a PR that edits one edits the other, and a paragraph that cannot be translated yet is marked <!-- TODO zh-CN --> rather than left silently behind.
• Do not add repo conventions only to an agent-specific file. Update this file and leave tool-specific files as pointers if needed.

Commit And PR Conventions

• Use focused commits with an imperative subject; Crew Missions covers how a mission's pull request is shaped.
• Common scopes: db, commands, ui, event-log, session, event-bus, router, cli, mission, docs, validation.
• Example: fix(session): preserve terminal geometry on tab switch.
• A doc-only change (docs/, the READMEs, this file) is committed straight to main from the root checkout, with no branch, worktree or pull request; a feature's spec, impl plan and mission brief go on its branch and land with its code. Open a PR for docs only when the edit is large and spans several files, such as a restructure or a rename across the docs tree.
• Label a PR frontend-only when its behaviour changes are confined to the desktop app (runner-app): runnerd, the CLI, the client protocol and storage behave the same. A behaviour-preserving refactor in a shared crate, such as moving a helper into runner-core, still qualifies; a migration, a new protocol field or a daemon or CLI behaviour change does not. A PR that changes no behaviour at all takes no-behavior-change instead.
• A PR that changes Runner's core gets the core-review label, and Jason reviews it closely before it merges. The core is session lifecycle (session/manager/, session/state/, launch and the runtime seam), the daemon/PTY boundary (session/pty_runtime.rs, session/process/), the event bus, router and event log, the client protocol's transport and request surface with the daemon server and launch, and the SQLite schema and migrations (db/). The Core review workflow holds the exact paths and adds the label automatically; test-only changes do not trigger it. Never remove the label, and a crew asked to merge waits for Jason's review of a core-review PR.
• Every PR gets exactly one risk label, which tells Jason how closely to read it: risk-low for a small or mechanical change a skim covers, such as removing unreachable code, a rename, or a behaviour-preserving refactor whose tests and goldens are unchanged; risk-medium for a real behaviour change in a contained area, whose changed code paths need reading; risk-high for a broad or cross-cutting behaviour change, a migration, or anything hard to undo, which needs a careful review and live testing. Whoever opens the PR picks the label from what the diff does, not from which paths it touches: a core-review PR can still be risk-low. When unsure, pick the higher one, and update the label when the PR's scope changes.
• A PR whose required live checks have not passed yet carries needs-live-test. Whoever opens it adds the label when the brief or the clean review names required live checks (see Test Scope); whoever runs them removes it once every selected check has passed and records in the PR description which checks ran. A failed check keeps the label. A crew asked to merge waits while the label is on.
• A PR carries reviewed once an independent reviewer has passed its current head with no remaining must-fix findings (Jason, 2026-11-04): the crew's reviewer for a mission's PR, or the codex reviewer on gpt-6-astra for an inline fix (see Issue Investigation And Fixes). The reviewer adds the label with its clean review and names the reviewed commit in a PR comment. Whoever later pushes a code change removes the label until the new head passes review again.
• For validation branches, keep PR descriptions current when scope changes.
• Bring a branch up to date by rebasing it onto origin/main and pushing with git push --force-with-lease; never merge main into a branch. A PR's history stays its own commits on top of main. A branch need not be current to merge: catch up only when GitHub shows a conflict, or when commits touching the same code have landed on main since the PR's CI ran, because a re-run tests the same stale trial merge and only a push tests against the new main. An umbrella branch is the exception: it follows main by merging main in, because rebasing it would rewrite every commit on it and every mission branch cut from it.
• Pull requests land on main as merge commits (gh pr merge --merge), never squashed or rebased. The PR's commits reach main as written, and the merge commit makes the PR one unit that git revert -m 1 undoes. Read main one PR per line with git log --first-parent, and bisect it with git bisect start --first-parent.
• Do not add tool-specific co-author trailers unless the user explicitly asks.

Crew Missions

A crew is a trio, a coder, a reviewer and qa, for a change that needs live checks; otherwise it is a duo, a coder and a reviewer. The claude trio and claude duo are the default, and the codex trio and codex duo run when Jason asks for them; see Issue Investigation And Fixes. A duo whose clean review names live checks gets the qa role added after it, as Test Scope describes. A crew mission ends in an open pull request by default. The crew works on its own branch in its own worktree, commits, pushes, opens the PR against main, and drives CI green on both platforms; then it stops. Jason reviews the PR and does the final merge, or explicitly asks the crew to merge after review and CI are clean. Crews do not cut a nightly or release without explicit authorization. A brief's authorization states only what is specific to its mission: the approved crew, whether the crew may commit, push and open a pull request, and any exception to this section's rules. A crew follows these rules without the brief restating them.

An explicit merge request includes GitHub's configured automatic deletion of the merged remote branch; no separate confirmation is needed. Local branch and worktree cleanup still requires explicit authorization; see Post-mission cleanup.

A mission runs in its worktree. Before starting it, create the worktree as described under Worktrees and commit the brief on its branch; then start the mission with the worktree as its directory, runner mission start --crew <crew> --title <title> --cwd <repo>/.worktrees/<flattened-branch> …, not --project runner. Every slot's agent and shell then start in the worktree instead of the root checkout, the mission still lands under the runner project because the project is inferred from the directory, and the brief names the same path.

A program that runs on an umbrella branch, such as #645's feat/645-runnerd, creates each mission's worktree from the umbrella instead of origin/main and opens the mission's PR against the umbrella. The umbrella follows main by merging main in between missions and reaches main as one PR when the program's gate passes; see the program's plan in docs/impls/.

A mission's pull request is a clean history on top of main (or of the umbrella, for an umbrella program), shaped as the crew judges best. A single change is usually one commit; split it when the work falls into steps that each stand on their own, such as a refactor and the feature built on it, or a fix and an unrelated cleanup, and make every commit build and pass its tests. The brief is folded into a commit rather than landing as one of its own, and each subject names the change, not the brief. Fixes after the push, from review or CI, are folded into the commit they correct (git commit --fixup with an autosquash rebase, or git commit --amend for the last commit) rather than added as "address review" commits, and pushed with git push --force-with-lease.

Post-mission cleanup

When Jason asks for the post-mission cleanup, usually together with the merge, it covers two local steps, in this order, once the PR has merged. Neither adds a commit to main:

1. Archive the mission. Stop it if a session is still live (runner mission stop <id>), then runner mission archive <id>.
2. Remove the worktree and branches. git worktree remove .worktrees/<flattened-branch>, then delete the local branch once gh pr view shows the PR merged. GitHub deletes the remote branch on merge; delete it by hand only if it is still there.

The mission's brief, test record and spec stay where they are until the next release's docs sweep.

Docs Sweep At Release

Shipped work's docs are reviewed once per production release, not after each merge; Jason may also request a cleanup. Follow the archive policy: delete completed small-feature and bug-fix specs/plans; retain only important features, architectural changes and consequential migration or compatibility records, with a reason in the relevant archive README. Preserve unique current decisions and repair references before pruning. Read archive indexes first and load only the records needed for the task, never the whole archive for orientation.

Once a release is published, one doc-only commit on main sweeps everything shipped since the previous sweep: test records move to docs/tests/archive/ with lasting live checks promoted into docs/tests/regression/, merged missions' briefs are pruned except the examples in docs/impls/briefs/README.md, specs and plans follow the retention policy, and docs/roadmap.md records the release. Distant features remain issues until development starts. Test evidence, run results and task/review logs are retained separately from discarded planning text. The procedure is the sweep action of the release skill.

Notes For Agent Runtimes

This repository is intentionally agent-agnostic. Claude Code, Codex, or any other assistant should read AGENTS.md as the shared guide. Tool-specific instruction files may exist only as compatibility entrypoints and should point back here.