Get started with Crewroom

Crewroom is a Mac app that runs a coding agent on your projects with any model you bring: a plan you already pay for, an API key, or a model on your own Mac. You describe a task in plain words, the agent works in your project and shows every step, and nothing risky happens without your OK. This page takes you from install to your first finished task in about five minutes.

Install

Crewroom runs on macOS. It needs git and tmux, and brings its own copies when your Mac has none, so most people install nothing else.

1. Open the disk imageDrag Crewroom into Applications. The app is code-signed. Apple notarization arrives with the first public release (Coming soon).
2. Open CrewroomA short welcome walks you through four screens: check your Mac, connect a model or your agents, add a project, and your privacy choices.
3. Start your first chatThe last screen opens a chat on your project with a starter prompt ready to send: “Explain this repository to a new teammate.”

bun install
cd web && bun install && bun run build && cd ..
bun run dev            # the daemon, in the foreground
bun src/cli.ts ui      # prints a one-time link that opens the UI
bun src/cli.ts doctor  # checks what is missing

The first-run screens

Every screen can be skipped and changed later in Settings.

Connect a model

Open Settings › Providers › Add. The window lists every connection Crewroom knows, grouped the way the code groups them. Subscriptions sign in through the provider's own page; everything else takes a key.

The full list, how each sign-in works and how effort levels map per provider are on Models & providers.

Your first task

Pick a project in the sidebar, type what you want, and press Enter. The chips under the message box set the model, the effort, how actions are approved, and where the work happens.

What the composer chips mean

Review what changed

Open the right panel's Changes tab (Ctrl 2) to read the diff per file. Click any line to leave a comment; comments wait until you send them together as one review round. Commit changes commits only the files this agent touched, and Undo agent changes puts every file back to how it was when the agent started.

Give it house rules

Crewroom Agent reads the same rule files other agents do. Put an AGENTS.md (or CLAUDE.md) in the project root and every new chat starts with it.

# my-app

## Commands
- Install: `bun install`
- Test: `bun test` (run it before you say a change is done)
- Typecheck: `bun x tsc --noEmit`

## Conventions
- TypeScript, strict mode. No default exports.
- UI strings live in src/i18n/en.ts; never hard-code them.
- Ask before adding a dependency.

Which files load, and in what order, is on Memory › Rule files.

Models & providers

Crewroom's own engine, Crewroom Agent, talks to models directly, so you can use almost any provider: sign in with a plan, paste an API key, or point it at a model running on your Mac. You can switch model in the middle of a chat and keep going. This page lists every connection the code knows, how each signs in, and the two settings that change cost the most: effort and the prompt cache.

Three ways to connect

Sign-ins

Each sign-in follows the provider's own flow. Tokens live only in Crewroom's secrets folder (a 0700 folder, files 0600); no other app's login is read or written.

API key connections

A pasted key is checked with one free GET /models call and saved only when it works. The answer also becomes the model list in the picker: chat models only, the curated models first, then the rest newest first. A key the provider rejects, a key with no credit left, and a rate-limited key each get their own plain message.

Model lists are refreshed in the background once a day per provider (Copilot and the price catalogue hourly). A failed refresh keeps the last good list. To refresh everything now:

crw models --refresh

Effort levels per provider

The effort chip only offers the levels the chosen model takes. When a level is not on a model's ladder, Crewroom rounds it the way that provider's own app does. Open models you have not set run at medium.

Prompt cache (Anthropic)

On an Anthropic key, every turn re-sends the whole conversation. The prompt cache keeps that prefix warm so it is billed at a fraction of the price. Settings › Providers › Anthropic › Prompt cache picks how long it stays warm:

Switching models mid-chat

Pick another model in the composer and the next turn runs on it, with the same conversation. When a turn is running, the switch waits for it to end. Tools adapt to the family: GPT models get Codex's tool set (exec_command, apply_patch, update_plan…), every other model gets Claude Code's (Bash, Edit, TodoWrite…). See Tools & MCP.

How the engine works

Every chat gets its own small background program, the engine, which calls the model and runs the tools. The Crewroom app talks to it over one private channel and keeps a log of everything it does, so a crash, a quit or a sleeping laptop never loses a turn. This page explains the moving parts, from the wire format to the rules that decide when a chat is compacted or stopped.

The picture

The daemon and one engine per chat

Crewroom's background service, the daemon, listens on 127.0.0.1 with a random token and serves the window and paired phones. For each Crewroom Agent chat it starts one engine process:

• The engine is crw agent run --serve, started without a shell, in its own process group, inside a macOS Seatbelt box.
• Its standard output and errors go to engine.log in the chat's folder, token-redacted a line at a time. They can never corrupt the protocol.
• Keys never sit in the engine's environment (which ps would show). The engine asks the daemon for a credential when it needs one, and the daemon handles sign-in refresh and account rotation.
• The engine never opens Crewroom's database.

The pipe: fd 3, one JSON object per line

Daemon and engine speak over file descriptor 3, both ways. The envelope is Codex app-server's: JSON-RPC 2.0 without the "jsonrpc" field, one object per line. The handshake is initialize then initialized, with a 30-second timeout.

{"id":12,"method":"turn/start","params":{"input":[{"type":"text","text":"Add a dark mode toggle"}],"typed":"Add a dark mode toggle","clientIds":[412]}}
{"id":12,"result":{"turn":{"id":"t7","status":"inProgress"}}}
{"method":"turn/started","params":{"turn":{"id":"t7","status":"inProgress"},"endOffset":18342}}
{"method":"item/agentMessage/delta","params":{"turnId":"t7","itemId":"i3","delta":"Reading the settings","offset":0}}
{"method":"item/completed","params":{"turnId":"t7","itemId":"i3","endOffset":19107}}
{"method":"turn/completed","params":{"turn":{"id":"t7","status":"completed","durationMs":48210},"endOffset":26655}}

Errors use four codes: -32700 bad line, -32000 the handler threw (the reader keeps going), -32601 unknown method, -32602 wrong turn state. Streaming deltas are never stored; they are placed by offset and the finished item is read back from the log.

The per-chat log

Each chat's conversation lives in one append-only .jsonl file in Claude Code's transcript shape, so the same parsers, usage readers and hooks work on it. Rules that keep it trustworthy:

• One writer. Only the chat's engine writes it, guarded by a lock file that holds its process id.
• Bytes before news. Each line is on disk before the daemon is told about it; notifications carry only an endOffset.
• Read only what is new. The daemon keeps an index (next_offset, turn rows) that it can rebuild from the log at any time. A torn last line is left alone; a corrupt line is skipped but still counted.
• Engine records. Turn starts and ends, approvals, mode changes and engine exits are written as system lines with crewroom_* subtypes. Your approval decisions are written by the daemon, never by the engine, so the log can never claim you approved something.

Queue and steer

Every message you send goes into the chat's inbox (SQLite) first. What happens next depends on whether a turn is running:

A message counts as delivered only when its id appears on a user line in the log, so a message can never run twice or get lost between the two. The queued list can be paused, resumed, reordered and cleared.

Stop rules

1. Stop pauses the queue first: anything queued before you pressed Stop stays put until you resume.
2. The engine aborts the turn, stops the running shell commands, gives unfinished tool calls an “interrupted by user” result, and tells the model with a short marker that you stopped on purpose.
3. A message you send after Stop runs once the stopped turn has ended.
4. A Stop that lands before a turn's request goes out cancels that request, so a crash's re-delivered turn never starts after you said Stop.
5. If the engine does not confirm within 10 seconds it gets SIGTERM, then SIGKILL at 15 seconds. It leads its own process group, so the whole group is stopped and nothing is left behind.

Crash recovery

When an engine dies mid-turn, or the app quits or restarts during one, the turn is marked interrupted and continues by itself:

• Auto-continue, at most twice. The engine restarts on the same log with a note telling the model the turn was cut off and to check what is already done. If the crash cut tool calls before their results were saved, the note names them: each ran at most once and its result is unknown.
• Only fresh turns. A turn auto-continues only if it was cut within the last hour, and never while it waits on one of your cards.
• Never a loop. The same turn cut by three restarts in a row is suspended with a notice and continues on your next message.
• Lost message, same message. A turn that died before your message reached the log simply runs that message again, without the note.

The idle stop

A chat that sits quiet does not need a live engine. Every second the daemon looks at its engines; one with no open turn, no pending card, nothing queued, no background work (shells, sub-agents, scheduled wake-ups) and no request in flight for engine_idle_minutes (default 60, 0 = never) is stopped. Your next message starts it again from the log in a moment.

Idle compaction

Long chats get summarised (compacted) so they fit the model and cost less. Two idle rules apply:

The first rule never fires for sub-agents, forks, unattended runs or goals, nor when a scheduled wake-up is due before the cache expires. Anything you send while it runs stops it at once, because the cache is still warm and you are back. Its own frames do not keep the engine alive, and a failed attempt is logged, never shown. Turning automatic compaction off turns both rules off.

What the model sees vs what you see

Step limits and the loop guard

A turn stops after 100 tool steps (step_limit) and asks before it keeps going, with a Keep going button. Background helpers, bots and goals, which run while nobody is watching, get 1000 (step_limit_unattended). A loop guard stops a turn that repeats the same call over and over, and non-Claude models are asked once to run the project's checks before they say a code change is done.

Planning & the crew

For a bigger job the agent can plan first, show you the plan, and split the work across helpers that run side by side. Each helper can get its own copy of the project so they never trip over each other, and you decide what gets merged. This page covers plan cards, sub-agents, folder isolation and review.

Plan first

Type /plan (optionally with a description) to turn on plan mode, or ask for a plan. In plan mode the agent reads the code without changing anything and then shows a plan card:

Once work starts, the plan becomes a checklist at the top of the turn that ticks itself off as steps finish, and is closed at wrap-up. Build it in a new chat starts the build in a fresh chat with the plan as its prompt, and the planning chat stops there.

Sub-agents

The agent can start helpers with its Agent tool (on GPT models, Codex's spawn_agent). Built-in helper types:

Helpers run in the background by default and report back when done; the main agent can message a running helper. A helper uses the Sub-agent model setting, or the parent's model when that is empty.

Your own helper types

Drop a Markdown file with frontmatter into .crewroom/agents/ (or Claude Code's .claude/agents/, Cursor's .cursor/agents/, or a Codex .codex/agents/*.toml). Project files win over user files, and .crewroom wins over the others.

---
name: test-writer
description: Writes missing unit tests for a module and runs them until they pass.
tools: Read, Edit, Write, Bash
model: inherit
effort: medium
isolation: worktree
maxTurns: 40
---
You write focused unit tests. Read the module first, cover the edge cases
the code already handles, run the suite, and report which tests you added.

Same-folder isolation

By default a chat works in your project folder itself. Two agents editing one folder would mix their changes, so Crewroom keeps them apart:

• When another chat is busy in the project folder, a new task starts in its own copy of the folder, uncommitted files included. Its edits stay in that copy until you merge them, and the agent is told so.
• A helper started with isolation: worktree also works in its own git worktree.
• If two chats do end up in one folder, the chat shows: “X is also working in this folder: your changes mix.” A change that could be either agent's counts as yours and is never undone.

Review and merge

• Review it yourself. In the Changes tab, click lines to comment, accept hunks or files, and send all comments to the agent as one review round. Manual review is free: no model runs.
• Second opinion. Sends the conversation and the current diff to a reviewer model of your choice, read-only, and puts its review in the chat with its cost.
• Merge. A task on its own branch can be squash-merged into its base on your Mac (“Merged locally into main, not pushed”) or through a pull request. A local merge can be undone with a revert commit.
• Commit. Commit changes commits only the files this agent touched.

Safety

The agent can read your project freely, but every command it runs is boxed in by macOS itself: it can only write where the work happens, and it can never read Crewroom's keys. Anything risky asks you first on a card that shows exactly what will run, and when a command needs a password or a token, you type it into a card the model never sees. This page lists the exact rules.

query run NPM_TOKEN --reason "publish to npm" -- npm publish

Four layers

The shell guard

Every agent shell command runs under macOS Seatbelt with a write allow-list, the same idea as Claude Code's sandbox.filesystem.allowWrite. Reads stay open, so the agent can still read your code, docs and tools.

# writable roots
the working folder and any folders added with /add-dir
the chat's own folders in Crewroom's home
/tmp, $TMPDIR and the per-user temp folder
a worktree's git folder (but never its hooks or config)

# package and tool caches under your home
~/Library/Caches   ~/.cache          ~/.npm             ~/.bun/install/cache
~/.cargo/registry  ~/.cargo/git      go/pkg/mod, sumdb  ~/.gradle/caches
~/.m2/repository   ~/.yarn/berry/cache  ~/Library/pnpm/store  ~/.local/state/pnpm
~/.local/share/uv  ~/.ssh/known_hosts

Mandatory denies

Inside those roots, some names are never writable, wherever they are. These are Claude Code's mandatory denies plus Crewroom's own settings:

• Shell start-up files: .bashrc, .bash_profile, .zshrc, .zprofile, .zshenv, .profile and the rest.
• Git's code-running files: .git/hooks, .git/config, .git/info/attributes, .gitconfig, .gitmodules, ~/.config/git, plus fish's config.
• Editor and agent settings: .vscode, .idea, .mcp.json, .ripgreprc, .claude/commands, .claude/agents, .claude/settings*.json, .crewroom/settings*.json.
• No creating, moving or writing a .git, commondir or gitdir (a planted one could point git at another repository). Deleting a clone with rm -rf still works.
• Your home folder itself, ~/Library/LaunchAgents, app updates staged in the caches, and renaming ~/.crewroom, ~/.claude, ~/.codex or ~/.ssh.

The guard also refuses reads of Crewroom's secrets (stored keys, sign-ins, the database, other chats' tokens, browser profiles) and blocks handing code to a program outside it: launchctl, crontab, at, osascript, open, automator, shortcuts, Apple Events and the browsers' debugging ports.

Leaving the guard

When a command fails on a guard refusal, the agent is told why and can retry the same command outside the guard. That retry always goes through the approval gate: a card in Ask first, the safety check in Auto. A refusal on a credential, a file or a host the task does not involve is meant to stop there, and the agent is told to say so instead of retrying.

Approvals

The access chip in the composer sets how actions are approved. New tasks start in the mode set under Settings › Sessions › Default permissions.

The approval card shows what will happen and makes you look at it:

• A command card shows the whole command; a long one must be scrolled to the end before Allow turns on.
• An edit card shows the change as a diff (first 400 lines).
• Hidden or direction-changing characters are written out as codes, with a warning.
• Always allow in this project says what it covers (for example “Covers: npm commands”) and is saved as a rule you can see in the project's Permissions.
• Commands Crewroom judges dangerous ask even when a rule would allow them.

Allow rules, including Claude Code's

Rules use Claude Code's format and are read from the same places, so the rules you already wrote for Claude Code are respected. A personal allow rule runs that tool without asking, even in Ask first. Settings › Sessions lists your personal rules with the file each came from; each project's own rules are in its Settings › Permissions.

{
  "permissions": {
    "allow": ["Bash(bun test:*)", "Bash(git status)", "Edit(src/**)"],
    "ask": ["Bash(git push:*)"],
    "deny": ["Read(./.env)", "Read(./secrets/**)"]
  }
}

Deny wins over ask, ask over allow. Block reads outside the working directories refuses file-tool reads (Read, Grep, Glob, LSP) outside the project in every mode; add a folder with /add-dir.

The secret card

The model is told never to ask you to paste a key into the chat. When a command needs one, it runs that command through query:

query run NPM_TOKEN --reason "publish to npm" --timeout 300 -- npm publish

1. A Secret request card opens in the chat with the reason, the folder and the whole command. Pass to command stays off until you have scrolled through them.
2. You paste the value into a masked field (password managers are told to stay out).
3. Crewroom itself runs that exact command, in that folder, in the box the chat's engine gives it, with the value only in that one process's environment.
4. The agent gets the command's output and exit code. Never the value. query: cancelled (exit 1) means you declined; exit 124 means nobody answered in time.

Masking in tool output

With Hide secrets from AI models on (the default), keys and passwords in files and command output are masked before they are sent to the model: API key shapes (sk-…, ghp_…, github_pat_…, AKIA… and more), private key blocks, bearer headers, token=…-style assignments and curl -u user:secret. The real values stay on your Mac.

Tool servers and hooks inside the guard

Every stdio MCP server you configure, and every hook, starts under the same guard: Crewroom's secrets are closed, the network is open, and writes go only to its own folder, temp and the tool caches. A server from a project file (.mcp.json) runs only after you approve it, and stops running if its entry changes after that.

A server or hook that genuinely needs your whole disk can run outside the guard. This is only possible for entries in your own user settings, never a project's or a plugin's, and it is saved for that exact entry in ~/.crewroom/settings.json:

{
  "mcpOutsideGuard": [ { "name": "files", "scope": "user", "file": "~/.crewroom/mcp.json", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"], "envHash": "…" } ],
  "hooksOutsideGuard": [ { "source": "~/.claude/settings.json", "command": "~/bin/notify-done.sh" } ]
}

You never write this by hand: use Runs outside the guard on the server's row in Settings › Plugins & MCP, or on the hook in /hooks. A server's environment is kept only as a hash, and a changed entry is no longer trusted.

Outside text

Web pages, MCP results and text from the repository are fenced as content someone else wrote, with an instruction not to follow anything inside. If such text tries to address the model, the model is told to report it with a short quote. Messages between agents and bots have hidden characters stripped.

Keys

Keys and sign-in tokens live in Crewroom's secrets folder (folder 0700, files 0600), never in the database or a settings row. The guard refuses every read of that folder, and the engine gets a credential from the daemon per request instead of from its environment.

Tools & MCP

Tools are what the agent can do: read and edit files, run commands, search the web, start helpers. Crewroom gives each model the tool set its own makers trained it on, adds a few of its own, and lets you plug in any MCP server. This page lists the built-in tools and shows how to add and trust servers.

Two tool sets, one engine

Rarely used tools are not sent up front; the model sees their names and loads one through ToolSearch when it needs it. That keeps every request smaller and the prompt cache stable.

Crewroom's own tools

Web search uses the model's own server-side search where it has one. Otherwise it goes to the first backend you have set up, in this order unless you pick one: Firecrawl, Tavily, Exa, SearXNG, Brave, DuckDuckGo.

Adding an MCP server

Use Settings › Plugins & MCP › Add server, or the command line, which mirrors claude mcp:

# a local (stdio) server, for every project
crw mcp add -s user files -- npx -y @modelcontextprotocol/server-filesystem ~/Projects/my-app

# a remote (HTTP) server, shared with the project through .crewroom/mcp.json
crw mcp add -s project -t http docs https://mcp.example.com/mcp

crw mcp list
crw mcp login docs      # OAuth sign-in for an HTTP server

Or write the file yourself. The format is the one Claude Code and Cursor use:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"],
      "env": { "PGCONNECT_TIMEOUT": "5" }
    },
    "docs": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" }
    }
  }
}

${VAR} and ${VAR:-default} are expanded from your environment, as are Cursor's ${env:VAR}, ${workspaceFolder} and ${userHome}. Per-server startupTimeout and toolTimeout (milliseconds) are honoured.

Where servers come from

Crewroom reads the servers of every tool you use and merges them like Claude Code's scopes: local beats project, which beats user. Within a scope, Crewroom's files beat Claude Code's, which beat Cursor's, which beat Codex's. Crewroom only ever edits its own files.

Trust

• Project servers wait for you. A server from a repository file runs only once you approve it, and the approval pins the entry: if it changes, it does not run until you approve again. The approval says plainly when an entry pulls a key-shaped environment variable.
• Malware check. Before an npx or uvx server starts, its package is checked against the OSV database for known-malicious advisories. A failed lookup is shown as “unchecked”.
• Per-tool choices. Each server's tools are grouped as Read-only, Write/delete and Other. Set each to Always allow, Needs approval or Blocked. Tools marked read-only by the server run without asking unless a rule says otherwise.
• Inside the guard. Stdio servers run under the shell guard unless you take a user-scope server out of it.

Hooks

Hooks use Claude Code's protocol: JSON on stdin; exit 0 is fine (stdout JSON is read), exit 2 blocks, anything else is a non-blocking error. Project hooks load only in a folder you trust, and not after they change.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [ { "type": "command", "command": "jq -r .tool_input.file_path | xargs bun x prettier --write" } ]
      }
    ]
  }
}

Bots & schedules

A bot is an agent with a standing job: a role, its own chat and workspace, and a schedule or a trigger that starts it. You set it up once from a template, and it reports back when something needs you. This page covers templates, schedule kinds, triggers and what a bot is allowed to touch.

Templates

Every template comes with standing instructions (its soul.md), access limits and sometimes a schedule. Change anything before you create it.

Schedule kinds

A bot can also ask you for a schedule from its chat. It proposes one, and nothing changes until you approve it:

crw bot schedule propose "cron 0 9 * * 1-5" "weekday stand-up notes before the 9:30 call"
crw bot schedule propose "daily 09:00" "morning summary"
crw bot schedule propose "every 90" "check the status page"   # minutes

What to do on each run is the message every scheduled run starts with. Leave it empty and the bot checks its tasks and carries on with its role.

Triggers and Run now

Besides its schedule, a bot can start when:

• CI failure — a check fails in the project;
• Labelled issue — an issue gets the label it watches;
• PR review comment — someone comments on a pull request;
• Message from another bot — a bot it accepts messages from writes to it.

To run a bot right now, open its row menu in the sidebar and pick Run now. A paused bot shows no Run now and ignores its triggers.

What a bot may touch

• Access: reads of project files, project memory and documents; writes to documents and its own workspace. Enforced by the sandbox: any other write is blocked.
• Approval mode: Ask first, Auto-accept edits, or Full access. Each scheduled run starts its agent without asking, and scheduled or bot-started runs never get more than the bot's own mode.
• Computer: off (terminal only), a managed headless web browser, or a full Linux desktop in Docker. On a CAPTCHA, bot check or login wall the bot stops and asks you; it never tries to solve or bypass one.
• Keys: a bot's key works only for its own chat. Bot-to-bot messages have hidden characters stripped and are limited to the bots you allow (“May message”).
• Spend: the bot's card shows today's and the last 7 days' cost.

Memory

Crewroom keeps what agents learn on a project, the decisions, the gotchas, the mistakes not to repeat, and hands the relevant pieces to the next task. Memory lives on your Mac, one store per project, and you can read, pin, correct or forget every entry. Rule files like AGENTS.md sit next to it for the things you want said every time.

How recall works

Memory is stored in Crewroom's local database, one per project. When a new task starts, the pinned entries and the entries that match the task go in front of its first prompt as a Project memory section, up to the size limit (1,500 characters by default). Entries marked wrong are never recalled. Nothing in your own agent config changes.

Four kinds of entry

Entries come from three places: the agent saves them with its memory tools, capture rules pick them up when a chat ends, and you add them yourself. Hover any message and choose Remember this, then Remember this as a type. Each entry records its source chat and evidence, and shows a tier: Observed, Human or Agent claim.

Recently learned, forget and correct

• Recently learned lists what agents and capture rules saved lately, newest first. Agents use these right away; Forget takes one out of recall.
• Pin an entry to recall it in every task; Mark wrong to keep it but never recall it; Edit or Delete it.
• Select several and Forget selected; a preview lists exactly what goes.
• Missed lists chats that ended without leaving anything in memory. Capture now reads that chat with your chosen model and adds what it finds to Pending.

Entries also age on their own:

Sharing across projects

An entry belongs to its project. Share with all my projects lets every project on this Mac find and recall it, which suits habits and personal preferences. Promote to AGENTS.md turns an entry into a line in the project's AGENTS.md; you review the line first and nothing is written until you confirm.

Rule files

Rule files are instructions you write and want in every chat. Crewroom Agent reads, for each folder from the repository root down:

AGENTS.md
CREWROOM.md
.crewroom/rules/*.md
CLAUDE.md
.claude/CLAUDE.md
.claude/rules/*.md          (a file of the same name in .crewroom/rules wins)
AGENTS.local.md  CREWROOM.local.md  CLAUDE.local.md

And globally: your own ~/.crewroom/AGENTS.md, always. Claude Code's ~/.claude/CLAUDE.md (with ~/.claude/rules/) and Codex's ~/.codex/AGENTS.md load only when you opt in with Global rules (engine_global_rules: off, claude, codex or both). They are off by default because they often carry orders meant for that one tool.

Dashboards

A dashboard is a board of small live widgets that an agent builds for you: describe what you want to see, and it writes the widget and the automation that keeps it fresh. Crewroom's own numbers (spend, agent activity, plan quota) are there as built-in widgets. Open Dashboards in the left rail.

The parts

The shapes follow Kimi's Blueprint tools, so skills written for those work here too. The same operations are open to the UI, the REST API and crw dashboard.

Built-in widgets and starters

• Add a Crewroom widget: Tokens & cost, Agent activity, Plan quota.
• New installs start with two sample dashboards to try: Dashboard basics and Hello Crewroom. A Daily Finance starter can be added too.

When automations run

The runner looks every 30 seconds and runs at most two automations at once. A slot more than a minute late is skipped, not caught up, and every run has a timeout. Each widget keeps its last 20 runs with their status (Succeeded, Failed, Running, Cancelled); View task opens the chat that ran it.

Cost view

The Usage page shows what you spent, where the tokens went, and what is wasting money, with a one-click fix where one exists. Plan limits always show as how much is left. Numbers Crewroom can measure are labelled as measured, the rest are marked as estimates, and nothing is dressed up.

Summary

Open Usage from the sidebar (or the rail when the sidebar is folded). The Summary tab answers “what did I spend, and on what”:

• Spend for the selected days, compared with the same number of days before.
• Where it went: input, output, cache read and cache write, in tokens and dollars; the share of prompt tokens that came from the cache; and By provider, one bar and one legend from the same provider list.
• Where the tokens come from: the categories below.
• Top waste: up to three findings, ranked by estimated dollars saved.
• Plan limits: always “N% left”, never “% used”.

Categories, “estimated” and “needs new tracking”

Where the tokens come from splits every chat active in the period, over its whole life, into categories. Only Crewroom Agent chats can be measured this way, from the engine's own context breakdown; other agents report their totals only. A coverage line says how much of the spend that is: “Covers $X of $Y spent: Crewroom Agent chats only”.

Advanced

Advanced goes deeper: Memory and Tools and MCP in detail, the full Waste list with CodeBurn's Health grade (its 21 checks over the period, measured again on every run) and the Applied fixes history with Undo, Cache and time, Plan limits in detail, the ledger, run numbers and the context weight card. Each chat's row shows its cost in the selected days; its drawer shows the full cost of the chat.

Waste findings, Apply and Undo

Findings come from CodeBurn. Each one is tagged Fix, Habit or FYI, says whether it is improving or still happening, and estimates the saving per 30 days.

1. Apply appears only when CodeBurn can make the change itself. A dry run first lists the files it will change.
2. You confirm. CodeBurn backs up every file it touches, makes the change, and the finding shows Applied.
3. Undo, in Advanced › Applied fixes, puts the files back. If a file changed since, CodeBurn's own refusal is shown.

A finding CodeBurn cannot apply from here gets Ask agent, which starts a chat with the finding and asks the agent to show each edit before making it. An FYI finding gets Review.

About CodeBurn

CodeBurn is a separate, open-source spend analyser that Crewroom runs for spend by day, token kinds, models, the waste findings and their fixes. Without it the page says what is missing (“CodeBurn is not installed: spend by day, token kinds and models need it”) and the per-chat numbers Crewroom measures itself still show. CodeBurn never runs in the daemon's own folder.

Inside a chat

The ring in the composer shows how full the context is, with the numbers on hover. The chat's cost breakdown splits it by item: Main agent, Compaction summary, Page summary, Advisor and Second opinion.

Phone app

The Crewroom iPhone app connects to the Crewroom on your Mac, so you can follow chats, answer approval cards and steer the agent while you are away from the desk. Nothing runs on the phone: the work stays on your Mac, and the phone only gets what you allow it.

Pairing

1. Turn on remote accessOn the Mac, open Settings › Phone & remote and turn on Let your phone control this Mac. It is off by default.
2. Choose where to listenAutomatic uses Tailscale first, then your local network. This Mac only is for a tunnel you run yourself.
3. Scan the QR codeScan it with the phone. The Mac shows Allow “iPhone”? with a code; check that your phone shows the same code, then press Allow.
4. Set its rightsEach phone gets its own rights: Read, Operate, Approve, Source control, Terminal. Every phone action is logged with the device name.

Access from anywhere

To reach your Mac when you are out, turn on a tunnel you already have: Tailscale (only your own devices), Tailscale Funnel (public internet) or a Cloudflare quick tunnel (public internet; the address changes each time, so phones pair again). Crewroom never installs anything or signs in for you. Remote access turns itself off after a set number of hours unused (12 by default).

What you can do

Notifications

Approvals and finished tasks can reach the phone's lock screen through Apple's push service. This needs your own APNs key: create one at developer.apple.com, save the .p8 file where Settings › Phone & remote shows, and enter its Key ID and your Team ID.

Keyboard shortcuts

Every shortcut below is a default from the app's own shortcut table. Change any of them in Settings › Keyboard shortcuts; Crewroom stores only the ones you changed, so new defaults still reach you. Punctuation shortcuts match the typed character, so ⌘ [ works on layouts like German where [ needs ⌥.

General

Moving around

In a chat

The right panel

Settings reference

Settings are grouped the way the Settings window groups them: Personal, Agents, Integrations and System. The tables list the settings that change how the agent behaves, with the key Crewroom stores, its default and what it does. Keys outside this list are refused by the settings API, so this is the whole surface for those areas.

The Settings window

The search box at the top of Settings finds a row on any tab.

Agent behaviour

Engine and sessions

Memory, notifications, network

Settings files

Besides the app's own settings, Crewroom reads the files other agents use, so one setup works everywhere:

Architecture

Crewroom is a local system of a few small parts: a background daemon that owns state, one engine process per chat, a window and a phone that only talk to the daemon, and the guard around everything that runs commands. This page shows how they fit and where each one lives in the code.

How the parts connect

The whole system

The parts

One message, end to end

1. The window posts your message; the daemon stores it in the chat's inbox.
2. The daemon starts the chat's engine if it is not running (single start, waiting for a dying one to exit), then sends turn/start over fd 3.
3. The engine writes a turn-start line and your message to the log, then calls the model with a credential it asked the daemon for.
4. Tool calls run in the engine; shell commands, MCP servers and hooks run under the guard. Anything that needs you becomes a request to the daemon, which shows a card and writes your decision.
5. Each finished item is appended to the log; the daemon reads the new bytes, updates its index and pushes chat items to the window and phone.
6. At the turn's end the daemon marks the message delivered, sends notifications, and starts the next queued message if there is one.

What talks to the network

• The engine, to the model providers you connected (and web search, MCP servers and pages the agent opens).
• The daemon, for model lists of connected providers, and, only when you turned them on, the price catalogue and the update check.
• Paired phones, over the address you chose. Remote access is off by default.
• Webhooks, only to the address you set.

Roadmap

What is queued next, grouped by area and in plain words. Everything here is planned, not shipped; anything elsewhere in these docs marked Coming soon is listed here too. The order inside a group is roughly the build order.

Changelog

The recent stable builds and what changed for you in each, newest first. Each build is a tagged commit that was installed and checked before it was tagged. Test-only and internal changes are left out.