Documentation

Install

Download the DMG from the latest release and drag Clarence into Applications.

Early-access builds are not yet notarized by Apple, so the first launch needs one extra step. Either right-click the app and choose Open, or clear the quarantine flag:

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

You'll also want at least one agent CLI installed and authenticated: claude (Claude Code), opencode (OpenCode), or codex. Clarence launches whichever you pick per workspace.

Quickstart

1. Create a workspace. Click + in the sidebar, point it at a repo, pick your agent and a starting layout (1–12 panes).
2. Talk to your agents. Each pane is a real terminal running a real agent. Click a pane and type. Every agent gets a name, so the sidebar reads like a roster: Vesper is working, Pluto needs input.
3. Multiply. ⌘D splits the focused pane with a fresh agent. ⌘T opens a new tab with its own layout. Right-click anywhere for the full menu.

Workspaces persist: quit Clarence and relaunch, and your layouts respawn their agents in place.

Workspaces, tabs & panes

A workspace is a repo plus its agents. Inside it, tabs each hold an independent split-pane layout, so one tab can be your feature work and another a debugging session. Background tabs show a pulsing dot when an agent there is waiting on you.

Panes are live terminals. Zoom one to full-screen with ⌘Z, close with ⌘⇧K, drag files onto them to paste paths (screenshots included), and watch the status roll up: sidebar rows, workspace cards, and tab dots all reflect what agents are doing right now.

Turn on worktrees per agent when creating a workspace and every agent gets its own git worktree and branch: parallel work on one repo without stepping on each other. Worktrees are cleaned up when their pane closes.

Keyboard shortcuts

Pop-out windows

Click ⧉ in a pane's top bar to detach that agent into its own window, useful for parking a long-running agent on another display. The pop-out can never lose your agent: closing it any way (traffic light, ⌘W, or the return to workspace button) folds the agent back into the exact tab it came from, already painted and focused.

GitHub & PR review

Connect GitHub in Settings (device-flow sign-in, or it picks up your gh CLI token automatically). You get:

• Open PRs in the sidebar, from any author on the focused repo, refreshed live.
• One-click review: Clarence fetches the PR's exact head commit, checks it out locally (fork-safe), and spawns an agent with the review brief.
• CI status for your current branch in the top bar, with a per-check breakdown and a notifications log for check transitions and new PRs.

Voice dictation

Enable Clarence Voice in Settings, download a Whisper model (runs fully on-device, nothing leaves your machine), then hold the hotkey and speak. The transcription types into the focused agent as if you'd written it. Works in pop-out windows too. Hotkey, model size, and microphone are configurable in Settings → Voice.

Clarence Graph

The Clarence Graph is a local knowledge graph your agents share over MCP: decisions made, approaches tried and failed, which agent owns which file. Agent B picks up where Agent A left off without rediscovering the same ground. Strictly opt-in.

Setup

1. Install and start Docker Desktop (enable Start at login).
2. In Clarence: Settings → Graph → Open the setup guide. Enable the graph and press Start the engine. Postgres + pgvector spin up in Docker, bound to localhost only.
3. Register the bundled MCP server in your agent tooling. For Claude Code:

claude mcp add --scope user clarence-graph \
  -e CLARENCE_KG_URL=postgresql://clarence:clarence@127.0.0.1:15432/clarence_kg \
  -- /Applications/Clarence.app/Contents/MacOS/clarence-mcp

The setup guide has ready-made snippets for OpenCode and Codex too. Verify with claude mcp list (look for clarence-graph ✔).

Team hosting

Teams can share one centrally hosted graph instead of per-machine engines. Host any Postgres 14+ with the pgvector extension, load the schema from ~/.clarence/graph/schema.sql, then point each teammate's Clarence at it: Settings → Graph → Team graph, paste the connection URL. Use the same URL as CLARENCE_KG_URL when registering the MCP server (the snippets in Settings update automatically). Every teammate's agents then read and write the same decisions, attempts, and file claims.

How agents use it

Agents get five tools: kg.write_decision, kg.record_attempt, kg.claim_file, kg.query, and kg.related. Clarence exports each pane's identity into its environment, so graph writes are attributed to the right agent and workspace automatically, no prompting required. The sidebar shows live stats, the latest recorded knowledge, and warnings when two agents claim the same file.

macOS permissions

Clarence hosts real terminals, and macOS attributes everything your agents' shells do to the hosting app, exactly as it does for Terminal.app and iTerm2. So when an agent reads ~/Downloads or ~/Documents, macOS asks on Clarence's behalf.

Clarence itself requests exactly one permission: the microphone, for push-to-talk, and only if you use Voice. Everything else is your agents at work. Grant the folder prompts, or agents will hit permission errors in those locations. You can review grants anytime in System Settings → Privacy & Security.

Troubleshooting

• "Clarence can't be opened." Early-access builds aren't notarized yet. Right-click → Open, or run the xattr command.
• An agent's pane shows a shell prompt. The agent exited (or you pressed Ctrl-C). The pane drops to a normal shell on purpose; type the agent command to relaunch, or close the pane and spawn a fresh one.
• Graph tools error with "engine is not running." Start Docker Desktop, then Settings → Graph → Start the engine. Data survives restarts in a Docker volume.
• Voice hotkey does nothing. Check Settings → Voice: enabled, model downloaded, and the right microphone selected. Grant the mic permission when macOS asks.
• Something else? Logs live at ~/.clarence/desktop.log. Ask in the Discord.