Paperclip: Run a Multi-Agent AI Company with Claude Code
The problem that shows up when you have more than one agent
Running a single AI agent on your project is powerful. Running twenty is chaos.
Who makes decisions? Who reviews the code? How do you stop two agents from picking up the same ticket simultaneously? How do you prevent runaway token costs when an agent gets stuck in a loop?
Paperclip is the answer to all of those questions. It's an open-source framework launched in March 2026 that organizes multiple Claude Code instances like employees in a company — with defined roles, budgets, approval flows, and persistent session memory.
It hit 30,000 GitHub stars in three weeks. The reason is simple: it solves the right problem.
What Paperclip actually is
Paperclip is not a Claude Code feature. It's an independent orchestration layer — open-source, self-hosted (no Paperclip account, no subscription) — that runs as a Node.js server with a React dashboard.
The central idea: model your AI team like a real company, with an org chart, mission, goals, and a monthly budget per agent.
Each "employee" in Paperclip is an agent that:
- Has a defined role (CEO, CTO, Backend Engineer, QA…)
- Runs on Claude Code as its execution runtime
- Wakes up at regular intervals (heartbeat)
- Works assigned tasks, makes commits, opens PRs, or reviews code
- Stops automatically when its monthly token budget is exhausted
What Paperclip does for you is exactly what a manager does in a human team: decides what each agent does, in what order, within what constraints — and ensures no one steps on anyone else's work.
The claude-local adapter: Claude Code integration
The piece connecting Paperclip to Claude Code is called the claude-local adapter. It tells Paperclip how to launch Claude Code sessions, maintain them between heartbeat cycles, and parse their output.
The most important aspects of this adapter:
- Session persistence: each agent keeps its
SESSION_IDbetween runs. When it wakes up, it resumes the exact same Claude Code conversation rather than starting blank. This eliminates the cost of re-contextualizing on every cycle. - Skill injection: Paperclip injects Markdown skill files into the Claude Code session. Your QA agent can learn to run Playwright without retraining — give it the Skill file and it knows what to do.
- Directory change detection: if the agent's working directory changes between runs, a fresh session starts automatically to avoid context confusion.
Minimum requirements for the adapter: the Claude CLI available (claude in PATH) and ANTHROPIC_API_KEY in the environment. The "Test Environment" button in Paperclip's dashboard validates everything before any execution.
Architecture of a typical team
A development team in Paperclip looks like this:
CEO (Sonnet 4.6) ← Strategy, backlog, assignment
└── CTO (Haiku 4.5) ← Technical decisions, PR reviews
├── Backend Eng (Sonnet 4.6) ← Claude Code: APIs, DB
├── Frontend Eng (Sonnet 4.6) ← Claude Code: React/Next.js
└── QA Eng (Haiku 4.5) ← Claude Code: Playwright, tests
The CEO never writes code. It reads the product backlog, breaks features into tickets, and assigns them to direct reports. It uses Sonnet because it needs to reason about the whole product.
The CTO delegates technical work and reviews PRs before approving them. It uses Haiku because its tasks are more mechanical: routing, review checklists, change approval.
Engineers are the ones who execute through Claude Code: create branches, write code, make consistently formatted commits (via a Skills file), open PRs.
QA picks up finished work from a shared directory, runs test cases independently, and reports bugs back to the organization.
Using Haiku for CTO and QA saves 40–60% of monthly spend compared to running Sonnet across every role.
The Skills system
One of Paperclip's most practical features is the Skills system: Markdown files that teach agents repeatable processes without retraining.
Useful skill examples for a development team:
# Skill: Commit Message Format
Always use Conventional Commits format:
- feat(scope): description
- fix(scope): description
- docs(scope): description
Maximum 72 characters on the first line.
# Skill: PR Review Checklist
Before approving a PR, verify:
1. CI tests passing
2. Clear change description
3. No exposed secrets
4. Naming conventions respected
Skills are discoverable at runtime. Add a new one and agents incorporate it on the next heartbeat cycle — no prompt changes, no redeployment.
If you've already worked with agents and subagents in Claude Code, you'll see that Paperclip takes that idea to the next level: it's not an agent that coordinates subagents on the fly, but a permanent organizational structure with real governance.
Cost control and governance
One of the most legitimate concerns about letting autonomous agents run is uncontrolled spending. Paperclip addresses this with hard budgets per agent:
- You define a monthly token limit for each role
- When the agent hits it, it stops automatically
- The dashboard shows real-time consumption per agent and per task
Additionally, Paperclip includes approval gates: actions that require human review before executing. For example, you can configure that no agent can merge to main without your approval, or that any token spend above a threshold triggers a notification.
This makes it suitable for real production environments, not just local experiments.
When does Paperclip make sense?
Paperclip is for teams, not simple personal projects. The documentation says it directly: "if you have one agent, you probably don't need Paperclip. If you have twenty — you definitely do."
It makes sense when:
- You're building a complex product that requires backend, frontend, tests, and documentation in parallel
- You want AI to work while you sleep or focus elsewhere, with clear logs of what it did
- You need cost control and per-role transparency
- Your human team already uses Claude Code and you want to scale with agents that respect the same workflow
For more targeted AI integrations on your React/Next.js stack, you can also explore how we integrate AI into real projects.
Conclusion
Paperclip is the missing piece for scaling from "one agent helping me code" to "a team of agents autonomously building software under my supervision." The combination with Claude Code as the runtime is particularly powerful because it inherits all the context, tooling, and code-editing capabilities you already know.
If you want to implement this architecture in your project or explore how it fits your workflow, reach out: