DEV Community

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

Posted on

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

Most multi-agent setups fail around agent number five: Claude Code is editing a backend service, Codex is generating tests, Cursor is changing UI code, and nobody has task ownership, budget limits, or a reliable audit trail. Paperclip fixes that by acting as an orchestration layer for AI agents: it gives them roles, tasks, reporting lines, budgets, and logs so they can work like a structured software team instead of disconnected terminal sessions.

Try Apidog today

Paperclip is open source and reached 35,000+ GitHub stars in under three weeks, which says a lot about how common this problem has become.

This guide shows how to install Paperclip, create your first agent company, assign work, control spend, and run multi-agent workflows without watching every terminal manually.

What Paperclip is

Paperclip is an orchestration layer for AI agents.

It does not replace Claude, Codex, Cursor, Gemini, or your own agent tooling. Instead, it coordinates them.

Image

The mental model is:

If Claude Code is an employee, Paperclip is the company.

That means Paperclip gives you:

  • Agent roles instead of loose prompts
  • Assigned tasks instead of open-ended terminal sessions
  • Budget limits instead of unchecked token usage
  • Audit logs instead of guessing what happened
  • Heartbeats instead of always-on agent processes

Paperclip works with:

Agent/tool Adapter
Claude Code claude_local
OpenAI Codex codex_local
Gemini CLI gemini_local
Cursor cursor
Custom agents HTTP webhook adapter

Paperclip is not:

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

If you run one agent manually, Paperclip is probably overkill. If you run three or more agents on ongoing work, it gives you the missing coordination layer.

Install Paperclip

Requirements:

  • Node.js 20+
  • pnpm 9.15+

Paperclip includes an embedded PostgreSQL database, so you do not need to configure external storage for a local setup.

Start with:

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

This installs the CLI, runs onboarding with defaults, and starts the server on port 3100.

Open:

http://127.0.0.1:3100
Enter fullscreen mode Exit fullscreen mode

To work from source:

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

To use Docker:

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

Paperclip stores local instance data under:

~/.paperclip/instances/default/
  config.json          # server and storage settings
  db/                  # embedded PostgreSQL data files
  secrets/master.key   # encryption key
  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, so you can use the dashboard immediately without creating an account.

Run a health check:

paperclipai doctor
Enter fullscreen mode Exit fullscreen mode

If something is misconfigured, try:

paperclipai doctor --repair
Enter fullscreen mode Exit fullscreen mode

Create your first company

In Paperclip, a company is the top-level container for:

  • Agents
  • Tasks
  • Goals
  • Budgets
  • Reporting structure

Create a company from the dashboard and give it a clear mission statement.

This matters because agents use the mission as context when deciding how to execute tasks.

Example mission:

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

A good mission helps agents make consistent decisions during longer runs.

Add agents

Each Paperclip agent uses an adapter that defines how it communicates with the underlying AI tool.

Supported adapters include:

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

Create a Claude Code agent:

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.

Common Claude agent configuration fields:

Field Purpose
model Claude model to use, for example claude-sonnet-4-6
cwd Working directory for the agent
promptTemplate System prompt with {{variable}} substitution
maxTurnsPerRun Maximum agentic turns per heartbeat
timeoutSec Hard execution limit, where 0 means no timeout

A practical model allocation pattern:

  • CEO/orchestration agents: Sonnet
  • Manager/routing agents: Haiku
  • Coding agents: Sonnet
  • Formulaic agents such as test scaffolding or migrations: Haiku

This keeps stronger models on reasoning-heavy work and cheaper models on routing or repetitive tasks.

Build a small agent org chart

A simple software project can start with this structure:

CEO (Sonnet)
 ├── CTO (Haiku)
 │    ├── Backend Engineer (Sonnet)
 │    ├── Frontend Engineer (Sonnet)
 │    └── QA Engineer (Haiku)
 └── Technical Writer (Haiku)
Enter fullscreen mode Exit fullscreen mode

Suggested responsibilities:

Role Responsibility
CEO Owns mission and breaks it into goals
CTO Routes engineering goals into tasks
Backend Engineer Implements backend work
Frontend Engineer Implements UI work
QA Engineer Validates changes
Technical Writer Documents public behavior

Each agent runs on a heartbeat interval. It wakes up, checks assigned work, performs a bounded run, reports progress, and exits.

Recommended intervals:

Agent type Interval
Coding agents 600 seconds
On-demand agents 86400 seconds with wake-on-demand
Minimum safe interval 30 seconds

Avoid very low heartbeat intervals unless you are actively testing. Fast polling can increase token spend quickly.

Understand the heartbeat flow

Every time an agent wakes, it follows a standard protocol:

  1. Confirm identity with GET /api/agents/me
  2. Handle pending approval callbacks
  3. Fetch assigned tasks from GET /api/companies/{companyId}/issues
  4. Prioritize in-progress tasks, then todo tasks
  5. Skip blocked tasks unless they can be unblocked
  6. Check out a task with POST /api/issues/{issueId}/checkout
  7. Read task context and comments
  8. Do the work
  9. Update status, add comments, or delegate subtasks

The checkout step prevents duplicate work. If another agent already owns the task, Paperclip returns 409, and the current agent moves on.

Paperclip also injects context into each run:

PAPERCLIP_TASK_ID       # task that triggered the run
PAPERCLIP_WAKE_REASON   # timer, mention, assignment, etc.
PAPERCLIP_AGENT_ID      # current agent identity
PAPERCLIP_API_URL       # Paperclip API URL
Enter fullscreen mode Exit fullscreen mode

Agents can use this context to update tasks, create subtasks, request approvals, or delegate work during the heartbeat.

Create and assign tasks

Tasks behave like GitHub issues plus project-management metadata.

Create a task from the 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 include:

  • Parent tasks
  • Goal links
  • Comments
  • Approval requests
  • Status changes
  • @ mentions to wake agents on demand

List open tasks:

paperclipai issue list
Enter fullscreen mode Exit fullscreen mode

You can also track tasks in the dashboard, including owner, status, and the last heartbeat that touched each task.

Add budget controls

Paperclip lets you assign a monthly token budget per agent.

Budget behavior:

Budget usage Behavior
Under 80% Normal operation
80%+ Agent shifts to critical-only tasks
100% Agent pauses

A common starting point is $20–50/month per agent tier.

Track these in the dashboard:

  • Burn rate per agent
  • Cost per heartbeat
  • Monthly cumulative spend
  • Agents with unusually expensive runs

If cost per heartbeat rises, the usual fix is not raising the budget. First, tighten the task scope or improve the agent prompt. Vague tasks cause long, expensive runs.

Budget controls are especially important for agents with short heartbeat intervals or expensive reasoning modes enabled.

Add runtime skills

Paperclip supports skill injection.

When an agent runs, the adapter creates symlinks to SKILL.md files in the agent config directory and passes them through --add-dir. The agent reads the skill file as part of its context.

Use this to teach workflows without retraining or redeploying agents.

Example skill:

# 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

Good skill files are useful for:

  • Commit message conventions
  • Database migration rules
  • API documentation format
  • Testing requirements
  • Release checklist steps

Assign the skill to the relevant agent, and future heartbeats follow that workflow.

Test APIs built by agents

If your agents build APIs, you need fast feedback on whether the generated endpoints work.

Apidog fits this workflow because it combines API design, mock servers, and automated tests in one place. When a backend agent ships an endpoint, you can validate it without switching between Swagger, Postman, and a separate mock tool.

Image

A practical loop:

  1. Backend agent implements an endpoint
  2. Generate or update the OpenAPI spec
  3. Run API tests from the spec
  4. Post failures back to the Paperclip task as a comment
  5. Wake the backend agent with an @ mention
  6. Agent fixes the failures on the next heartbeat

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

Run multiple isolated instances

Paperclip supports multiple local instances with:

  • PAPERCLIP_INSTANCE_ID
  • --instance

Each instance has isolated:

  • Config
  • Database
  • Ports
  • Workspaces

For branch-based development, use:

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

This creates an isolated development instance for that Git branch. You can test a company and agents against feature code without touching your main setup.

Patterns that work well

Goal cascade

Start with a company-level goal. Let the CEO agent break it into project goals. Let manager agents break those into implementation tasks.

Agents perform better when they understand the purpose chain instead of receiving isolated instructions.

Approval gates

Use approval gates for actions that touch:

  • Production
  • Staging
  • Billing
  • External services
  • Destructive operations

The agent pauses, requests approval, and continues only after you confirm.

On-demand wakes

Instead of using very fast heartbeat intervals, keep agents on slower intervals and wake them with @ mentions when needed.

This gives you fast response times without paying for constant polling.

Separate workspaces

Each agent gets its own workspace under:

workspaces/<agent-id>/
Enter fullscreen mode Exit fullscreen mode

Keep workspaces isolated. Shared workspaces cause agents to overwrite or conflict with each other’s work.

A 15-minute setup checklist

Use this sequence for your first Paperclip setup:

  1. Install and start Paperclip 
npx paperclipai onboard --yes
Enter fullscreen mode Exit fullscreen mode
  1. Open the dashboard 
http://127.0.0.1:3100
Enter fullscreen mode Exit fullscreen mode
  1. Run diagnostics 
paperclipai doctor
Enter fullscreen mode Exit fullscreen mode
  1. Create a company with a clear mission 
Build and maintain a REST API for customer order management.
Prioritize correctness over speed.
Document every public endpoint.
Enter fullscreen mode Exit fullscreen mode
  1. Add your first agent 
paperclipai agent local-cli "Backend Engineer" --company-id <your-company-id>
Enter fullscreen mode Exit fullscreen mode
  1. Create a task 
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

  1. Set a monthly budget for the agent

  2. Configure heartbeat interval

  3. Watch the first run in the dashboard

Final thoughts

Paperclip is most useful when you already have multiple agents doing ongoing work. It gives you structure: task ownership, heartbeat execution, budget limits, and audit logs.

The setup is quick. The important part is designing the company well:

  • Write a specific mission
  • Assign clear roles
  • Use the right model for each role
  • Set budget limits early
  • Keep workspaces isolated
  • Use approval gates for risky actions

That structure is what turns a pile of AI agent terminal tabs into a system that can actually run work without constant supervision.

Top comments (0)