Jonathon's AI Wiki

Paperclip — Run an AI-First Business as a Multi-Agent Company (Nate Herk / AIS+ Resource Guide)

12 min read

Source: raw/Run_an_AI_First_Business_with_Paperclip.pdf — 12-page AIS+ Resource Guide (AI Automation Society, by Nate Herk, May 2026). Companion to Run an AI First Business with Paperclip YouTube video.

Paperclip is an MIT-licensed open-source orchestration platform from paperclipai for running entire business units as teams of AI agents. The framing thesis: “if Claude Code is an employee, Paperclip is the company around it.” Self-hosted, free to run, BYO AI keys; not a chatbot, not a workflow builder, not an agent framework — it’s the management layer that sits on top of tools like Claude Code, Codex, or Gemini. You act as the board of directors, set the mission, hire AI agents into roles, approve decisions, monitor performance. Six pillars: heartbeat system (agents wake on triggers), goal cascade (mission → project → goal → issue → subtask), org chart (CEO + tree hierarchy), agent configuration (instructions / runtime / skills / budget / runs), pre-built companies (16 templates, 440+ agents, 500+ skills), and the Claude Code REST API integration.

Key Takeaways

  • Paperclip is the company; agents are the employees. Not a chatbot interface — agents have structured job assignments, not conversations. Not an agent framework — doesn’t tell you how to build agents. Not a drag-and-drop workflow builder — uses company structure, not pipelines. Not a prompt manager — agents bring their own configurations. Not for single-agent scenarios — designed for teams. Open-source MIT, self-hosted on your machine, no Paperclip account/subscription, BYO AI keys.

  • Why this matters. Instead of prompting one AI tool at a time, you manage an entire team of AI agents that work autonomously: agents wake on a schedule, check assigned tasks, do the work, report back — without you prompting. Run a content team, dev shop, research lab, or marketing agency with AI agents filling every role. Built-in cost controls (monthly budgets per agent), full audit trails, governance to approve or deny agent decisions before they execute. “Not a toy. Production-grade infrastructure for running autonomous businesses.”

  • The tech stack. Single Node.js process on your machine: React frontend (the dashboard), Express.js REST API (backend), embedded PostgreSQL database (zero config, all data local). Everything runs on http://localhost:3100 — no cloud services needed.

  • Heartbeat system — the core loop. Agents do not run continuously; they wake on triggers like an alarm clock. An agent wakes when: scheduled interval fires (e.g., every 30 min, hourly); a new task gets assigned; someone mentions it in a comment; you manually trigger from the dashboard; an approval decision is made.

    • 9-step heartbeat protocol: (1) Check identity — who am I, role, budget? (2) Handle pending approvals (3) Check inbox — what tasks are assigned? (4) Pick highest-priority work (5) Atomic-lock checkout (only one agent works on a task at a time) (6) Understand full context (7) Do the work using available tools (8) Update status and leave comments (9) Delegate subtasks to reports if needed → sleep until next trigger.

  • Goal Cascade hierarchy. Every piece of work traces back to the company mission: Company Mission → Project → Goal → Issue/Task → Subtask. Every agent knows WHY they’re doing something, not just WHAT — context flows down from the mission to every task.

  • Org Chart and Chain of Command. Tree-based hierarchy. Every agent reports to exactly one manager. CEO at the top reports to you (the board / human operator). Managers create and delegate subtasks to direct reports; agents escalate blockers up the chain; cross-team assignments possible but agents can’t cancel cross-team tasks. You control org structure, decide who reports to whom, approve hire requests.

  • Five-step setup workflow.

    1. Prerequisites: Node.js 20+, Claude Code installed and authenticated, terminal. Windows users: enable Developer Mode (Settings > System > For Developers) for Paperclip’s skill symlinks to work — without it you get EPERM errors.
    2. Install and launch: npx paperclipai onboard --yes — interactive setup that configures embedded Postgres, sets up auth, walks first-company creation. Runs at http://localhost:3100.
    3. Create your company: name (e.g., “AIS Content”), mission/goal, issue prefix (e.g., “AIS” so tasks show as AIS-1). One Paperclip instance can run multiple companies with complete data isolation.
    4. Create your CEO agent: every company needs a CEO as the first agent. Set role to CEO, pick the claude_local adapter (uses Claude Code on your machine), choose a model (claude-sonnet-4-6 is a good balance), set a working directory, enable “can create agents.” First task: “Create a hiring plan and build out the team.”
    5. Let the team build itself. The CEO proposes new hires. You see a hire request in your inbox — review (name, role, capabilities) and approve or deny. This is the governance layer in action — nothing happens without your sign-off.

  • Five agent configuration areas.

    1. Instructions — agent’s core identity. Who it is, role, responsibilities, decision-making guidelines, domain knowledge, how it should communicate with other agents. “Job description plus training manual combined.”
    2. Configuration — technical runtime: adapter type (Claude Code, Codex, Gemini, etc.), model, timeout per heartbeat, max turns per heartbeat cycle, env vars, heartbeat interval, wake triggers.
    3. Skills — reusable instruction sets injected at runtime. Each is a SKILL.md with YAML frontmatter (name + description for routing) + detailed instructions in markdown. Lazy-loading: agents only load a skill when relevant — keeps base prompt lean.
    4. Budget — Paperclip tracks every agent’s token consumption (provider, model, tokens, cost in cents). Set company-wide AND per-agent monthly budgets. At 80% the agent gets a soft warning. At 100% the agent is auto-paused until budget resets. Prevents runaway costs.
    5. Runs — every heartbeat is logged: when it ran, how long, what tasks, full transcript, token usage and cost, success or failure. Complete visibility.

  • Skill structure (Paperclip’s flavor).

    skill-name/
  SKILL.md
  references/   (optional supporting files)

    ---
name: skill-name
description: Use this skill when the agent needs to [specific trigger]
---
[Detailed instructions in markdown]
    • Routing-focused descriptions: include when to apply AND when to skip.
    • Concrete instructions: code examples and API calls, not abstract guidance.
    • Single responsibility: each skill handles one focused concern.
    • Minimal SKILL.md: detailed reference material in separate files.

  • Pre-built companies repo (the killer feature). Paperclip ships an official GitHub repo at github.com/paperclipai/companies with 16 pre-built company templates (440+ agents, 500+ skills total). Each includes full org structure, agent configurations, reporting lines, pre-loaded skills.

    • Available templates:
      • Agency Agents — full-service AI agency with 167 agents across 10 divisions
      • Fullstack Forge — development consultancy with 49 agents and 66 skills
      • Product Compass Consulting — AI product management with 48 agents
      • Donchitos Game Studio — indie game dev with 48 coordinated agents
      • K-Dense Science Lab — multi-disciplinary research with 54 agents and 177 skills
      • Trail of Bits Security — security auditing with 28 agents
      • ClawTeam Capital — investment analysis with 7 agents
      • GStack — engineering workflows with distinct cognitive modes
      • 8 more covering creative strategy, code review, research, etc.
    • Import via dashboard (Org Chart → Import Company) or CLI: npx companies.sh add paperclipai/companies/[company-name] (e.g., npx companies.sh add paperclipai/companies/fullstack-forge).

  • Supercharging Paperclip with Claude Code. Claude Code can directly interact with Paperclip’s REST API at localhost:3100. What Claude Code can do that the dashboard sometimes can’t yet:

    • Pull real-time status on all agents, tasks, costs.
    • Read task details and agent configurations.
    • Edit agent configs, skills, tools files.
    • Add API keys to the encrypted secrets manager (the UI doesn’t have this yet — Claude Code fills the gap).
    • Wire secrets into agent adapter configs.
    • Troubleshoot failed heartbeats by reading run logs.
    • Create and assign tasks via the API.

  • Secret management via Claude Code (UI gap workaround). Paperclip has an encrypted secrets manager built in but the UI doesn’t surface it yet. Three-step process Claude Code automates: (1) Claude Code creates the secret via the API (encrypted at rest); (2) Claude Code patches each agent’s adapter config to reference the secret; (3) when the agent’s heartbeat fires, Paperclip decrypts and injects the key as an env variable. Keeps API keys encrypted, out of config files, automatically scrubbed from exports.

  • API cheat sheet (most-useful endpoints).

    • List agents: GET /api/companies/{companyId}/agents
    • List tasks: GET /api/companies/{companyId}/issues
    • Company costs: GET /api/companies/{companyId}/costs/summary
    • Costs by agent: GET /api/companies/{companyId}/costs/by-agent
    • Create secret: POST /api/companies/{companyId}/secrets
    • Update agent: PATCH /api/agents/{agentId}
    • Activity log: GET /api/companies/{companyId}/activity
    • Org chart: GET /api/companies/{companyId}/org

  • Tips and best practices.

    • Start with conservative budgets — easier to increase than undo overspending.
    • Keep board approval on for new agent hires until you trust your CEO agent’s judgment.
    • Monitor costs early — check the costs dashboard after the first few heartbeats.
    • Start local, move to a VPS later — get it working on your machine first; for 24/7 operation move to a server.
    • Use template export for backup before major changes; secrets get scrubbed automatically.
    • Write custom skills for recurring workflows.
    • Use Claude Code as your Paperclip assistant — sees the API, manages secrets, configures agents, troubleshoots faster than the UI.
    • Windows users: enable Developer Mode before running Paperclip.

  • PDF’s 8-item Key Takeaways:

    1. Paperclip is the control plane for running AI agent companies. Open-source, self-hosted, free.
    2. You act as the board of directors — agents work autonomously; you approve hires, strategy, major decisions.
    3. Heartbeat system is the core loop — agents wake, check work, execute, report, sleep. Every action logged.
    4. Agent configuration has five key areas: Instructions, Configuration, Skills, Budget, Runs.
    5. Skills are runtime-injected instruction sets giving agents specialized capabilities without bloating base prompt.
    6. Import pre-built companies from GitHub (440+ agents, 500+ skills) with a single command.
    7. Claude Code supercharges Paperclip by accessing the REST API: secret management, monitoring, configuration, troubleshooting.
    8. Start local and simple. Scale up as you learn what works.

Where it fits in the wiki

  • The “company-shaped multi-agent” pattern, formalized. Angela & Caitlin’s platform-team interview frames the end-state as “managed agents all the way down” + advisor / adversarial / swarm / best-of-N / deep-research orchestration patterns. Paperclip is the open-source self-hosted instantiation of that pattern — explicit org chart, governance, budgets, heartbeats.
  • Sister to Crabbox in the open-source-counterpart-to-Anthropic-infrastructure cluster. Crabbox = short-lived Linux box per agent run (counterpart to Managed Agents sandboxing); Paperclip = long-lived multi-agent company management plane (counterpart to Managed Agents orchestration). Both MIT, both self-hosted, both BYOK. They compose: Paperclip schedules the work, Crabbox provides the disposable execution environment.
  • Validates the MCP-tier-3 thesis. Paperclip’s killer integration is “Claude Code talks to Paperclip’s REST API.” No MCP layer, no custom protocol — just a Node.js localhost API that any agent harness can call.
  • Sister course to Nate’s Claude Code AIOS masterclass / Hermes 1-Hour Course / Codex 1-Hour Course — same operator, four-harness lineup. Paperclip is the company-management layer; the others are the underlying agent surfaces.
  • Convergent on the same agentic-OS architecture as Simon Scrapes’ nine-component AIOS and the 2026 Claude Code AIOS Pattern — clever context management + clear org structure + budget discipline + memory persistence + scheduled heartbeats + governance gates. Paperclip ships the framework; the AIOS articles describe the operator-built patterns it formalizes.

Implementation

  • Tool/Service: Paperclip (MIT) — github.com/paperclipai/paperclip + github.com/paperclipai/companies.
  • Setup: npx paperclipai onboard --yes from a directory you want Paperclip to live in.
  • Prerequisites: Node.js 20+, Claude Code authenticated, terminal. Windows: enable Developer Mode first.
  • Cost: Paperclip itself free (self-hosted). You pay for agent token usage (BYO AI keys). Per-agent and company-wide monthly budgets prevent runaway costs.
  • Defaults: claude_local adapter with claude-sonnet-4-6 for the CEO; localhost:3100; embedded Postgres; manual approval for new agent hires; conservative starter budgets.
  • Integration notes: Paperclip’s REST API is the canonical Claude Code integration point. Pre-built companies CLI: npx companies.sh add paperclipai/companies/[name]. Paperclip is for teams of agents — explicitly NOT for single-agent scenarios.

Open Questions

  • Adapter coverage detail. PDF says adapters exist for Claude Code, Codex, Gemini, “etc.” — does that cover Hermes Agent? Open-source models via Ollama or vLLM?
  • Multi-tenant deployment. PDF says “one Paperclip instance can run multiple companies with complete data isolation.” Single-OS-process tenant isolation, or separate Postgres schemas?
  • Heartbeat granularity vs cost. Default heartbeat is “every hour”; how short can it go? At 5-min intervals × 50 agents, what’s the realistic monthly token bill on claude-sonnet-4-6?
  • Cross-company agent sharing. Can a “research” agent be shared across multiple companies, or does each need its own?
  • Failure isolation in cross-team tasks. Agents can be assigned cross-team tasks but can’t cancel them. What happens on cross-team failures?
  • Scale ceiling. 167-agent template (Agency Agents) on what hardware footprint?
  • Cloud-hosted Paperclip option. PDF says “start local, move to VPS.” Is there an official Paperclip-as-a-Service?

Try It

  1. Install prerequisites — Node.js 20+, Claude Code (authenticated), terminal. Windows: Developer Mode enabled.
  2. Run npx paperclipai onboard --yes in a fresh directory. Walk through the interactive setup, create your first company. Open http://localhost:3100.
  3. Create your CEO agent with claude_local adapter, claude-sonnet-4-6, working directory, “can create agents” enabled. First task: “Create a hiring plan and build out the team.”
  4. Approve or deny the CEO’s hire requests as they appear. Watch the org chart grow.
  5. Set conservative budgets first — both company-wide and per-agent. Check the costs dashboard after the first few heartbeats.
  6. Import a pre-built company template: npx companies.sh add paperclipai/companies/fullstack-forge — 49 agents in one command.
  7. Wire Claude Code as your Paperclip executive assistant. Open Claude Code in the project directory. Ask Claude Code to: list agents, pull cost summary, create a secret + wire it to an agent (the UI gap fix).
  8. Write one custom skill for a recurring workflow. Routing description should say when to apply AND when to skip.
  9. Run heartbeats manually first before scheduling — verify the agent does what you expect before letting it run on a timer.

Graph View

Backlinks