Paperclip: an org chart and budget layer for teams of AI agents

The problem: many agents, no shared record of who is doing what

Running one coding agent is a session. Running six of them across two providers is a coordination problem, and the README names it directly: the situation where you have 20 Claude Code tabs open and cannot track which one does what, and where a reboot loses the context. Paperclip is aimed at that second situation. It is a Node.js server plus a React UI that treats agents as staff rather than as terminals. The README frames the split as "If OpenClaw is an employee, Paperclip is the company", which is a useful way to read the scope: Paperclip does not try to be a better coding agent, it tries to be the place where several of them are hired, given goals, funded and reviewed. The audience is people running several agents from different providers at once, and people who want a record of agent work that survives a restart. The repository layout backs this up: there are adapter packages for claude-local, codex-local, cursor-local, cursor-cloud and gemini-local, so the product assumes a mixed fleet rather than a single vendor.

How Paperclip works: tasks, heartbeats, org chart and budgets

The README describes four pillars: an agentic task manager, an org chart for agents, agent employee training, and an agentic OS layer for runtime, sandboxing and cost control. The mechanism that ties them together is the heartbeat. Agents wake on a schedule, check work, and act, and delegation flows up and down the org chart. That means Paperclip is not a chat interface that waits for you to type. It is a scheduler and a queue: work is expressed as tickets, tickets are attached to roles, roles sit under other roles, and each agent polls for what is assigned to it. The README also states that tasks are ticket-based, conversations are threaded, and sessions persist across reboots, which is the concrete difference from keeping tabs open. Cost control is per-agent monthly budgets, and the README says that when an agent hits its limit it stops. Governance is a separate layer: approving hires, overriding strategy, pausing or terminating any agent. The README claims every conversation and tool call is traced in an immutable audit log, and that one deployment can hold multiple organizations with data isolation between them. Those are the load-bearing claims. The README does not describe the storage schema or how isolation is enforced, so treat multi-organization isolation as something to verify in the docs before you put two customers on one instance.

Installing Paperclip and running it for the first time

The repository is a pnpm workspace with separate server, ui and cli packages, and the Dockerfile builds on node:24-trixie-slim. The .env.example file is the clearest statement of what the server needs to start: a Postgres connection string, a port, and two secrets. Copy it to .env and fill in the values.

cp .env.example .env

The defaults in that file point at a local Postgres instance on port 5432 and run the server on port 3100, with the UI not served by the server.

DATABASE_URL=postgres://paperclip:paperclip@localhost:5432/paperclip
PORT=3100
SERVE_UI=false
BETTER_AUTH_SECRET=paperclip-dev-secret
PAPERCLIP_TOOL_ACTION_SIGNING_SECRET=paperclip-dev-tool-action-signing-secret-change-me

The two secrets are development placeholders. The variable names make the intent clear: one signs authentication, the other signs tool actions, so both need real values outside a local machine. With Postgres reachable and the env file in place, the root package.json exposes a single development entry point that runs the server and the UI together.

pnpm install
pnpm run dev:both

The dev:both script is defined in package.json as node scripts/dev-both.mjs. If you only want the backend, pnpm run dev:server runs the server package on its own, and pnpm run dev:ui runs the UI package. Once the UI is up, the README's own first-run sequence is a three-step loop: define the goal, hire the team, then approve and run. Concretely, you create an organization, add agents as roles under it, point each role at a provider through its adapter, set a monthly budget, and let the heartbeat schedule take over. The README gives "Build the #1 AI note-taking app to $1M MRR" as the shape of a goal statement, and lists OpenClaw, Claude Code, Codex, Cursor, Bash and HTTP as things that can be attached. The rule the README states is "If it can receive a heartbeat, it's hired."

Where Paperclip is the wrong tool

Paperclip adds a database, a server process, a UI and an org model before it does any work. If you run one agent in one terminal and read its diffs yourself, none of that pays for itself, and the setup cost is real: you need Postgres, Node.js 24 in the container image, and two secrets managed properly. The README also does not document rollback, so if an agent commits something wrong, the recovery path is your own version control, not a Paperclip feature. The audit log is described as immutable, which is good for review and unhelpful if you need to correct a record. Budget enforcement is described as a hard stop at the monthly limit, which is simple but coarse: there is no documented notion of a per-task cap or a soft warning threshold in the README. Multi-organization isolation is claimed but not explained, so running two unrelated companies on one deployment is a decision to make after reading docs.paperclip.ing, not from the README. Finally, the project is TypeScript and Node throughout, so teams without a Node runtime in their infrastructure are taking on a new runtime to get a coordination layer.

How Paperclip differs from a plain agent runner

A general agent runner such as Claude Code or Codex is built around a session: you start it, it works in a directory, and you review the result. Paperclip inverts that. It assumes the agents already exist and instead owns assignment, budget and review. The practical difference shows up in three places. First, persistence: the README states sessions persist across reboots because state lives in tickets rather than in terminal scrollback. Second, hierarchy: a runner has no concept of one agent reporting to another, while Paperclip's delegation flows up and down an org chart. Third, spend: a runner bills whatever the provider bills, while Paperclip puts a monthly budget on each agent and stops it at the limit. The trade-off is that Paperclip cannot run without those agents underneath it. It is a control plane, and a control plane with no workers does nothing. If your problem is that one agent is not good enough, Paperclip will not fix it. If your problem is that five agents are good enough but you cannot see them, that is the case it was built for.

Maintenance, licensing and what a self-hosted upgrade costs

The repository is not archived, and the last push was on 2026-08-25, with releases v2026.824.1 and v2026.824.0 on the same day and v2026.817.0 a week earlier. That is a frequent release cadence, and the version scheme is date-based, so upgrades are expected to be routine rather than rare. The cost of that cadence is that you are operating a server, a UI and a Postgres database yourself: the Dockerfile shows a multi-stage build with a deps stage that copies each workspace package.json individually, which means adding or removing a workspace package is a change to the Dockerfile as well as to pnpm-workspace.yaml. The .env.example also shows operational knobs that imply load you may have to tune, including PAPERCLIP_WORKSPACE_GIT_SCAN_CONCURRENCY and PAPERCLIP_WORKSPACE_GIT_SCAN_QUEUE_CAPACITY for workspace Git scans, and PAPERCLIP_HTTP_ADAPTER_PRIVATE_ENDPOINT_ALLOWLIST for HTTP adapters that need to reach private origins. The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are kept. That is a permissive licence, and it also means no warranty and no support obligation from the authors; if you need a support contract or an indemnity, MIT does not provide one. This is not legal advice, and the licence file in the repository is the authoritative text.

Editorial conclusion

Adopt Paperclip if you already run several agents from different providers and lose track of which one is doing what, and you want tickets, org roles and per-agent monthly budgets in one place. Do not adopt it if a single agent in a single terminal is enough for you, or if you need a hosted product with no Postgres and no Node.js runtime to operate. Before committing, verify the current install path against docs.paperclip.ing rather than the README alone, confirm which adapters ship in the packages/adapters directory for the agents you actually run, and check that the budget enforcement behaviour matches how you expect an agent to stop when its monthly limit is reached.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes