Docs

How it works

Pitwall hosts terminal coding agents. It isn't an agent itself: it never rewrites prompts or decides what an agent does. This page covers the parts the home page only names.

• Flags
• Wall
• Next up
• Review
• Terminals
• Spaces
• Agents
• Accounts
• Rules
• agw machines
• CLI and approvals
• First launch
• Performance
• Roadmap

Flags

Each agent has one flag, shown in the sidebar, its pane header and its Wall tile. Within a project, agents sort needs you → done → working → idle, then the rest.

• Needs you: a permission prompt or a question. Amber row, a bar along the bottom of the window, counted on the Dock badge. ⌘J jumps to the next one.
• Done: finished a turn you haven't looked at. Looking turns it idle.
• Working: output is flowing, or the agent's hook says it's busy.
• Idle: waiting for a prompt. Unknown (?) means there's no signal yet.
• Exited / stopped: the process ended, or it was loaded after a restart and isn't running.

When the window isn't focused, needs you and done also post a native notification.

How it knows

1. Hooks, when the agent has sent one this run. Claude Code gets its hooks per launch through --settings; ~/.claude/settings.json is never edited. Codex hooks are opt-in, and ~/.codex/hooks.json is backed up first.
2. The screen. A headless copy of each terminal is matched against per-agent TOML rules, adapted from Herdr's detection manifests (Apache-2.0). Always on.
3. Activity. For any other CLI: output in the last ~1.2 s means working, otherwise unknown.

Hooks are never required.

Wall

⌘E shows every agent's terminal, grouped by project, blocked first. Tiles show the bottom rows of each terminal, where prompts wait. The Wall is view-only: it never resizes a terminal and never types. Click a tile to take over that agent; Esc comes back. A window left in Wall mode stays that way across restarts.

Next up

Each agent has its own queue in the right panel (⌘.). With Auto-send on, the first item goes once the agent has been done or idle for 0.8 s and you haven't typed in its terminal for 2.5 s. Text goes in as a bracketed paste, then Enter, exactly as written. Last sent stays under the queue.

Review

⌘R lists changes by agent, then file, in a side-by-side or inline diff. Pick All changes or one task: a single prompt, from send until the agent is done.

• Per-task snapshots are written through a temporary index (GIT_INDEX_FILE), so your real index and working tree are never touched. Untracked files are included.
• Click a line to comment. Send comments shows the composed prompt for editing first, or queues it if the agent is busy.
• Commit & merge runs git merge --no-ff of the worktree's branch, only when you click. It refuses if your main checkout is dirty; on a conflict it runs git merge --abort and offers the agent an editable "rebase and resolve" prompt.
• The diff editor is bundled, so Review works offline.

The Changes panel in the right panel matches git status: staged and unstaged changes are listed apart, and each git repository inside the agent's folder, or linked into it, gets its own collapsible section with its branch. A file that is both staged and changed again shows both, and its diff opens on the part you clicked.

Terminals that outlive the app

Each agent's terminal belongs to its own pitwall-hold process, not to the app. ⌘Q closes the UI; dev servers and half-finished turns carry on, and the next launch re-attaches with the scrollback replayed. Only Stop, Restart, Remove or Quit and Stop Agents end a terminal. After a reboot, agents come back stopped, and Restart resumes the conversation for CLIs that support it.

Pitwall.app   UI, quit any time
   │ attach · write · resize · replay
   │ ~/.pitwall/run/hold/<agent>.sock
   ▼
pitwall-hold  one per agent, setsid, owns the PTY
   ▼
claude --session-id 7f3c…   still running

Stop / Remove → SIGHUP, SIGKILL after 1.5 s

Spaces and windows

Spaces are tabs of tiled terminals. Presets: 1, 2, 1 big + 2, 2×2 and 3×2, plus 3×3, 4×3 and 4×4 when the window can fit them, and Auto grid. Drag an agent onto a pane edge to split, onto the centre to swap. An agent sits in at most one pane; extras fold into a chip strip. ⌘⇧N moves a space into its own window, and layouts, windows and bounds come back on launch. Moving a terminal never restarts it.

Agents

Pitwall launches the real CLI through $SHELL -l -i -c, so it sees your PATH, logins and config.

Claude Code and Codex can start in their own worktree through the CLI's own flag (claude --worktree <name>, codex --worktree); Pitwall creates no branches or folders. Add your own kind with a TOML file in ~/.pitwall/agents/ (agent definitions); override detection rules in ~/.pitwall/detect/ (detection rules).

Accounts

Claude Code and Codex can run on more than one login, say a work and a personal subscription. Each account is its own login folder (the agent's CLAUDE_CONFIG_DIR or CODEX_HOME); Default is your own ~/.claude or ~/.codex.

• Add one in Settings → Agents → Accounts, or from a project's right-click menu → Accounts…. Log in opens the agent on that account so it asks for its login; Settings shows who each account is logged in as.
• Per project: right-click a project → Accounts… sets the account its new agents use, and offers to move the agents already there.
• Per agent: New agent has an account choice, and an agent's right-click menu → Run on account moves it. It restarts on the new login with its conversation carried over, so it resumes where it was. An account that isn't logged in yet is refused instead of leaving the agent stuck.

Any agent kind whose definition names a login folder variable (account_env) gets the same support.

Rules

Keep rules in ~/.pitwall/rules/, group them into named sets, and assign a set per project with optional extras per agent. Pitwall calls the rulesync CLI to write CLAUDE.md, AGENTS.md and the rest; it doesn't reimplement it.

• Import from a project's .rulesync/, an existing CLAUDE.md or AGENTS.md, or a git repo.
• Generated paths go into the worktree's .git/info/exclude, so they never show up in Review or a commit.
• Agents in your main checkout only get rules when you tick the box.
• Uses rulesync on PATH, or npx -y rulesync only if you enable it in Settings.

agw machines

If you use agw to run agents on VMs, its sessions show up in Pitwall next to your local agents, grouped by machine.

• Works today: add an existing session and get its live terminal, its flag (from screen detection), Next up, stop and start. Diffs and Review run git on the VM through agw. New agent → Runs on creates a session on a VM with agw's own workspaces, users and templates.
• Not yet: hooks and rules on VMs (status comes from the screen only), merging from Review, and deleting a session on the VM. Removing an agw agent from Pitwall only detaches it; the session keeps running there.

CLI and approvals

Settings → Install command-line tool links pitwall into ~/.local/bin or /usr/local/bin. It talks to the running app over a local socket and prints JSON (--human for text).

pitwall agent list
pitwall agent new --kind claude --project ~/code/api --name api [--account work]
pitwall session list --provider agw
pitwall session add agw <vm> <session> --start
pitwall settings list
pitwall settings set appearance.theme dark
pitwall queue add api "run the tests"
pitwall space move "API" --to-window new
pitwall wait api --for done --fresh

It does what the UI does: agents (new, stop, restart, remove, rename, status), queued prompts, spaces and windows, projects, rules, read-only review and settings, plus wait so agents can coordinate. Stopping, restarting or removing an agent asks for your approval when anyone but you asks. Settings are also plain JSON in ~/.pitwall/ui.json (with a JSON Schema for editors): edits apply live, and a value that isn't allowed is reported while the last good one stays. Settings that change something outside Pitwall, like installing Codex hooks, ask for your approval when an agent changes them. Anything that changes another machine (starting or creating a session on a VM) opens an approval dialog in Pitwall and the command waits for your answer. A denial exits with status 3. The app works out who's asking from the calling process, so an agent can't approve its own request. Every command and option is in the CLI reference, every setting in the settings reference.

The optional Race Engineer (the headset in the top bar, or ⌘K) is an agent that already knows all this: it runs on the agent you pick in Settings → Agents, in its own folder in Pitwall's data folder, with Pitwall's instructions and this CLI reference written there as AGENTS.md, CLAUDE.md and GEMINI.md, and pitwall on its PATH. Your ~/.claude and ~/.codex are not touched.

First launch

A read-only scan: agent CLIs on your PATH, recent projects from Claude and Codex transcripts, VS Code and Cursor history and one level deep in ~/projects ~/code ~/Developer ~/src ~/dev ~/work, and conversations you can continue. Desktop, Documents and Downloads aren't enumerated; use Add folder…. Nothing changes until you tick a box. Details are in the quick start.

Performance

Pitwall is a native Rust app. The UI is drawn on the GPU with GPUI, Zed's UI framework, in the same process as the engine: there is no web view, and terminal output never crosses a bridge to be drawn. Terminals are parsed with alacritty_terminal, Wall tiles are drawn from those same screens, and git for local agents refreshes when files change instead of on a timer.

Glass uses the system's own material: Liquid Glass on macOS 26, vibrancy on older macOS, Mica on Windows 11. Terminals stay opaque. Measurements, against the 0.1 releases that ran in a web view, are in the README.

Roadmap

What's being worked on now, what comes next and what comes later is on the roadmap. No dates.