PaperclipOrg
Claude Agent Skill · by Aradotso

Paperclip Ai Orchestration

Install Paperclip Ai Orchestration skill for Claude Code from aradotso/trending-skills.

Install
Terminal · npx
$npx skills add https://github.com/vercel-labs/agent-skills --skill vercel-react-best-practices
Works with Paperclip

How Paperclip Ai Orchestration fits into a Paperclip company.

Paperclip Ai Orchestration drops into any Paperclip agent that handles this kind of work. Assign it to a specialist inside a pre-configured PaperclipOrg company and the skill becomes available on every heartbeat — no prompt engineering, no tool wiring.

S
SaaS FactoryPaired

Pre-configured AI company — 18 agents, 18 skills, one-time purchase.

$27$59
Explore pack
Source file
SKILL.md530 lines
Expand
---name: paperclip-ai-orchestrationdescription: Skill for using Paperclip — open-source orchestration platform for running autonomous AI-agent companies with org charts, budgets, governance, and heartbeats.triggers:  - set up paperclip for my ai company  - orchestrate multiple ai agents with paperclip  - configure agents and goals in paperclip  - add a new agent to my paperclip company  - monitor ai agent costs and budgets in paperclip  - create a company with paperclip orchestration  - heartbeat scheduling for ai agents  - manage multi-agent workflows with paperclip--- # 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) ```bashnpx paperclipai onboard --yes``` This clones the repo, installs dependencies, seeds an embedded PostgreSQL database, and starts the server. ### Manual setup ```bashgit clone https://github.com/paperclipai/paperclip.gitcd paperclippnpm installpnpm 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# .envDATABASE_URL=postgresql://user:password@host:5432/paperclipSTORAGE_BUCKET=your-s3-bucketSTORAGE_REGION=us-east-1AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_IDAWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEYPORT=3100``` --- ## Key CLI Commands ```bashpnpm dev              # Start API + UI in development modepnpm build            # Build for productionpnpm start            # Start production serverpnpm db:migrate       # Run pending database migrationspnpm db:seed          # Seed demo datapnpm test             # Run test suitenpx 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 tokenconst headers = {  'Authorization': `Bearer ${process.env.PAPERCLIP_API_KEY}`,  'Content-Type': 'application/json',};``` ### Create a Company ```typescriptconst 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 ```typescriptconst agent = await fetch(`http://localhost:3100/api/v1/companies/${companyId}/agents`, {  method: 'POST',  headers,  body: JSON.stringify({    name: 'Alice',    role: 'CTO',    runtime: 'claude-code',       // 'openclaw' | 'claude-code' | 'codex' | 'cursor' | 'bash' | 'http'    endpoint: process.env.ALICE_AGENT_ENDPOINT,    budget: {      monthly_usd: 200,    },    heartbeat: {      cron: '0 * * * *',          // every hour      enabled: true,    },    reports_to: ceoAgentId,       // parent in org chart  }),}).then(r => r.json());``` ### Create a Goal ```typescriptconst goal = await fetch(`http://localhost:3100/api/v1/companies/${companyId}/goals`, {  method: 'POST',  headers,  body: JSON.stringify({    title: 'Launch v1 to Product Hunt',    description: 'Ship the MVP and generate 500 upvotes on launch day.',    parent_goal_id: null,         // null = top-level goal    owner_agent_id: ctoAgentId,    due_date: '2026-06-01',  }),}).then(r => r.json());``` ### Create a Task ```typescriptconst task = await fetch(`http://localhost:3100/api/v1/companies/${companyId}/tasks`, {  method: 'POST',  headers,  body: JSON.stringify({    title: 'Implement offline sync for notes',    description: 'Use CRDTs to merge note edits made offline. See ADR-004.',    assigned_to: engineerAgentId,    goal_id: goal.id,              // links task to goal ancestry    priority: 'high',  }),}).then(r => r.json()); console.log(task.id); // "tsk_xyz789"``` ### List Tasks for an Agent ```typescriptconst { tasks } = await fetch(  `http://localhost:3100/api/v1/agents/${agentId}/tasks?status=open`,  { headers }).then(r => r.json());``` ### Post a Message to a Task Thread ```typescriptawait fetch(`http://localhost:3100/api/v1/tasks/${taskId}/messages`, {  method: 'POST',  headers,  body: JSON.stringify({    role: 'agent',    content: 'Implemented CRDT merge logic. Tests passing. Ready for review.',    tool_calls: [      {        tool: 'bash',        input: 'pnpm test --filter=sync',        output: '42 tests passed in 3.1s',      },    ],  }),});``` ### Report Agent Cost Agents self-report token usage; Paperclip enforces budget atomically: ```typescriptawait fetch(`http://localhost:3100/api/v1/agents/${agentId}/cost`, {  method: 'POST',  headers,  body: JSON.stringify({    tokens_in: 12400,    tokens_out: 3800,    model: 'claude-opus-4-5',    task_id: taskId,  }),});``` ### Heartbeat Ping Agents call this endpoint on each scheduled wake-up: ```typescriptconst { instructions, tasks } = await fetch(  `http://localhost:3100/api/v1/agents/${agentId}/heartbeat`,  { method: 'POST', headers }).then(r => r.json()); // instructions — what the org says to focus on now// tasks        — open tasks assigned to this agent``` --- ## TypeScript SDK Pattern Wrap the REST API for cleaner agent integration: ```typescript// lib/paperclip-client.tsexport class PaperclipClient {  private base: string;  private headers: Record<string, string>;   constructor(    base = process.env.PAPERCLIP_BASE_URL ?? 'http://localhost:3100',    apiKey = process.env.PAPERCLIP_API_KEY ?? '',  ) {    this.base = `${base}/api/v1`;    this.headers = {      Authorization: `Bearer ${apiKey}`,      'Content-Type': 'application/json',    };  }   private async req<T>(path: string, init?: RequestInit): Promise<T> {    const res = await fetch(`${this.base}${path}`, {      ...init,      headers: { ...this.headers, ...init?.headers },    });    if (!res.ok) {      const body = await res.text();      throw new Error(`Paperclip API ${res.status}: ${body}`);    }    return res.json() as Promise<T>;  }   heartbeat(agentId: string) {    return this.req<{ instructions: string; tasks: Task[] }>(      `/agents/${agentId}/heartbeat`,      { method: 'POST' },    );  }   completeTask(taskId: string, summary: string) {    return this.req(`/tasks/${taskId}`, {      method: 'PATCH',      body: JSON.stringify({ status: 'done', completion_summary: summary }),    });  }   reportCost(agentId: string, payload: CostPayload) {    return this.req(`/agents/${agentId}/cost`, {      method: 'POST',      body: JSON.stringify(payload),    });  }}``` --- ## Building an Agent That Works With Paperclip A minimal agent loop that integrates with Paperclip: ```typescript// agent.tsimport { PaperclipClient } from './lib/paperclip-client'; const client = new PaperclipClient();const AGENT_ID = process.env.PAPERCLIP_AGENT_ID!; async function runHeartbeat() {  console.log('[agent] heartbeat ping');   const { instructions, tasks } = await client.heartbeat(AGENT_ID);   for (const task of tasks) {    console.log(`[agent] working on task: ${task.title}`);     try {      // --- your agent logic here ---      const result = await doWork(task, instructions);       await client.completeTask(task.id, result.summary);      await client.reportCost(AGENT_ID, {        tokens_in: result.tokensIn,        tokens_out: result.tokensOut,        model: result.model,        task_id: task.id,      });       console.log(`[agent] task ${task.id} done`);    } catch (err) {      console.error(`[agent] task ${task.id} failed`, err);      // Paperclip will reassign or escalate based on governance rules    }  }} // Heartbeat is usually driven by Paperclip's cron, but you can also self-poll:setInterval(runHeartbeat, 60_000);runHeartbeat();``` --- ## Registering an HTTP Agent (any language) Any process reachable over HTTP can be an agent. Paperclip sends a POST to your endpoint: ```typescript// Paperclip calls POST /work on your agent with this shape:interface PaperclipWorkPayload {  agent_id: string;  task: {    id: string;    title: string;    description: string;    goal_ancestry: string[];   // full chain: company mission → goal → sub-goal  };  instructions: string;        // current org-level directives  context: Record<string, unknown>;}``` Respond with: ```typescriptinterface PaperclipWorkResponse {  status: 'done' | 'blocked' | 'delegated';  summary: string;  tokens_in?: number;  tokens_out?: number;  model?: string;  delegate_to?: string;        // agent_id if status === 'delegated'}``` --- ## Multi-Company Setup ```typescript// Create isolated companies in one deploymentconst companies = await Promise.all([  createCompany({ name: 'NoteGenius', mission: 'Best note app' }),  createCompany({ name: 'ShipFast', mission: 'Fastest deploy tool' }),]); // Each company has its own agents, goals, tasks, budgets, and audit log// No data leaks between companies``` --- ## Governance & Approvals ```typescript// Fetch pending approval requests (you are the board)const { approvals } = await fetch(  `http://localhost:3100/api/v1/companies/${companyId}/approvals?status=pending`,  { headers }).then(r => r.json()); // Approve a hireawait fetch(`http://localhost:3100/api/v1/approvals/${approvals[0].id}`, {  method: 'PATCH',  headers,  body: JSON.stringify({ decision: 'approved', note: 'Looks good.' }),}); // Roll back a bad config changeawait fetch(`http://localhost:3100/api/v1/agents/${agentId}/config/rollback`, {  method: 'POST',  headers,  body: JSON.stringify({ revision: 3 }),});``` --- ## Environment Variables Reference ```bash# RequiredPAPERCLIP_API_KEY=                  # Your API key for the Paperclip server # Database (defaults to embedded Postgres in dev)DATABASE_URL=                        # postgresql://user:pass@host:5432/db # Storage (defaults to local filesystem in dev)STORAGE_DRIVER=local                 # 'local' | 's3'STORAGE_BUCKET=                      # S3 bucket nameSTORAGE_REGION=                      # AWS regionAWS_ACCESS_KEY_ID=                   # From your environmentAWS_SECRET_ACCESS_KEY=               # From your environment # ServerPORT=3100BASE_URL=http://localhost:3100 # Agent-side (used inside agent processes)PAPERCLIP_BASE_URL=http://localhost:3100PAPERCLIP_AGENT_ID=                  # The agent's UUID from Paperclip``` --- ## Common Patterns ### Pattern: Manager delegates to reports ```typescript// In your manager agent's heartbeat handler:const { tasks } = await client.heartbeat(MANAGER_AGENT_ID); for (const task of tasks) {  if (task.complexity === 'high') {    // Delegate down the org chart    await fetch(`http://localhost:3100/api/v1/tasks/${task.id}/delegate`, {      method: 'POST',      headers,      body: JSON.stringify({ to_agent_id: engineerAgentId }),    });  }}``` ### Pattern: @-mention an agent in a task thread ```typescriptawait fetch(`http://localhost:3100/api/v1/tasks/${taskId}/messages`, {  method: 'POST',  headers,  body: JSON.stringify({    role: 'human',    content: `@${designerAgentId} Can you review the UI for this feature?`,  }),});// Paperclip delivers the mention as a trigger to the designer agent's next heartbeat``` ### Pattern: Export a company template (Clipmart) ```typescriptconst blob = await fetch(  `http://localhost:3100/api/v1/companies/${companyId}/export`,  { headers }).then(r => r.blob()); // Saves a .paperclip bundle with secrets scrubbedfs.writeFileSync('my-saas-company.paperclip', Buffer.from(await blob.arrayBuffer()));``` ### Pattern: Import a company template ```typescriptconst form = new FormData();form.append('file', fs.createReadStream('my-saas-company.paperclip')); await fetch('http://localhost:3100/api/v1/companies/import', {  method: 'POST',  headers: { Authorization: `Bearer ${process.env.PAPERCLIP_API_KEY}` },  body: form,});``` --- ## Troubleshooting | Problem | Fix ||---|---|| `ECONNREFUSED localhost:3100` | Server not running. Run `pnpm dev` first. || `401 Unauthorized` | Check `PAPERCLIP_API_KEY` is set and matches server config. || Agent never wakes up | Verify `heartbeat.enabled: true` and cron expression is valid. Check server logs for scheduler errors. || Budget exhausted immediately | `monthly_usd` budget too low or tokens_in/tokens_out are being over-reported. Check `POST /agents/:id/cost` payloads. || Task stuck in `open` | Agent may be offline or heartbeat misconfigured. Check `/api/v1/agents/:id/status`. || Database migration errors | Run `pnpm db:migrate` after pulling new commits. || Embedded Postgres won't start | Port 5433 may be in use. Set `EMBEDDED_PG_PORT=5434` in `.env`. || Org chart not resolving | `reports_to` agent ID must exist before creating the subordinate. Create top-down. | --- ## Resources - **Docs:** https://paperclip.ing/docs- **GitHub:** https://github.com/paperclipai/paperclip- **Discord:** https://discord.gg/m4HZY7xNG3- **Clipmart (company templates):** https://paperclip.ing/clipmart *(coming soon)*