Paperclip - Managing Teams of AI Agents (Full Tutorial)

Paperclip overview (what the tutorial is about)

• Paperclip is an open-source “control panel/control plane” for running teams of AI agents—not a single-agent framework.
• It runs on the user’s own server and treats agents like staff/employees within an organizational model.
• The core purpose is management + reliability + cost control for agent workflows—not building agents from scratch and not providing a drag-and-drop workflow builder.

Key architectural concept: organizational team + control plane

• The tutorial describes multiple agents (example: 6 agents) coming from three providers, all managed under one organizational structure.
• Roles mentioned:
  • Aida: strategy
  • Bruno: development
  • Kofi: synchronization mechanism
  • (In the demo) Olena: editor; positioned in a CEO/CTO-style hierarchy
• Agents are not rewritten—Paperclip coordinates them using a consistent control model.

The “why you need it” problem (pain points addressed)

Without orchestration, users often face:

• Too many parallel agent/IDE tabs (e.g., ~20 Claude Code tabs)
• Agents freezing or repeatedly getting stuck on the same faulty test
• Discovery happening only after bills arrive (token costs and quotas get consumed)
• Context/session fragility (context “lives in your head,” sessions die, users must restart explanations)
• Scaling breaks after a few agents because coordination overhead isn’t handled by the tools

Product features / systems highlighted

Single goal → inherited hierarchy

• You set one company goal (e.g., reach $1M/month).
• Projects/tasks inherit that goal so the purpose of work remains explicit.

Company isolation + multi-tenant deployment

• One deployment can serve many companies.
• Each company has separate records/data/audits.

Web UI + Node/React

• Node.js server
• React interface

Secrets handling

• Instance and company secrets stay encrypted.
• They are not exposed to prompts unless explicitly requested via a restricted launch.

Auditing / activity journal

• Tracks change actions, expense events, approvals.
• Maintains permanent history.
• Task discussions include tool calls and state changes with authorship.

No silent failures

• Crashed agents appear as error states (not endless spinners).

How execution works: “heartbeat” scheduling

• Agents don’t run continuously by default.
• Paperclip uses a heartbeat protocol:
  • Decides when to trigger cycles
  • Decides what context to pass
  • Sets how often per scheduled agent
• The agent decides how to respond to each received cycle.
• This heartbeat layer is positioned as the key orchestration abstraction.

Adapter model (connecting existing agents/tools)

• Agents/tools connect via adapters (examples include Claude Code, CodeX, Cursor, Gemini, open code, plus generic process/HTTP).
• Adapter interface described as three methods:
  • Invoke (starts the loop)
  • Status (reports state)
  • Cancel (stops execution)
• Principle: “Anything that can get a heartbeat can be hired.”
  • Minimizes rewriting and integration effort.

Task management + scheduling mechanics

• Task registration is required when agents take tasks (prevents duplication).
• Locks are first-class objects
  • Dependencies are declared in task data (e.g., task B depends on task A) rather than relying on memory.
• Wake-up queue is database-based
  • If an agent has multiple events, Paperclip assigns a logical cycle per event set.
• Rollback and versioning
  • Configuration changes are versioned
  • Failed edits can be rolled back rather than patched live

Cost control and budgets (major tutorial focus)

• Budgets exist at:
  • Agent level
  • Company level
• When an agent hits its monthly token budget:
  • Paperclip immediately stops the agent (no “warn later” behavior)
  • The queued job is canceled, and the agent suspends
• Expenses tracked by:
  • company, agent, project, goal, task, provider, model
• Includes a financial interface supporting automation via commands/scripts.

Routines + skills

Routines

• Scheduled work that generates real tasks (via webhook/API).
• Eliminates manual “start weekly report” work by waking designated agents automatically.

Skills

• Reusable knowledge/process patterns for agents.
• Includes a studio with evaluations and saved tests to validate effectiveness.

Consent limits

• Some expensive operations may require management approval.

UI/dashboard capabilities demonstrated

• Dashboard shows:
  • Agents activated/running/blocked/error states
  • Task statuses
  • Activity over the last ~14 days
  • Success rate computed from actual launches (not estimates)
• Opening a task shows:
  • A discussion thread
  • Tool calls made
  • Work materials added
  • An audit trail for actions that change state

Setup / installation details mentioned

• Requirements:
  • Node 24.11+
  • pnpm 9.15+
• Installation includes:
  • Download script + checksum verification (e.g., sha256sum check before running bash)
  • Installer places:
    • Managed CLI in home
    • Stable shim in PATH
  • Atomic updates with rollback (keeps two previous packages)
• Local options:
  • Test mode: foreground isolated instance with an initial CEO agent, no background service or first task auto-created
  • Dev flow: clone repo, pnpm install, pnpm dev (creates embedded Postgres)
• Access modes:
  • Trusted Local Access (loopback)
  • Authenticated mode (real logins)
  • Access presets like LAN/telnet mentioned
• Data layout:
  • One home folder holds config, database, repo, secrets
  • Backup/transfer folder concept

Repo / community / implementation notes (from the tutorial)

• Live stats pulled:
  • ~83,590 stars
  • ~15,141 forks
  • ~219 contributors
  • ~5,656 open tickets/merge requests
• Version:
  • 2026.9.1 (published September 21)
• Implementation:
  • Mostly TypeScript (reported ~82MB code size)
  • Rust kernel for performance-critical parts
  • Multiple adapter types (mentioned 15 types across 12 adapter packages)
  • Mentions 12 agent roles and 7 status states
• Execution/boot time:
  • Clean instance responds to health check in about 90 seconds (including embedded DB)

Explicit “when not to use it”

Paperclip is probably unnecessary if:

• You have one agent (likely not needed).

It’s not intended to:

• Teach you how to create agents
• Be a workflow builder (no drag-and-drop pipelines)
• Serve as a code review tool
• Act as a chatbot/prompt manager
  • Agents include their own prompts/models; Paperclip runs the organization around them

Expect complexity: large backlog and roadmap reading is recommended.

Also noted as incomplete/not fully complete:

• memory
• task queues
• desktop app

Additional operational detail:

• Telemetry enabled by default; can be disabled via environment variable.

Main conclusions stated in the tutorial

1. Paperclip is a control plane, not a normal agent—it coordinates agents you already have.
2. Heartbeat is the abstraction: any component that can respond to the ping/heartbeat interface can be integrated.
3. Control is built in from the start: atomic verification/checks, goal inheritance, and budgets that stop at the limit.

Main speakers / sources (as implied by the subtitles)

• The tutorial narrator/author of the walkthrough (no named on-screen host beyond example roles like Aida, Bruno, Kofi, Olena).
• Paperclip documentation / README and the GitHub repository
  • Used for installation instructions, system description, and referenced repo stats.