Paperclip: Run a Company of AI Agents — Setup & Complete Guide

April 7, 2026 · 10 min read

Senior Software Engineer at OCB

Paperclip is an open-source framework that lets you run a team of AI agents like a business — with an org chart, goals, budgets, governance, and a full audit trail. Here's what it is, how it works, and how to set it up.

You have 20 Claude Code tabs open. One is working on the API, one is fixing a bug, another is writing tests. You can't track which one is doing what. You restart your machine and lose all the context. Sound familiar?

This is the problem Paperclip was built to solve. Instead of managing a chaotic pile of agent sessions, Paperclip gives you a company operating system for AI agents — an org chart, a goal hierarchy, a ticket system, cost budgets, and a full audit trail. Every agent has a boss, a title, and a job description.

It launched in March 2026, hit 44,000+ GitHub stars within days, and quickly became one of the most-discussed AI tools in the developer community.

📖 GitHub (paperclipai/paperclip) • Official Docs • paperclip.ing

What Problem Does Paperclip Solve?

Before Paperclip, running multiple AI agents looked like this:

Pain Point	Reality
State loss	Restart your machine → lose all agent context
No coordination	Agents work in isolation, no shared task queue
Runaway costs	A loop goes wrong → $200 API bill before you notice
No visibility	You don't know what any agent is doing or why
Manual scheduling	You have to remember to kick off recurring jobs

Paperclip replaces this mess with a structured, managed operating environment:

"Claude Code is an employee. Paperclip is the company." — @resolvervicky on X

It doesn't tell you how to build agents — it tells you how to run a company made of them.

Core Concepts

The Org Chart Model

Instead of thinking about "prompts" and "sessions," Paperclip asks you to think like a founder:

Board of Directors (YOU)
└── CEO Agent
    ├── CTO Agent
    │   ├── Backend Engineer Agent
    │   └── QA Engineer Agent
    ├── Marketing Agent
    │   ├── Content Writer Agent
    │   └── SEO Agent
    └── Designer Agent

Each agent has:

A title (Engineer, Marketer, Designer)
A boss (who delegates tasks to them)
A job description (system prompt defining their role)
A runtime (Claude Code, OpenClaw, a Python script, an HTTP webhook — anything)
A monthly budget (hard token limit)

The Heartbeat Protocol

Agents don't run continuously (which would be expensive). Instead, they operate on a heartbeat schedule:

Every N minutes:
  Agent wakes up
    → Checks task queue
    → If task assigned → work on it
    → If no task → delegate or go dormant
  Agent goes to sleep

This saves significant API costs versus keeping agents always-on, and makes the system predictable.

Goal-Aware Execution

Every task carries a full goal ancestry — from the individual ticket up through the project, department, and company mission. This means an agent writing a blog post knows it's doing so to "grow organic traffic" as part of the goal to "reach $1M ARR."

Company Goal: "Build the #1 AI note-taking app to $1M MRR"
  └── Department Goal: "Drive 50k monthly organic visits"
       └── Project: "Publish 10 technical tutorials per month"
            └── Task: "Write a tutorial on fuzzing in Go"
                 └── Agent: Content Writer Agent

Full Audit Trail

Every conversation is a ticket. Every tool call, API request, and decision is logged in an immutable, append-only audit log. Nothing happens in the dark.

Setup: From Zero to Running Agent Company

Prerequisites

Node.js 18 or 20+
Git
An Anthropic API key (or key for your preferred LLM provider)

Step 1: Clone and Install

git clone https://github.com/paperclipai/paperclip.git
cd paperclip
npm install

Step 2: Run Interactive Setup

npx paperclipai onboard --yes

This launches an interactive wizard that:

Sets up a local embedded PostgreSQL database (no external DB needed for local use)
Walks you through authentication configuration
Creates your first company
Generates the initial config files

Alternatively, for the simplest possible start:

npm run setup

Step 3: Project Structure After Setup

paperclip/
├── paperclip.config.json     ← Main config (database, auth, API keys)
├── .env                      ← API keys and secrets
├── agents/                   ← Agent definitions
│   ├── ceo.json
│   ├── cto.json
│   └── engineer.json
├── tasks/                    ← Shared task queue
├── SKILLS.md                 ← How agents discover context
└── companies/                ← Multi-company data isolation

Step 4: Configure Your API Keys

Edit .env:

# Required: your primary LLM provider
ANTHROPIC_API_KEY=sk-ant-...

# Optional: if using OpenAI models for some agents
OPENAI_API_KEY=sk-...

# Optional: if deploying to cloud
DATABASE_URL=postgresql://user:pass@host:5432/paperclip

Step 5: Define Your Company Goal

Start the dashboard and create your first company:

npm run start
# Dashboard available at http://localhost:3000

In the UI, set your company mission — for example:

"Build and grow a technical blog to 10,000 monthly readers."

Step 6: Configure Your First Agents

Agent configuration files live in /agents/. Here's an example engineer agent:

{
  "id": "backend-engineer",
  "title": "Backend Engineer",
  "reportsTo": "cto",
  "runtime": "claude-code",
  "systemPrompt": "You are a senior backend engineer specializing in Go and Java. You write clean, production-ready code with proper error handling and tests. You work on tasks assigned by the CTO.",
  "heartbeatInterval": 30,
  "monthlyBudget": {
    "tokens": 500000,
    "usd": 20
  },
  "skills": ["./SKILLS.md"],
  "workspace": "./workspace/backend"
}

A content writer agent might look like:

{
  "id": "content-writer",
  "title": "Content Writer",
  "reportsTo": "marketing",
  "runtime": "claude-code",
  "systemPrompt": "You are a technical content writer. You write SEO-optimized blog posts and tutorials for developers. Each post must have a clear intro, real code examples, and practical takeaways.",
  "heartbeatInterval": 60,
  "monthlyBudget": {
    "tokens": 300000,
    "usd": 15
  }
}

Step 7: Define the CEO Agent

The CEO is the most critical agent — it receives the company goal directly and delegates to the rest of the org:

{
  "id": "ceo",
  "title": "CEO",
  "reportsTo": "board",
  "runtime": "claude-code",
  "systemPrompt": "You are the CEO of a company with a clear mission. Your job is to break down the company goal into a quarterly strategy, then delegate specific projects and tasks to your team leads (CTO, Marketing). You review their work and make strategic decisions. You escalate blockers to the board.",
  "heartbeatInterval": 120,
  "monthlyBudget": {
    "tokens": 200000,
    "usd": 10
  }
}

Step 8: Start the Company

npm run start

Then in the dashboard:

Review the CEO's strategy — they'll break your goal into a plan
Approve agent hires — agents can't be added without board approval
Set budgets — assign monthly token limits per agent
Hit Start — heartbeats begin, agents start working their queues

The SKILLS.md Pattern

One of Paperclip's most powerful features is runtime skill injection via SKILLS.md. This is a file that agents discover at runtime to understand project-specific context.

You may recognize this — it's the same pattern we use in this very blog under .agents/skills/! Paperclip formalized this into a standard:

# SKILLS.md

## How to find your tasks
- Check the /tasks directory for your queue
- Tasks are JSON files with a `status: "assigned"` field

## How to submit work
- Write your output to the workspace directory
- Update the task status to "completed"
- Include a summary in task.notes

## Project context
- We are building: a technical blog for backend engineers
- Audience: developers aged 25-35, Java/Go background
- Publishing cadence: 3 posts/week
- Style guide: see ./style-guide.md

Agents read this file at the start of each heartbeat to orient themselves — without any hardcoded context in their system prompts.

Use Cases

1. Autonomous Software Project

CEO: Plan the project roadmap
 └── CTO: Break into engineering tasks
     ├── Backend Engineer: Implement API endpoints
     ├── Frontend Engineer: Build the UI
     └── QA Engineer: Write and run tests

2. Content & Marketing Machine

CEO: Set content strategy
└── Marketing Director: Manage content calendar
    ├── Content Writer: Write blog posts and tutorials
    ├── SEO Agent: Optimize titles, meta, internal linking
    └── Social Media Agent: Draft and schedule posts

3. E-commerce Operations

CEO: Monitor KPIs and growth
├── Product Agent: Manage listings and inventory
├── Customer Support Agent: Handle support tickets
└── Ads Agent: Manage ad campaigns and budgets

Paperclip ships with importable company templates for all of these — you can import a pre-built org structure and be running in minutes.

How Paperclip Compares

Feature	Paperclip	LangGraph	AutoGen	Raw Claude Code
Org structure	✅ Full hierarchy	❌ Graph nodes	Partial	❌ None
Cost budgets	✅ Per-agent limits	❌	❌	❌
Audit trail	✅ Immutable log	Partial	Partial	❌
Governance	✅ Human-in-the-loop	❌	Partial	❌
Multi-company	✅ Isolated	❌	❌	❌
Agent-agnostic	✅ BYOA	❌ Python-specific	Partial	❌
State persistence	✅ Across reboots	Framework-dependent	❌	❌
Self-hosted	✅ MIT license	Depends on LangSmith	✅	✅

Key differentiator: Most agent frameworks focus on how to build agents. Paperclip focuses on how to run a company made of agents.

Best Practices

1. Start with a small org — Run CEO + 2 specialists before expanding. Understand how heartbeats and delegation work before adding more agents.

2. Set conservative budgets initially — Start with $5–10/month per agent. You can always increase. This prevents a misconfigured agent from burning your entire API quota.

3. Write tight job descriptions — The more specific the system prompt, the better the output. "Write code" is bad. "Write production-ready Go API handlers with proper error handling, input validation, and unit tests" is good.

4. Use SKILLS.md for project context — Don't put project details in system prompts (they change). Put them in SKILLS.md so agents pick up updates automatically.

5. Monitor the audit log regularly — The audit trail is your best debugging tool. If an agent is producing bad output, trace the decision chain to understand why.

6. Use the Board role deliberately — You are the board. Don't approve every hire blindly. You control the autonomy budget.

When to Use (and When Not To)

✅ Use Paperclip when:

You're running 5+ AI agents and losing track of what each one does
You need persisted state across restarts
You're building autonomous workflows (content, code, research)
You need cost controls and observability on agent spend
You want human governance at specific approval gates

❌ Don't use Paperclip when:

You have a single agent doing a single task
You need real-time streaming UX (Paperclip is not a chatbot)
You need millisecond-level response times (heartbeats add latency)
You're still experimenting with prompts (add structure after you find what works)

Key Takeaways

Paperclip is an operating system for AI agents — not an agent framework, not a prompt manager, not a chatbot. It manages the organization agents work in.
The org chart model changes how you think — moving from "I'm prompting an AI" to "I'm managing a team" makes multi-agent systems dramatically more intuitive.
Heartbeats + budgets = cost control — agents only run when scheduled, and automatically stop when they hit their monthly token limit. No surprise bills.
The audit trail is critical for debugging — every decision is logged and traceable. This is what makes autonomous systems trustworthy.
BYOA (Bring Your Own Agent) — Claude Code, OpenClaw, Python scripts, HTTP webhooks — any agent runtime works. Paperclip manages the coordination layer.
Start small — Set up a CEO + 2 specialists before building out a full org. Understand the delegation and heartbeat model first.

Thanks for reading! If you want to go deeper on how to engineer the systems around AI agents, check out my Prompt Engineering, Context Engineering & Harness Engineering guide. And if you want to run a fast local model as one of your Paperclip agents, the Gemma 4 local setup guide is a great pairing. 🚀

What Problem Does Paperclip Solve?​

Core Concepts​

The Org Chart Model​

The Heartbeat Protocol​

Goal-Aware Execution​

Full Audit Trail​

Setup: From Zero to Running Agent Company​

Prerequisites​

Step 1: Clone and Install​

Step 2: Run Interactive Setup​

Step 3: Project Structure After Setup​

Step 4: Configure Your API Keys​

Step 5: Define Your Company Goal​

Step 6: Configure Your First Agents​

Step 7: Define the CEO Agent​

Step 8: Start the Company​

The SKILLS.md Pattern​

Use Cases​

1. Autonomous Software Project​

2. Content & Marketing Machine​

3. E-commerce Operations​

How Paperclip Compares​

Best Practices​

When to Use (and When Not To)​

Key Takeaways​