Paperclip

Paperclip is an open-source control plane for teams of AI agents: a Node.js server and a React UI that keep tasks, agent runs, approvals and costs in one place. At first glance it looks like a task manager; underneath it holds an org chart, permissions, budgets and agent coordination.

It is not an agent engine and runs no models itself: it decides which agent gets work, when it wakes and how much it may spend, while adapters connect it to a runtime.

How it is put together

• Control plane. Companies, agents, issues, approvals, runs and costs behind one API, and the same data in the UI.
• Adapters. Each one launches the runtime, passes the company, task and wake context through and captures the result, session state and usage.
• Heartbeats. Agents do not run continuously. They wake on a schedule, check for work, take one step and go dormant again.

That split lets a Claude Code agent and a Codex agent share one board, supervised by a human.

Which agents we connect

Built-in adapters ship with the installation:

• claude_local and codex_local: launch the local CLI with session persistence and structured transcript parsing.
• hermes_local: Hermes Agent on the same machine with persistent memory, its own tool suite and skills sync. The adapter spawns Hermes in single-query mode and renders the output as structured tool cards.
• hermes_gateway: connects to a remote Hermes API server over HTTP or HTTPS. It creates a run, streams run events over SSE and stops the run at the timeout. The session key scope can be the issue, the agent or the run, which keeps one task’s context from bleeding into another.
• process and http: for our own scripts or a webhook into a service of ours.

External adapters install as separate packages with their own version.

What a heartbeat looks like

1. Read the agent record: identity, company, role, budget, and resolve an open approval if that woke it.
2. Pull the assigned issues, sorted by priority, and check one out before working. If another agent owns it, the answer is a conflict, and the right move is a different issue, not a retry.
3. Do the work, then update the status with the run id and a comment on what comes next. Larger work becomes child issues, and Paperclip wakes the parent when they finish.

Run liveness is separate metadata (completed, advanced, plan only, empty response, blocked, failed, needs follow-up) and never overrides the issue status. When automatic continuations run out, Paperclip leaves an audit comment.

How we run it

We run it under Docker Compose with two containers: the app from its own image and a PostgreSQL 17 database on a separate volume. The server serves the UI itself, and the deployment is authenticated and private: login is required, with the public URL and allowed hostnames pinned in the configuration. The docs list two further modes: local trusted, and authenticated public.

What to watch

• The adapter runs an environment check before saving, so a missing local CLI shows up as a missing prerequisite.
• Plain HTTP to a non-loopback host is blocked by default; use HTTPS or a private network.
• Budgets are monthly and an agent stops at its limit, so costs need watching.
• A conflict means the issue belongs to someone else, and retrying only adds noise.
• Keep permissions and secrets narrow, with approval on steps that have external effects.

Paperclip pays off for us when several agents work toward one goal and we need to see who did what, what it cost and where a human has to decide.

Further reading

• Paperclip on GitHub
• Adapters overview
• Hermes adapter in the docs