Paperclip: How to Manage a Team of Claude Code and Codex Agents
Paperclip is an open-source tool for organizing Claude Code, Codex, and other AI agents into teams with tasks, reviews, and budgets.
What is Paperclip and what problem does it solve?
Paperclip is an open-source app for coordinating multiple AI coding agents, such as Claude Code and Codex, so you don’t have to manually manage handoffs between them. Running a single agent is simple: give it a task, check the output, ask for fixes. Running several agents at once (one implementing, one reviewing, one researching) creates a coordination problem. Someone has to track the overall goal, define who owns what, pass work between agents, and watch what the whole thing costs. Paperclip sits on top of the agents you already use and handles that organizational layer: assigning tasks, routing work between agents, and keeping a record of what happened.
TL;DR
- Paperclip is open source under the MIT license and free to self-host; model usage, subscriptions, and hosting costs are separate and billed by the providers you connect.
- It works through adapters for tools including Claude Code, Codex, Gemini CLI, Cursor, Open Code, and Pi, plus integration paths for custom processes and HTTP services.
- Teams are organized around a company (called an “organization” in the interface) with a goal, projects, and a CEO-style agent that proposes plans and delegates to other agents.
- Tasks support review stages and final approval gates, so a coding agent’s “done” claim gets checked by a reviewer before anything is marked complete.
- An experimental isolated workspace feature can give each task its own git worktree and branch, though you still have to review and merge the results yourself.
- You can set budgets with warning thresholds and hard stops at the company, agent, or project level, but enforcement relies on reported usage, so in-progress work can overshoot before a stop takes effect.
- Routines and shared skills let you schedule recurring jobs (like a weekly summary) and reuse written procedures (like a review checklist) across agents, with version history you can roll back.
One coffee. One working app.
You bring the idea. Remy manages the project.
How does Paperclip organize a team of agents?
Paperclip’s structure borrows the language of a company. You create an organization, give it a goal, and connect projects to that goal. The documented setup starts with a CEO agent whose job is to read the goal, propose a plan, and delegate pieces of work to other agents. Those agents can report up to the CEO, or you can build a deeper hierarchy with managers and workers in between. You remain above all of it as the person approving plans and hires.
In practice, a small setup works better than a sprawling one. For a simple app, you don’t need several layers of management agents debating what a front-end agent should do. A coordinator plus two or three agents with clearly defined jobs is a more sensible starting point than recreating an entire org chart for a basic project.
The coordinator creates tasks and assigns them to the agents reporting to it. Agents post updates as they work, and blockers travel back up the chain, giving you a trail from the original request down to the specific piece of work that’s stuck. Each task holds a brief, comments, and progress updates, and you can filter by status or assignee to see what’s moving and what isn’t.
How do review stages and task handoffs work?
Tasks are where the actual coordination happens. You can configure a review stage so that when a coding agent tries to close a task, Paperclip routes it to a reviewer instead of closing it automatically. If the reviewer requests changes, the task goes back to the original agent. You can also add a final approval stage on top of that, so a human (or another agent) checks the running result before anything counts as finished.
This matters because an agent reporting that it’s done is the start of verification, not the end of it. For something like a notes app, a reviewer needs a concrete checklist: can it create and edit notes, does deleting one remove the correct item, does the data survive a page refresh. Those are testable criteria a reviewer can actually judge, rather than a vague “does it work.”
There’s also a checkout mechanism that stops two agent runs from claiming the same task at once. That solves task-level collisions, but two different tasks can still touch the same code. For that, Paperclip has an experimental isolated workspace feature that can give a task its own git worktree and branch, keeping coding changes in a separate working copy. You still have to review and combine those branches afterward; isolation doesn’t substitute for a merge review.
How do you set up a small agent team in Paperclip?
The basic local setup requires Node version 24.11 or newer. Running npx paperclip-ai@latest onboard (with the flag for accepting defaults) starts Paperclip locally using an embedded PostgreSQL database, so there’s no separate database server to configure for a first run.
Remy doesn't write the code. It manages the agents who do.
Remy runs the project. The specialists do the work. You work with the PM, not the implementers.
You also need whatever agent runtime you plan to connect. If you’re using a local Claude Code or Codex adapter, that CLI needs to be installed and authenticated on the same machine running Paperclip. You don’t necessarily need separate API access either; adapter documentation supports logging in through an existing subscription as well as API keys, depending on the adapter and how it’s configured. It’s worth checking which account method applies before running real tasks.
Inside Paperclip, name the organization and configure the first agent: pick its adapter, model, and working directory, then use the test environment option to confirm the connection before adding more agents. Troubleshooting one broken agent is manageable; troubleshooting five is not.
From there, define the goal clearly. A realistic example: build a local notes app with persistent storage, include tests for the main actions, and provide run instructions, explicitly excluding accounts and payments from the first version. A coordinator, an implementation agent, and a review agent cover the roles needed for something this size. When the coordinator proposes its strategy, read it before approving. If it suggests building a backend service and authentication system for a small local demo, send it back and ask for something scoped to the actual request.
Is Paperclip worth the overhead for small teams?
It depends on whether you’re already losing time to coordination. If you have several agents working on related tasks and find yourself manually tracking who’s doing what, the task history and review handoffs in Paperclip are the parts worth evaluating first. If you mostly fire off short one-off requests to a single coding agent, setting up an organization, hierarchy, and review stages is probably more structure than the work needs. Building a full company setup just to rename a few variables isn’t a good use of the tool.
The “autonomous company” framing is worth treating skeptically too. Giving an agent a CEO title doesn’t make it good at deciding what to build. The quality of the output still depends on a clear goal, specific instructions, and someone checking the result closely, the same requirements that apply to running a single agent.
What does it cost to run a team of agents in Paperclip?
Paperclip itself is free to self-host under the MIT license. The cost comes from everything underneath it: model usage, existing subscriptions, and any hosting you add. Connecting multiple agents through Paperclip doesn’t grant extra access to those underlying services; you’re still paying for whatever each agent consumes.
You can track reported spending and set budgets at the company, agent, or project level, with warning thresholds and configurable hard stops. The caveat is that enforcement relies on recorded spending and usage reporting, so work already in progress can push past the limit before a stop takes effect. A budget setting is a guardrail, not a guaranteed ceiling. A sensible approach is running one small task first, checking actual usage, and then deciding how much budget to give each agent going forward, since a reviewer sending work back and forth with an implementer adds usage on top of the core task.
Frequently Asked Questions
What agent tools does Paperclip support?
It supports adapters for Claude Code, Codex, Gemini CLI, Cursor, Open Code, and Pi, along with integration paths for custom processes and HTTP services. An adapter is the connection that lets Paperclip start an agent and collect the results of its run; you still configure the runtime itself separately.
Remy doesn't build the plumbing. It inherits it.
Other agents wire up auth, databases, models, and integrations from scratch every time you ask them to build something.
Remy ships with all of it from MindStudio — so every cycle goes into the app you actually want.
Does Paperclip cost money to use?
Paperclip is open source and free to self-host under the MIT license. You still pay for whatever model usage, API access, or subscriptions the connected agents consume, plus any hosting you choose to run.
Can Paperclip stop agents from overspending?
You can set budgets with warning thresholds and hard stops at the company, agent, or project level. Enforcement is based on reported usage though, so in-progress work can delay a stop, meaning a budget limit isn’t a strict guarantee against overshoot.
Do action controls in Paperclip restrict everything an agent can do?
No. Action controls (allowed, ask first, off) apply to calls going through Paperclip’s tool gateway for supported service connections. They don’t automatically govern every shell command a coding agent can run, so runtime permissions and credentials still need to be checked separately.
Is Paperclip only useful for large multi-agent “companies”?
Not necessarily, but it’s built around that structure. For simple, short tasks handled by a single agent, the organization and hierarchy setup is likely more overhead than it’s worth. It becomes more useful once you have multiple agents handling related work and need a shared record of tasks, reviews, and costs.