Getting started

Before you start

• macOS or Linux, on x64 or arm64.
• The Claude Code CLI (claude), installed and logged in. If claude works in your terminal, Spawnkit can use it. Run claude auth login if it is not logged in yet.
• Node is bundled with Spawnkit, so you do not need to install it.

You do not need a Spawnkit account to run it locally. An account is only for working with a team.

Install

curl -fsSL https://spawnkit.app/install.sh | sh

The installer:

• puts the app in ~/.local/share/spawnkit (its config is spawnkit.env in there),
• links the spawnkit command into ~/.local/bin,
• keeps your data in ~/.spawnkit,
• and starts the daemon at login, with a launchd agent on macOS or a systemd user unit on Linux.

Installer flags:

Open the workbench

spawnkit open

This starts the daemon if it is not running and opens the workbench in your browser athttp://127.0.0.1:4317. The local auth token is passed once and then kept in a cookie, so later visits just work.

If anything looks wrong, run the doctor. Every line should be a check mark, and each failure comes with a fix.

spawnkit doctor

Create a workspace

A workspace is the set of folders you work in. Terminals, files, git and agents are all scoped to the active workspace, so switching workspaces switches all of them.

1. In the navigator, under Workspaces, create a new workspace and give it a name.
2. Add one or more project folders. A crew that works across an API and a web app can have both.
3. Open the workspace to edit it. Besides folders it holds agents, capabilities (the skills and MCP servers its sessions load) and environments (commands and variables for running your services).

Define your agents

Each agent is one Claude Code session with a name, a role description and a model. The role is what the agent is told about its job. A crew that works well for a feature across two repos looks like this:

• orchestrator on Opus: turns the goal into a plan, assigns the work, reviews results and keeps you informed. Does not edit product code.
• backend on Sonnet: owns server-side code and its tests.
• frontend on Sonnet: owns UI code and follows the app’s existing patterns.
• tester on Sonnet: checks the work end to end against each acceptance criterion and reports pass or fail.

Start your first crew

Work happens in a thread: a goal plus the crew working on it. Click New thread in the navigator, or press ⌘ Shift C (Ctrl on Linux).

127.0.0.1:4317

1. Title and goal. Write the goal the way you would brief a colleague: what to build, what is in scope, and what is not.
2. Folders and agents. Pick which of the workspace’s folders and agents take part.
3. Main agent (optional). Untagged messages go to the main agent. Without one, you tag who each message is for.
4. Isolation. Own branch per repo gives the thread a git worktree and branch in each repo, so your checkout is untouched. Work in my checkouts edits your folders directly, on whatever branch is checked out.

Once the thread starts, the agents share one timeline and can message each other. Type @ in the composer to tag an agent. Enter sends, Shift Enter adds a new line, and Esc stops the running turn. You can queue messages while an agent is busy.

Answer what needs you

Needs you is the one place for everything blocked on a person: tool approvals, questions, plans to confirm and messages addressed to you. The status bar counts what is waiting, and each thread shows how many of its agents need you.

• Approvals: allow or deny a tool call.
• Questions: pick an option, or press 1 to 9.
• Plans: approve a plan before the agent acts on it, or send it back.

Review and commit

The thread’s side panel shows the crew, the changes in each repo, files, tasks and the goal. Opensource control with ⌘ Shift G to see status and diffs, stage and unstage, commit with ⌘ Enter, switch branches and push. Terminals live in the bottom panel (⌘ `) and keep their scrollback.

Everyday commands

Keyboard shortcuts

On macOS the modifier is ⌘; elsewhere it is Ctrl.

Where your data lives

Everything is in ~/.spawnkit (set SPAWNKIT_HOME to move it). The folder is readable only by your user.

• Spawnkit never reads your Claude credentials. Logins are written by the Claude CLI itself.
• When you add an account, the MCP servers from your ~/.claude.json are copied into that account’s config so they keep working. Nothing else is copied.
• ANTHROPIC_API_KEY and other auth variables inherited from your shell are removed from agent environments.
• The daemon only listens on 127.0.0.1 and checks Origin and Host on every request.

Working with a team

1. Create an account. It comes with a default org.
2. In the app, set up a shared workspace: its agents, capabilities and folders. Folders are GitHub repo links, not paths, because each member clones the repos with their own git login.
3. Invite your team to the org.
4. Members see the org’s workspaces in their own workbench. When they add one, they choose where each repo lives on their machine, and can start a thread from it like any other workspace.

Sessions always run on each member’s machine with their own Claude login. MCP servers the org hosts run on Spawnkit’s servers, and their secrets never leave them.

Troubleshooting

Start with spawnkit doctor. Then:

• Claude not logged in or not found. Run claude auth login, or add an account in Settings, Accounts and use Log in. For a non-standard binary, set SPAWNKIT_CLAUDE_PATH.
• Port 4317 is in use. Find the process with lsof -nP -iTCP:4317 -sTCP:LISTEN, or run on another port with SPAWNKIT_PORT=4400.
• The daemon will not stay up. Check spawnkit logs. On macOS, launchctl print gui/$(id -u)/ai.spawnkit.daemon shows the launch agent’s state.