Paperclip Ai Orchestration

# Paperclip AI Orchestration

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

Paperclip is an open-source Node.js + React platform that runs a **company made of AI agents**. It provides org charts, goal alignment, ticket-based task management, budget enforcement, heartbeat scheduling, governance, and a full audit log — so you manage business outcomes instead of individual agent sessions.

---

## Installation

### Quickstart (recommended)

```bash
npx paperclipai onboard --yes
```

This clones the repo, installs dependencies, seeds an embedded PostgreSQL database, and starts the server.

### Manual setup

```bash
git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev
```

**Requirements:**
- Node.js 20+
- pnpm 9.15+

The API server starts at `http://localhost:3100`. An embedded PostgreSQL database is created automatically — no manual DB setup needed for local development.

### Production setup

Point Paperclip at an external Postgres instance and object storage via environment variables:

```bash
# .env
DATABASE_URL=postgresql://user:password@host:5432/paperclip
STORAGE_BUCKET=your-s3-bucket
STORAGE_REGION=us-east-1
AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY
PORT=3100
```

---

## Key CLI Commands

```bash
pnpm dev              # Start API + UI in development mode
pnpm build            # Build for production
pnpm start            # Start production server
pnpm db:migrate       # Run pending database migrations
pnpm db:seed          # Seed demo data
pnpm test             # Run test suite
npx paperclipai onboard --yes   # Full automated onboarding
```

---

## Core Concepts

| Concept | Description |
|---|---|
| **Company** | Top-level namespace. All agents, goals, tasks, and budgets are scoped to a company. |
| **Agent** | An AI worker (OpenClaw, Claude Code, Codex, Cursor, HTTP bot, Bash script). |
| **Goal** | Hierarchical business objective. Tasks inherit goal ancestry so agents know the "why". |
| **Task / Ticket** | A unit of work assigned to an agent. Conversations and tool calls are threaded to it. |
| **Heartbeat** | A cron-style schedule that wakes an agent to check for work or perform recurring tasks. |
| **Org Chart** | Hierarchical reporting structure. Agents have managers, direct reports, roles, and titles. |
| **Budget** | Monthly token/cost cap per agent. Atomic enforcement — agent stops when budget exhausted. |
| **Governance** | Approval gates for hires, strategy changes, and config rollbacks. You are the board. |

---

## REST API

The Paperclip API is served at `http://localhost:3100/api/v1`.

### Authentication

```typescript
// All requests require a bearer token
const headers = {
  'Authorization': `Bearer ${process.env.PAPERCLIP_API_KEY}`,
  'Content-Type': 'application/json',
};
```

### Create a Company

```typescript
const response = await fetch('http://localhost:3100/api/v1/companies', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'NoteGenius Inc.',
    mission: 'Build the #1 AI note-taking app to $1M MRR.',
    slug: 'notegenius',
  }),
});

const { company } = await response.json();
console.log(company.id); // "cmp_abc123"
```

### Register an Agent

```typescript
const agent = await fetch(`http://localhost:3100/api/v1/companies/${companyId}/agents`, {
  method: 'POST',
  headers,
  body: JSON.stringify({