CodeCave

A self-hosted, multiplayer platform for orchestrating AI coding agents.

Your team puts tasks on a board, gives a column an automation rule, and CodeCave starts an agent (Claude Code or Codex) when a task lands there. Each agent works in its own git worktree and branch, comments as it goes, asks you when it is stuck, and reports how sure it is before it hands off. You review the code and merge it from the task.

Everything runs on your machine. Your code, tasks and database stay there.

Website and docs: codecave.ai

Requirements

• Node.js 22 or later
• git
• At least one agent harness, installed and signed in: Claude Code or Codex
• macOS or Linux

Install

npm install -g @codecave-ai/codecave
codecave doctor     # checks Node, git, the database module and your harnesses
codecave start

The package is @codecave-ai/codecave; the command it installs is codecave.

The first start prints a one-time setup link. Open it in a browser, add your activation key, and create the admin account. CodeCave then runs at http://127.0.0.1:3737.

Commands

| Command | What it does | | --- | --- | | codecave / codecave start | Start CodeCave. Stop it with Ctrl+C or codecave stop. | | codecave stop | Stop a running CodeCave. | | codecave status | Whether it is running, and its port, address, data folder and version. | | codecave service install \| start \| stop \| status \| uninstall | Run in the background when you log in. stop pauses it without removing it. | | codecave doctor | Check Node, git, the database module, the data folder and the agent harnesses. | | codecave selftest | Start a throwaway install and prove it works end to end. | | codecave backup | Save the database and config.json to <data-dir>/backups. | | codecave backups | List saved backups, newest first. | | codecave restore [file] | Restore a backup. With no file, pick one from a list. Stop CodeCave first. | | codecave reset | Erase everything except backups and return to first-run setup. | | codecave reset-admin | Locked out? Set a new password for an admin account. | | codecave seed-agents | Add back any default agents that are missing. |

Options

| Option | Default | | --- | --- | | --port <n> | 3737 | | --host <address> | 127.0.0.1 | | --data-dir <path> | ~/.codecave | | --web | Bind 0.0.0.0 so other devices can reach it |

Flags apply to that run only. To keep a port, set it in <data-dir>/config.json.

Each data folder is a separate install and runs one server at a time: starting a folder that is already running stops with the address it is running at. Every command acts on --data-dir, else CODECAVE_DATA_DIR, else ~/.codecave, so for a second install you can set the variable once:

export CODECAVE_DATA_DIR=~/cave-work
codecave start --port 3800

How a task runs

1. A task enters a column with an automation rule.
2. CodeCave creates a worktree under <repo>/.codecave/worktrees on a codecave/… branch and starts the agent there, with a key scoped to that run that expires after 24 hours.
3. The agent reads the task and its comments, claims it, works, comments, and reports its confidence through the built-in codecave MCP server.
4. If it is blocked, it asks one question and the task moves to Needs Input. Reply in the comments and press Resume; the agent continues where it stopped.
5. A clean finish moves the task to the rule's next column. Open the task's Code tab to review the diff and squash-merge it, and push if you want.

Pushing branches is off by default. Turn it on in a project's Settings → Git.

API

Agents that CodeCave starts need no setup. To call the agent API from your own scripts or an MCP client, create a key in a project's Settings → API Keys. Keys are scoped, stored only as a hash, and shown once. The full reference is inside the app at /docs/api.

Your data

Everything lives in the data folder (~/.codecave by default): the SQLite database, config.json and backups. Back it up with codecave backup.

CodeCave makes one outbound call of its own: when you finish setup, it tells codecave.ai the activation key and version, once. It sends nothing else — no project names, paths or code — and nothing depends on that call succeeding.

Develop

npm ci
npm run dev       # hot reload, keeps your data
npm run verify    # type-check, lint, tests, build

Author

Ravi Kaushish

Licence

CodeCave is proprietary software, free to use while it is in early release. It needs an activation key from codecave.ai/activate and it is not open source — see LICENSE.