PITWALL

Docs

Quick start

Pitwall is a desktop app for macOS, Linux and Windows (preview) that hosts terminal coding agents and shows which one needs you. It is not an agent itself: it never rewrites prompts or decides what agents do. Download a build from GitHub Releases, or build it from source.

Install

macOS on Apple silicon or Intel (one universal build), Linux x86_64 and Windows x64 (preview). The download page has every file and the first-launch steps for each system. On macOS:

  1. Download the .dmg from the download page and drag Pitwall to Applications.
  2. Open it once with right-click → Open, then Open again in the dialog.

Why the extra step: releases aren't signed with an Apple Developer ID or notarized yet, so Gatekeeper blocks a double-click on the first launch. If macOS says the app is damaged, clear the quarantine flag instead:

xattr -dr com.apple.quarantine /Applications/Pitwall.app

Until builds are Developer-ID signed, macOS may ask again for folder access (Desktop, Documents) after you install a new version, because it sees each build as a different app.

A Homebrew cask is coming; it isn't published yet.

Build from source

You need a Rust toolchain (rustup; the version is pinned in the repository) and, on macOS, Xcode. Plus at least one agent CLI you're already logged in to.

git clone https://github.com/AleksandreJavakhishvili/pitwall.git
cd pitwall
cargo run -p pitwall-app            # run the app (debug build)
scripts/package-app.sh              # release bundles → target/package/

The build also compiles pitwall-hold (the per-agent terminal holder) and the pitwall CLI, and ships both inside the app bundle. Release builds need Xcode's Metal toolchain on macOS, and Linux needs GPUI's libraries; the packages for each OS, and how to install a build into /Applications, are in the README.

The demo on the home page is the web demo of the UI: pnpm install and pnpm dev open it in a browser with mock agents and a simulated scan.

First launch

Pitwall opens with a read-only scan. Nothing on your Mac changes unless you tick a box.

  • Agents on your login-shell PATH, each checked with --version only.
  • Projects from Claude transcripts, Codex sessions, VS Code / Cursor recent folders, and one level deep in ~/projects ~/code ~/Developer ~/src ~/dev ~/work. Desktop, Documents and Downloads aren't enumerated; use "Add folder…".
  • Conversations you can continue. The latest one per ticked project from the last 3 days is pre-ticked.
  • Running elsewhere — agents in other terminals. "Bring into Pitwall" is off by default; close the old terminal first so two copies don't run.
  • Rule files and Codex hooks status. Installing Codex hooks is a checkbox, and ~/.codex/hooks.json is backed up first.

Start Pitwall creates an agent per ticked conversation, resumed in its own folder, and tiles them in the All space. Settings → Scan again runs the same flow later and skips conversations that already have an agent.

Start an agent

⌘N opens New agent: pick a project (search your projects and recent folders, paste a path, drop a folder or Choose folder…), a kind (Claude Code, Codex, Gemini CLI, opencode, Cursor Agent, GitHub Copilot CLI, Qwen Code, Amp, Aider or Shell) and a name. ⌘↵ starts it; More options holds the rest.

  • Account (Claude Code and Codex) picks which login it runs on, when you've added more than one in Settings → Agents → Accounts. It starts on the project's account; "Use it for new agents in …" makes your pick the project's. Right-click a project → Accounts… does the same for the whole project.
  • Separate worktree (off by default; Claude Code and Codex only) passes the agent's own flag — claude --worktree <name> or codex --worktree. Pitwall finds where the agent ends up working and uses that folder for status, diffs and Review. It creates no branches or folders of its own.
  • Rules picks a rule set to write through rulesync before launch. For agents in your main checkout this needs an explicit tick.
  • Agents launch through $SHELL -l -i -c, so they see the same PATH and config as your terminal.

Read the flags

  • needs you — a permission prompt or question. Amber, sorted first, counted on the Dock badge. ⌘J jumps to it.
  • done — finished a turn you haven't looked at yet.
  • working — busy.
  • idle — waiting for a prompt.
  • exited / stopped — the process ended, or it was loaded after a restart and isn't running.

Sources, in priority order: hooks (when the agent has sent one this run), then the terminal screen matched against per-agent rules, then output activity. When the window isn't focused, a blocked or done agent posts a native notification.

Next up

Type a follow-up in the right panel and press ⌘↵. 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 is pasted exactly as written, then Enter.

Review

⌘R opens every agent's changes. Choose All changes or a single task, click a line number to comment, then Send comments to deliver one editable prompt. Commit & merge commits in the agent's worktree and merges its branch with --no-ff; it refuses if your main checkout is dirty and aborts cleanly on conflicts.

Quitting

Closing the window hides it; the Dock icon brings it back. ⌘Q quits the UI only — every agent keeps running in its pitwall-hold process and is re-attached next launch. To end everything, use the app menu's Quit and Stop Agents.

Shortcuts

⌘K
Command palette
⌘N
New agent
⌘J
Next agent that needs you
⌘E
Wall
⌘R
Review
⌘1–⌘9
Focus agent
⌘⏎
Maximise pane
⌘⇧N
Space to new window
⌘B
Sidebar
⌘.
Details panel
⌘+ ⌘− ⌘0
Tile font size
⌘,
Settings

Files

Everything lives in ~/.pitwall/:

state.json          agents, queues, session ids
ui.json             spaces, layouts, windows
agents/*.toml       your own agent kinds
detect/*.toml       status rule overrides
rules/              rule library (rulesync format)
accounts.json       extra Claude Code / Codex logins, per-project picks
accounts/<id>/       each account's login folder
run/hold/*.sock     one socket per terminal holder