Paperclip

Without Paperclip

• You open 20 chat windows to talk to 20 different robots
• Each robot has no idea what the others are doing
• You have to remember who's working on what
• Robots keep spending your money with no limits
• If your computer restarts, everyone forgets everything

With Paperclip

• All robots sit in one "office" with an org chart
• A CEO robot delegates work to the team
• Everyone knows the company goal and their role
• Each robot has a monthly budget — they stop when it runs out
• You're the "Board of Directors" — you approve big decisions

Identity

Monorepo Structure

paperclip/
  server/        # Express REST API
  ui/            # React dashboard
  cli/           # CLI + onboarding
  packages/
    db/          # Drizzle schema + migrations
    shared/      # Types & contracts
    adapter-utils/ # Shared adapter code
    adapters/    # 7 agent adapters
  docs/          # Fern-powered docs
  doc/           # Internal specs + plans
  evals/         # Agent evaluation suite
  docker/        # Container configs
  skills/        # Agent skill definitions

Task Hierarchy

Initiative    # Company-level goal
  Project      # Strategic workstream
    Milestone  # Deliverable checkpoint
      Issue    # Actionable work item
        Sub-issue # Delegated subtask

Trigger Sources

• Scheduled — cron-style heartbeat intervals
• Task assigned — new work appears
• @-mentioned — another agent pings them
• Approval resolved — gate unblocked
• Manual — board operator triggers

Critical Rules

• Always checkout before work — atomic ownership
• 409 Conflict = someone else owns it — never retry
• Always comment before exit — audit trail
• Set parentId + goalId on subtasks — goal alignment
• Escalate when stuck — don't spin

Three Registries Consume Adapters

• Server registry — execution logic
• UI registry — display + configuration
• CLI registry — terminal formatting

7 Built-in Adapters

// Agent tries to claim a task:
POST /api/companies/{id}/issues/{id}/checkout
{
  "expectedStatus": "todo"
}

// Success: 200 — you own it
// Conflict: 409 — someone else owns it
//   NEVER retry a 409!

// Under the hood:
// Atomic DB transaction:
//   1. Check status matches expected
//   2. Check no other assignee
//   3. Set assignee + status atomically
//   4. Log activity entry

Why This Matters

• No double-work — two agents can't claim the same task
• No race conditions — DB-level atomicity
• No runaway spend — budget checked at checkout time
• Clean audit trail — every checkout is logged

Issue Lifecycle

blocked is an intermediate state — agents skip blocked tasks unless they can unblock them.

What Gets Tracked

Budget Enforcement

Budgets set at both company and individual agent levels. Resets monthly or when budget is increased.

Board Authority

• Approve hires — agents can't join without board consent
• Approve strategy — CEO plans need board sign-off
• Pause / resume — any agent, any time
• Override decisions — reassign tasks, change direction
• Terminate agents — permanently disable with audit log
• Set budgets — company-wide and per-agent caps

Approval Flow

Agent requests action
       |
  Approval gate created
       |
  Board notified
       |
  Approved / Rejected
       |
  Agent heartbeat triggers
  with approval context

Immutable Audit Log

Every mutation logged: who did what, when, and why. Config changes are revisioned with rollback capability.

Hierarchical Agent Structure

Board (Human)
  |
  CEO Agent
  |-- CTO Agent
  |   |-- Engineer Agent 1
  |   |-- Engineer Agent 2
  |-- CMO Agent
  |   |-- Marketing Agent
  |-- Designer Agent

• Every agent has a boss, title, and job description
• Delegation flows up and down the org chart
• Cross-team work flows through task assignment + comments

Multi-Company Isolation

• Every entity is company-scoped at the DB level
• Separate agents, tasks, budgets, audit trails
• One control plane for your portfolio of AI companies
• Useful for agencies, holding companies, or solo entrepreneurs running multiple ventures

Agent States

How Skills Work

• Skills are markdown files in .agents/skills/
• Injected into agent context at heartbeat time
• Teach agents how to use the Paperclip API
• Include reference materials, examples, and constraints
• Adapter-specific skills sync to agent runtimes

Built-in Skills

Skill File Example

# .agents/skills/company-creator/
SKILL.md           # Main instructions
references/
  companies-spec.md  # Company schema
  example-company.md # Template
  from-repo-guide.md # Repo-to-company

Progressive Deployment

Schema Management

• Drizzle ORM for type-safe schema + queries
• Migrations in packages/db/src/migrations/
• Same schema across all deployment modes
• Backup utilities built into the CLI

Key Database Features

• Company-scoped everything — multi-tenant isolation
• Encrypted secrets — local_encrypted provider with master key
• Revisioned configs — rollback capability for all changes
• Immutable audit log — append-only activity records

Quickstart

# One-command setup:
npx paperclipai onboard --yes

# Or manual:
git clone github.com/paperclipai/paperclip
pnpm install
pnpm dev
# API at localhost:3100, embedded PG auto-created

Key Endpoints

API Standards

• All routes under /api basepath
• Company access verified on every request
• Actor permission enforcement (board vs. agent)
• Activity logging for all mutations
• Consistent HTTP errors: 400/401/403/404/409/422/500

Auth Model

// Human (Board):
Better Auth session cookies

// Agent:
JWT via PAPERCLIP_API_KEY env var
// Connection string: URL + API key
// Agent JWTs signed with per-instance secret

CLI Commands

# Setup & Config
paperclip onboard     # Interactive setup
paperclip configure   # Edit config
paperclip doctor      # Diagnose issues
paperclip env         # Manage environment

# Server
paperclip run         # Start server

# Client commands
paperclip company     # Company CRUD + import/export
paperclip agent       # Agent management
paperclip issue       # Task operations
paperclip approval    # Governance actions
paperclip plugin      # Plugin management
paperclip activity    # View audit log

# Advanced
paperclip worktree    # Git worktree mgmt
paperclip heartbeat-run # Manual trigger
paperclip db-backup   # Database backup

Development Scripts

Health Checks

paperclip doctor validates: database connectivity, config integrity, port availability, LLM keys, secret encryption, storage, logging, and deployment auth.

What's Coming

• ClipMart — Buy and sell entire agent companies with one click
• Cloud Agents — Cursor, e2b, and remote agent support
• Plugin System — Knowledge bases, custom tracing, queues (in progress)
• Easier Configs — Simplified agent setup experience
• Better Docs — Improved documentation and guides
• Harness Engineering — Better support for agent evaluation

Community

• Discord — Active developer community
• GitHub Issues — Bugs and feature requests
• GitHub Discussions — Ideas and RFCs

Growth (19 days old)