Retrieved article excerpt
Open article · Retrieved 2026-09-29T04:26:21.117825+00:00
# Caffold
Caffold is a self-hosted workspace for running and reviewing coding-agent work
from any screen. Keep Codex, Claude Code, or Grok working on a Mac you control, then
follow the conversation, answer approvals, inspect commands and tests, and read
the actual files and diff from a desktop, foldable, tablet, or phone.
The user manual is at [caffold.dev](https://caffold.dev).
The layout adapts to the screen; the workflow stays the same. A Task still
contains one agent conversation and the repository context needed to judge its
work. Start on one device, leave the turn running on the Mac, and return from
another to decide what happens next by text or voice.
Caffold is not a hosted agent or a replacement harness. The agent CLIs,
repositories, credentials, conversations, and execution remain on your Mac.
## What it looks like
[A finished Caffold Task with its conversation, current plan, and the Task list](https://github.com/panarch/caffold/blob/main/website/docs/assets/screenshots/task-conversation-desktop.png)
*Follow a Task as it runs, then read the result and decide what comes next.*
[The same Caffold Task's changed files and diff in Working Tree](https://github.com/panarch/caffold/blob/main/website/docs/assets/screenshots/review-working-tree-desktop.png)
*Open Working Tree to review the actual files and diff without leaving the
Task.*
*These images show a Codex Task. Claude and Grok Tasks use the same
Conversation and review workspace.*
## One workspace, native agents
When you create a Task, choosing a model also chooses the agent that provides
it. Caffold currently supports:
- **Codex**, through its persistent app-server runtime;
- **Claude Code**, through its CLI protocol and a Caffold runner that keeps the
CLI process attached while the backend is replaced; and
- **Grok**, through the Grok CLI's leader process and stdio agent protocol,
with a leader Caffold starts for itself that holds sessions across backend
replacement.
A Task remains bound to that agent for its lifetime. Its model, reasoning or
effort choices, permission modes, tools, session behavior, and transcript come
from the selected agent rather than from a Caffold reimplementation.
This is deliberate. A coding agent is the model together with the harness its
authors built around it. Caffold gives Codex, Claude, and Grok separate native
drivers so it can preserve those harnesses instead of forcing them through a
lowest common denominator. It normalizes only the product concepts the workspace must
present consistently: conversations, turns, activity, approvals, and the
operations a Task can actually perform.
See [Agent runtimes](https://github.com/panarch/caffold/blob/main/docs/architecture/agent-runtimes.md) for the design and the
different state, transport, and recovery boundaries of the two integrations.
## How it works
Only one machine does the actual work. Install `Caffold Server.app` on the Mac
that has the agent CLIs, Git, and your checkouts. The app stays in the menu bar,
keeps the Caffold backend available, and connects the browser interface to the
selected agent and the files on that Mac.
```
browser or installed PWA
(desktop, foldable, tablet, phone)
|
local URL or private
Tailscale HTTPS URL
|
Caffold Server on Mac
/ | \
Codex Claude runner Grok leader
app-server -> claude CLI -> grok bridge
\ | /
Git checkouts and worktrees
```
On the host Mac, `Open Caffold` opens the local address. On another device,
Tailscale Serve can provide a private HTTPS address. Configure and copy that
address from **Settings → Remote Access**; the ready page also provides a QR
code for another permitted device.
Each browser or installed PWA is a window onto the same Mac, not another copy
of the server. Closing it does not end a turn, but the Mac must stay awake,
running Caffold, and reachable for remote use.
## A typical Task
1. Start a Task in the directory where the work belongs and choose a Codex,
Claude, or Grok model.
2. Follow the conversation and answer the agent's approval requests while it
works.
3. Read the result, command and test output, changed files, and actual diff.
4. Type or dictate the next instruction, steer an active turn, or return later
and continue the same Task.
For longer turns, each browser can opt in to system notifications under
**Settings → Notifications**, for a turn that ends and for a Task waiting on an
approval.
Caffold also keeps the Task connected to its repository, optional managed
worktree, Git history, and read-only GitHub Issue or Pull Request context. When
you want to check something yourself, each Task and Section has a terminal in
its working directory that keeps running on the Mac while you move between
devices.
## Install on macOS
Caffold supports Apple silicon Macs running macOS 14 or later. Install and sign
in to at least one supported agent:
- the official standalone Codex CLI `0.155.1` or newer;
- Claude Code `2.1.259` or newer, available as `claude` on the app's `PATH`; or
- the Grok CLI `1.0.30` or newer, available as `grok` on the app's `PATH` or
at `~/.grok/bin/grok` or `~/.local/bin/grok`.
Any of them may be installed, and Caffold will offer the models it can reach.
[Set up your agents](https://github.com/panarch/caffold/blob/main/website/docs/get-started/agents.md) in the user manual has
the agent-specific setup.
Install Caffold with Homebrew:
```
brew install --cask panarch/tap/caffold
```
Launch `Caffold Server` from Applications, then choose `Open Caffold` from its
menu-bar menu.
## With or without a keyboard
Every action in Caffold works from the keyboard. If one doesn't, that's a bug.
Press `F` and a short code appears on each action in view; `S` does the same
for areas that scroll, and key combinations reach the terminal, the side panel,
and those codes even while you type. See
[Keyboard navigation](https://github.com/panarch/caffold/blob/main/website/docs/keyboard.md).
You can also work without one. The Task composer supports multilingual voice
input. Under **Settings → Voice Input**, choose Whisper to transcribe on the
Mac after a one-time model download (about 1.5 GiB), or OpenAI, Gemini, or
Grok to transcribe with your own API key. Audio goes from the browser to your
Mac, which transcribes it or forwards it to the chosen provider; Caffold never
stores the recordings.
Voice is useful here for the same reason the browser interface is useful: much
of the work is giving direction, reading what happened, and following up.
## Current limits
Caffold assumes one trusted user, one trusted Mac, and a private network. It
does not provide authentication for a public deployment or multi-user
authorization.
Agent support is built in rather than loaded as a runtime plugin. Caffold
currently drives Codex, Claude Code, and Grok; it does not provide an ACP
driver or let an existing Task switch agents.
Its Git and GitHub views are deliberately review-oriented. Caffold does not
provide a full editor, and it does not expose stage, commit, checkout, merge,
rebase, reset, stash, publication, or review mutation controls. Those
operations can still be requested through the Task's agent, typed into the
Task's terminal, or performed with the developer tools you already use. Each
Task keeps one terminal, which ends when the Caffold backend stops.
Managed-worktree preparation is explicit, and Caffold only cleans up worktrees
that it created and recorded. The complete implemented scope and limitations
are tracked in [Current Product Status](https://github.com/panarch/caffold/blob/main/docs/product/status.md).
## Documentation and development
- [User manual](https://caffold.dev), with its pages in
[website/docs](https://github.com/panarch/caffold/blob/main/website/docs/get-started/how-caffold-works.md), starting with
[Install](https://github.com/panarch/caffold/blob/main/website/docs/get-started/install.md)
- [Product vision](https://github.com/panarch/caffold/blob/main/docs/product/vision.md)
- [Current product status](https://github.com/panarch/caffold/blob/main/docs/product/status.md)
- [Product workflows](https://github.com/panarch/caffold/blob/main/docs/product/workflows.md)
- [Agent runtime architecture](https://github.com/panarch/caffold/blob/main/docs/architecture/agent-runtimes.md)
- [Roadmap](https://github.com/panarch/caffold/blob/main/docs/product/roadmap.md)
- [Contributing](https://github.com/panarch/caffold/blob/main/CONTRIBUTING.md)
- [Testing](https://github.com/panarch/caffold/blob/main/docs/development/testing.md)
The complete [documentation index](https://github.com/panarch/caffold/blob/main/docs/README.md) groups product,
architecture, development, review, and maintainer material by purpose. Caffold
is available under the [Apache License 2.0](https://github.com/panarch/caffold/blob/main/LICENSE).