DEV Community

Cover image for Paperclip: The Free Tool That Turns AI Agents Into a Software Team
Wanda
Wanda

Posted on • Originally published at apidog.com

Paperclip: The Free Tool That Turns AI Agents Into a Software Team

Most developers running multiple AI agents hit a wall around agent number five. You’ve got Claude Code in one terminal rewriting a backend service, Codex in another generating tests, Cursor editing a component, and three more tabs you forgot to check. Nobody knows what anyone else is doing. Costs spiral. Two agents duplicate the same work. One runs for six hours and produces nothing useful because nobody gave it a clear objective.

Try Apidog today

Paperclip fixes this. It’s an open-source orchestration platform that turns your scattered AI agents into a structured company, complete with org charts, assigned roles, task management, budget limits, and audit logs. It hit 35,000+ GitHub stars in under three weeks, showing just how many developers have felt this pain.

This article walks you through setting up Paperclip, structuring your first agent company, and running it so work actually gets done without you watching every terminal.

What Paperclip is (and what it isn’t)

Before installing, know what Paperclip provides.

Paperclip is an orchestration layer: it coordinates agents, tracks their work, controls their budgets, and gives them context about company goals. It does not build agents, replace your AI provider, or add a chat UI.

Paperclip Org Structure

Think of it as: if Claude Code is an employee, Paperclip is the company.

That means:

  • Agents have roles, not just prompts
  • Tasks have owners, not just open terminals
  • Budgets have hard limits, not just vibes
  • Everything is logged in an audit trail

Paperclip works with Claude Code, OpenAI Codex, Cursor, Gemini CLI, and any agent that can receive a webhook or heartbeat signal. You bring the agents. Paperclip runs the company.

It is not:

  • A chatbot UI
  • A drag-and-drop workflow builder (like n8n or Zapier)
  • A framework for writing agents
  • Useful for single-agent tasks

If you’re running one AI agent occasionally, Paperclip is overkill. For three or more ongoing agents, it’s the missing piece.

Installing Paperclip

You need Node.js 20+, pnpm 9.15+. Paperclip ships with an embedded PostgreSQL database—no external DB setup needed.

Fastest way to get started:

npx paperclipai onboard --yes
Enter fullscreen mode Exit fullscreen mode

This downloads the CLI, runs onboarding with sensible defaults, and starts the server on port 3100. Open http://127.0.0.1:3100 to access the dashboard.

To contribute or inspect the code:

git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev
Enter fullscreen mode Exit fullscreen mode

Docker users:

docker compose -f docker-compose.quickstart.yml up --build
Enter fullscreen mode Exit fullscreen mode

Files created on disk:

Paperclip stores everything under ~/.paperclip/instances/default/:

~/.paperclip/instances/default/
  config.json          — server and storage settings
  db/                  — embedded PostgreSQL data files
  secrets/master.key   — encryption key (auto-generated)
  logs/                — server logs
  data/storage/        — file attachments
  workspaces/<agent>/  — per-agent working directories
Enter fullscreen mode Exit fullscreen mode

Local mode uses local_trusted auth by default, skipping login and using a synthetic “Board” user. Start using the dashboard immediately—no account needed.

Run a health check once you’re in:

paperclipai doctor
Enter fullscreen mode Exit fullscreen mode

If anything is misconfigured, fix it automatically:

paperclipai doctor --repair
Enter fullscreen mode Exit fullscreen mode

Setting up your first company

In Paperclip, a “company” is the top-level container for your agents, tasks, goals, and budgets. Think of it as a project, but every member is an AI agent with a role and reporting line.

From the dashboard, create a new company and set a mission statement. This context is used for every agent task, informing why tasks matter, not just what to do.

Example mission:

Build and maintain a REST API for customer order management. Prioritize correctness over speed. Document every public endpoint.

This statement gives your agents a decision-making filter.

Adding your first agents

Each agent in Paperclip uses an adapter that defines which AI tool it uses and how it communicates.

Supported adapters out of the box:

Agent Adapter type Package
Claude Code claude_local @paperclipai/adapter-claude-local
OpenAI Codex codex_local @paperclipai/adapter-codex-local
Gemini CLI gemini_local @paperclipai/adapter-gemini-local
Cursor cursor @paperclipai/adapter-cursor-local
HTTP webhooks HTTP adapter custom endpoint

Add a Claude Code agent via CLI:

paperclipai agent local-cli "Backend Engineer" --company-id <your-company-id>
Enter fullscreen mode Exit fullscreen mode

This bootstraps the agent, installs its skills in ~/.claude/skills, and generates API credentials. The agent now appears in your company org chart and can receive tasks.

Claude agent configuration options:

Field What it does
model Claude model to use (e.g., claude-sonnet-4-6)
cwd Working directory (auto-created if missing)
promptTemplate System prompt with {{variable}} substitution
maxTurnsPerRun Max agentic turns per heartbeat (default: 300)
timeoutSec Hard execution limit (0 = no timeout)

Model allocation by role:

  • CEO / orchestration: Sonnet (strategic reasoning)
  • Manager agents: Haiku (routing, delegation)
  • Creative / coding ICs: Sonnet (output quality)
  • Formulaic ICs: Haiku (boilerplate, scaffolding, migrations)

This approach can cut monthly agent spend by 40-60% compared to using Sonnet everywhere, without meaningful loss on routine tasks.

Structuring your agent org

Example structure for a small software project:

CEO (Sonnet)
 ├── CTO (Haiku)
 │    ├── Backend Engineer (Sonnet)
 │    ├── Frontend Engineer (Sonnet)
 │    └── QA Engineer (Haiku)
 └── Technical Writer (Haiku)
Enter fullscreen mode Exit fullscreen mode
  • The CEO agent holds the mission and breaks it into goals.
  • The CTO routes goals to engineers.
  • Engineers do the work.
  • QA validates.
  • The writer documents.

Each agent has a heartbeat interval—how often it wakes, checks tasks, works, and exits. Agents don’t run continuously. They wake, execute, and sleep. This controls costs.

Recommended intervals:

  • Coding agents: 600 seconds (10 min)
  • On-demand agents: 86,400 seconds (1/day) with wake-on-demand enabled
  • Minimum safe interval: 30 seconds (lower risks high cost and spam)

How the heartbeat works

Every agent wake follows this nine-step protocol:

  1. Confirm identity via GET /api/agents/me
  2. Handle pending approval callbacks
  3. Fetch assigned tasks from GET /api/companies/{companyId}/issues
  4. Prioritize: in-progress first, then todo; skip blocked unless unblockable
  5. Check out the task via POST /api/issues/{issueId}/checkout (409 means already taken)
  6. Read full task context and comments
  7. Do the work
  8. Update the task with comments/status
  9. Delegate subtasks with parent/goal IDs if needed

The checkout step ensures no duplicate work—only one agent owns a task at a time.

Paperclip injects context into every run via env variables:

PAPERCLIP_TASK_ID          # the triggering task
PAPERCLIP_WAKE_REASON      # why agent woke (timer, mention, assignment)
PAPERCLIP_AGENT_ID         # agent identity
PAPERCLIP_API_URL          # Paperclip API URL
Enter fullscreen mode Exit fullscreen mode

Agents use these to post updates, create subtasks, request approvals, and delegate—all within one heartbeat.

Assigning tasks and tracking work

Tasks in Paperclip behave like GitHub issues plus project management. Create via UI or CLI:

paperclipai issue create \
  --company-id <id> \
  --title "Add pagination to the orders endpoint" \
  --assignee-agent-id <backend-engineer-id>
Enter fullscreen mode Exit fullscreen mode

Tasks can have:

  • Parent tasks for breaking up work
  • Goal links to tie to company objectives
  • Comments for context, approvals, status
  • @-mentions to wake a specific agent immediately

View all open tasks via CLI:

paperclipai issue list
Enter fullscreen mode Exit fullscreen mode

Or in the dashboard, where you see owner, status, and last heartbeat.

Budget control that actually works

Paperclip gives each agent a monthly token budget. At 80%, the agent shifts to critical-only tasks. At 100%, it pauses.

Set a budget in agent config (suggested: $20-50/month per agent tier). Track burn rate, cost per heartbeat, and cumulative spend in the dashboard.

If an agent’s cost-per-heartbeat climbs, it’s a sign the prompts are too vague or the task scope is too wide—tighten the assignment, don’t just raise the budget.

Without budget controls, a misconfigured agent running on a 30-second interval can burn through hundreds of dollars before you notice. Paperclip prevents runaway costs automatically.

Runtime skills: teaching agents new workflows without retraining

Paperclip supports skill injection. When an agent runs, its adapter symlinks SKILL.md files to the agent's config directory and passes them via --add-dir. The agent reads the skill file and follows the workflow.

To teach a new process, just write a markdown file—no prompt rewriting or redeployment.

Example SKILL.md:

# SKILL: Database migrations

When creating a migration:
1. Never modify existing migration files
2. Use descriptive names: YYYYMMDD_description.sql
3. Include both up and down SQL
4. Test locally before committing
5. Add a comment explaining the business reason for the change
Enter fullscreen mode Exit fullscreen mode

Save to the skills directory, assign to your backend agent, and every future heartbeat follows that process.

If you’re testing APIs built by your agents

When your agents are building APIs, fast testing is crucial. Apidog fits naturally here. It handles API design, mock servers, and automated tests in one place—so when your backend agent ships an endpoint, you can validate it immediately, without juggling Swagger, Postman, and a mock tool.

Apidog API Testing

Auto-generate test suites from OpenAPI specs, run them against agent output, and feed the results back as a task comment. The agent picks it up on the next heartbeat and fixes failures. The full loop, from code to test to fix, runs without manual intervention.

Apidog supports REST, GraphQL, and gRPC, and it's free to start.

Managing multiple instances

Paperclip supports multiple isolated instances on one machine via the PAPERCLIP_INSTANCE_ID env var or the --instance flag. Each instance has its own config, DB, ports, and agent workspaces.

For local dev, use the worktree command to create a fully isolated dev instance per git branch:

paperclipai worktree:make feature/orders-pagination
Enter fullscreen mode Exit fullscreen mode

This gives you separate ports, config, and a DB per branch. Run test companies against feature code without touching production. Tear down when done.

Multi-agent setups that work

Effective patterns:

  • Goal cascade: Write one high-level company goal, let your CEO agent break it into project goals, and managers break those into tasks. Agents work better with context.
  • Approval gates: For sensitive actions (production, staging, billing), configure approval gates. The agent pauses and waits for manual OK before proceeding.
  • On-demand wakes via @-mention: Use slow heartbeat intervals and @-mentions in task comments to wake agents immediately when needed. Saves cost, ensures responsiveness.
  • Separate workspace per agent: Each agent has its own working directory under workspaces/<agent-id>/. Keep these clean and separate.

Getting started takes about 15 minutes

Initial onboarding takes under 15 minutes. One command installs and starts the server. Adding your first agent and creating a task takes five minutes in the dashboard.

The key is structuring your company well: write a clear mission, choose the right model for each role, and set sensible budget limits. Spend 30 minutes here before assigning work and you’ll get better results than rushing setup.

If you’re running more than two AI agents on any ongoing project, this is worth an afternoon to set up. The difference between a tab-per-agent and a structured, budgeted company with audit logs is the difference between a side project and something that can actually run unattended.

Top comments (0)