What Is Paperclip? A Developer's Guide to Running Claude Code and Codex Agents as a Team

Run node --version first. If it prints anything below 24.11, upgrade before you touch the installer. The installer can bootstrap Node for you on macOS and Linux, but only when you download the script and run it locally, not from a pipe.

On Windows the supported route is WSL2. The install script checks for it explicitly, and the background service uses systemd inside WSL2. Native PowerShell can run the npx quick start, but as of this writing every local agent run fails on native Windows, which makes it a dashboard with no workers. Docker is the other Windows option and is covered in step 09.

Install Claude Code, Codex, or OpenCode with npm and run it once by hand so the login is stored. The Claude Code adapter accepts a subscription login, ANTHROPIC_API_KEY, or CLAUDE_CODE_OAUTH_TOKEN. The Codex adapter accepts a ChatGPT login or OPENAI_API_KEY. If the CLI cannot answer a prompt in your terminal, Paperclip cannot fix that.

Pick a working directory for the agent now. The adapter needs an absolute path, and the agent will read and write files there on every heartbeat. A fresh clone of the repository you want worked on is the safe choice.

Two paths exist. The npx path installs nothing permanently and is the right one for a first look. The managed installer downloads a script, verifies its checksum, puts a stable paperclipai shim in ~/.local/bin, and offers to run Paperclip as a background service. Both end at the same dashboard.

The registry flag is not decoration. If your ~/.npmrc points at a private registry such as GitHub Packages, npx resolves paperclipai there and fails with an E404. The README documents this exact failure and the registry flag as its fix.

Onboarding defaults to trusted local mode: loopback only, no login screen. That is correct for a laptop. Add --bind lan or --bind tailnet to switch to authenticated mode if other machines need to reach it.

test-drive is the fastest way to see a heartbeat happen. It writes to a fresh temporary directory, prints that path, ensures one CEO agent exists using the harness you choose, starts the server in the foreground, and opens the dashboard. It never installs a service and never creates a task on its own, so you can watch each thing happen.

Pass the API key for the harness you want. Claude is the default. OpenCode routes through OpenRouter and needs a model id that starts with openrouter/. Reuse the same instance later with --data-dir.

In the dashboard, create a company and give it a goal. The README example is "Build the #1 AI note-taking app to $1M MRR". For a first run, something smaller and checkable is better: "Get the test suite of repo X green and keep it green." Every task an agent creates later carries the goal ancestry in its prompt, so a vague goal produces vague work.

One instance can hold many companies with full data isolation, so you do not need to get this right the first time. Delete the company and start over if the goal was wrong.

Create an agent, give it the CEO role, and choose the claude_local adapter. The only required field is cwd, the absolute working directory from step 02. Optional fields include model, a prompt template, environment variables with secret references, a per-run timeout, and maxTurnsPerRun, which defaults to 300.

Press Test Environment before you save. It confirms the claude command is reachable, checks the directory, reports which auth mode it detected, and sends a live "Respond with hello." probe using the same headless flags a real heartbeat uses. A green result here means the first heartbeat will not fail on plumbing.

One default deserves a pause. dangerouslySkipPermissions is true for this adapter, because a scheduled run has nobody to click Allow. Your agent will edit files and run commands in cwd without asking. Point it at a directory you can afford to reset.

Create an issue with a finish line the agent cannot argue with, assign it to the CEO, and either wait for the assignment trigger or press Invoke. A heartbeat fires on a schedule, on assignment, on an @-mention in a comment, on a manual Invoke, or when an approval resolves. Each heartbeat checks identity, reviews assignments, atomically checks out a task, works, and updates status.

The issue moves backlog to todo to in_progress to in_review to done. Checkout is an atomic operation: if two agents try to claim the same issue, one receives a 409 and moves on. That single rule is most of what people mean when they say orchestration is hard.

Open the run from the issue page. You get structured logs, tool-call traces, the cost event for that heartbeat, and the session id the adapter will resume next time. The Claude Code adapter persists the session between heartbeats so the agent picks up its own context instead of starting cold.

Budgets exist at company and agent level and are stored in cents per month. Cost is tracked per company, agent, project, goal, issue, provider, and model, with a warning threshold before the stop. The heartbeat queue checks budget before it invokes the adapter, so an over-budget agent never starts a run it cannot pay for.

Set a small number first, on the order of a few dollars, and let one week of heartbeats show you the real burn. A CEO that hires and delegates can multiply spend quickly, which is why hire approvals exist: turn them on and every new agent waits for you.

Clone the repository and use the quickstart compose file. It runs one container with the embedded database and persists everything under ./data/docker-paperclip. Two secrets are required at start: one for auth and one for signing tool actions. Pass ANTHROPIC_API_KEY or OPENAI_API_KEY into the container so the bundled CLIs can authenticate.

On Windows, run these from a WSL2 shell with Docker Desktop's WSL integration enabled, so that openssl and the bind mount path behave. If you change the host port or put it behind a domain, set PAPERCLIP_PUBLIC_URL to the address the browser will use.

The service is a systemd user unit on Linux and WSL2 and a LaunchAgent on macOS. It restarts after a crash and can start at login. Only one server process may own an instance: paperclipai run refuses to start while the service is supervising it.

Updates back up the database, verify the new CLI, flip the current symlink, and restart the service. Two previous payloads are kept, so a bad release is one command away from undone. Telemetry is on by default and anonymous; set PAPERCLIP_TELEMETRY_DISABLED=1 or DO_NOT_TRACK=1 if you would rather it were off.