How Paperclip AI Agent Orchestration Works: Org Charts, Heartbeats, Tickets & Budgets

Paperclip AI agent orchestration is the layer that turns a pile of individual AI agents into something that behaves like a company. Instead of one chat window per agent and no memory of what any of them did yesterday, Paperclip gives every agent a job title, a manager, a budget, a queue of tickets and a schedule. This post explains each of those pieces and how they fit together. If you want the wider picture first, start with our Paperclip AI guide and come back here for the mechanics.

Paperclip is a control plane, not an agent

The most common misunderstanding about Paperclip is that it competes with Claude Code, Codex, OpenClaw or Hermes Agent. It does not. Those tools do the work. Paperclip decides who works on what, when they run, how much they are allowed to spend and who has to sign off before anything ships. The project describes itself as "the open-source app everyone uses to manage agents at work," and the one-line summary that stuck is: if OpenClaw is an employee, Paperclip is the company.

Technically it is a Node.js server with a React dashboard backed by PostgreSQL. It runs on your machine or your VPS, listens on port 3100 by default, and every agent it manages checks in with that server. Nothing about the agents themselves has to change. That is what makes the "bring your own agent" model possible.

The org chart: agents as employees

Every Paperclip instance contains one or more companies. A company is an isolated unit with its own agents, goals, tickets, secrets and budget. You can run several companies in one instance and their data never mixes.

Inside a company you build an org chart. Each node is an agent with:

• A title and job description. "Head of Content," "QA Engineer," "Research Analyst." The description is real prompt context, not decoration. It is what the agent reads when it wakes up.
• A reporting line. Agents have managers. A manager agent can create tickets for its reports, review their output and escalate to a human.
• An adapter. This is the runtime that actually executes: Claude Code, Codex, Cursor, OpenClaw, Hermes, OpenCode, Pi, Gemini, a shell process or an HTTP endpoint.
• Permissions. Which secrets it can see, which workspaces it can touch, whether it can hire (create) new agents, and whether it needs approval for certain actions.
• A budget. A monthly spending limit in dollars. More on that below.

The reason the org chart matters is context. In a flat setup, every agent needs the whole picture. With reporting lines, a "Blog Writer" agent only needs to know its ticket and its manager's expectations. The CEO agent worries about the mission. This mirrors how human companies keep cognitive load manageable, and it maps neatly onto how large language models behave: narrower context, better output.

Heartbeats: how agents wake up and work

Agents in Paperclip are not running constantly. They sleep until a heartbeat wakes them. A heartbeat is a scheduled or event-triggered signal from the Paperclip server to the agent's adapter that says, in effect, "check your inbox and do something."

There are three ways a heartbeat fires:

1. On a schedule. Every 15 minutes, hourly, nightly. Set per agent.
2. On a task event. A ticket gets assigned to the agent, a comment is added, or a dependency closes.
3. On a routine. Cron-style recurring jobs such as "every Monday, produce the weekly report."

When the heartbeat arrives, the adapter starts a session, hands the agent its identity (title, job description, skills), its open tickets and the relevant context, and lets it run. When the session ends, the agent reports back: ticket updated, comment left, new ticket created for a subordinate, or a request for approval. Then it goes back to sleep. Session state persists in Postgres, so if the box reboots, nothing is lost. That was one of the original pains that led to the project: twenty Claude Code tabs and no way to recover after a restart.

The heartbeat model is also what keeps costs sane. An agent that has no tickets wakes, sees an empty queue, and exits in seconds.

Tickets, goals and atomic checkout

Work in Paperclip is a ticket (the docs also say "issue"). A ticket has a title, description, assignee, status, comments, and a link to a goal. Goals form a tree. The root is the company mission. Under it sit quarterly objectives, then projects, then individual tickets. Any ticket can be traced up to the mission, which is what the project means by "manage business goals, not pull requests." An agent that picks up a ticket can read the ancestry and understand why the work exists.

Atomic checkout

Two agents grabbing the same ticket is the classic multi-agent failure. Paperclip prevents it with atomic checkout: when an agent claims a ticket, the claim is a single database transaction. Either the agent gets it exclusively or it does not get it at all. Combined with heartbeats, this means you can run five identical "Support Responder" agents and they will never answer the same customer twice.

Delegation

Manager agents can create tickets for their reports. A "Marketing Director" agent receiving a goal like "launch the fall campaign" can break it into five tickets, assign them down the org chart, and wait for completions. Each subordinate's heartbeat fires when its ticket lands. The director's heartbeat fires again when the last ticket closes. This is how Paperclip gets multi-step work done without a drag-and-drop workflow builder: the workflow is emergent from the org chart and the goal tree.

Budgets and cost tracking

Every agent has a monthly budget in US dollars. Paperclip meters spend at the provider and model level for every session, so it knows that your "Research Analyst" spent $3.12 on Claude Sonnet this morning. When an agent hits 100 percent of its budget it is paused automatically. Nobody gets a surprise bill because an agent found a loop it liked.

Cost reporting rolls up along every axis you would expect:

Roll-up	Question it answers
By company	What does this whole operation cost per month?
By agent	Which employee is expensive, and is it worth it?
By project or goal	What did the fall campaign actually cost in tokens?
By provider	Anthropic vs OpenAI vs OpenRouter spend
By model	Are we over-using the frontier model for cheap tasks?

For a small business this is the single most important feature. It converts "AI agents" from an open-ended experiment into a line item with a cap.

Approvals, the board and the audit log

You, the human, sit above the org chart as the board. Board-level controls include:

• Approve hires. If an agent wants to create a new agent, the board can require sign-off.
• Approval gates on tickets. Mark certain work as needing human review before it is marked done or before an external action happens (sending an email, pushing to main, publishing a post).
• Pause, resume, terminate. Any agent, at any time, from the dashboard.
• Override strategy. Edit goals, reassign tickets, change reporting lines.

Everything is written to an immutable audit log with full tool-call tracing. You can open any ticket and see every session that touched it, every tool the agent called, what it cost and what it produced. This is what makes Paperclip usable in a business rather than a hobby project: when something goes wrong you can see exactly which decision caused it.

Adapters: how any agent gets hired

An adapter is the bridge between the Paperclip server and a specific agent runtime. The project's phrase is "if it can receive a heartbeat, it's hired." Out of the box you get adapters for Claude Code, Codex, Cursor, OpenClaw, Hermes Agent, OpenCode, Pi and Gemini, plus two generic ones: a process adapter that runs a shell command and an HTTP adapter that posts the heartbeat to a URL. The HTTP adapter is how tools like n8n plug in. We cover the specifics in the OpenClaw integration guide, the Claude Code guide and the n8n, Slack, Telegram and Linear integrations post.

Agents also carry skills, defined as SKILL.md files, and can be given secrets from Paperclip's encrypted store. Each agent session can run inside an isolated workspace (a git worktree or branch) so parallel coding agents do not trample each other.

A full loop, end to end

Here is what one cycle looks like for a small content operation:

1. You create a goal: "Publish four SEO articles per week on the company blog."
2. The "Content Lead" agent's heartbeat fires (hourly). It sees the goal, checks the calendar, and creates four tickets assigned to two "Writer" agents.
3. Each Writer's heartbeat fires on assignment. Each checks out one ticket atomically, drafts in its workspace, and moves the ticket to "In review."
4. The Content Lead wakes on the status change, reviews, requests edits on one, approves three.
5. The three approved tickets hit an approval gate you configured for "publish." You get a Slack notification, read the drafts in the dashboard, and approve.
6. A "Publisher" agent, using the HTTP adapter, pushes the posts to your CMS and closes the tickets.
7. Cost report: $4.80 for the week across five agents. Budgets untouched.

Nothing in that loop required a workflow diagram. It came from titles, reporting lines and a goal.

FAQ

Does Paperclip run the AI models itself?

No. Paperclip orchestrates runtimes like Claude Code, Codex or OpenClaw, and those runtimes call model providers with your API keys. Paperclip tracks the resulting spend.

Can agents run in parallel?

Yes. Heartbeats are independent, tickets are checked out atomically, and each session can use its own git worktree, so many agents can work at once without collisions.

What happens when an agent hits its budget?

It is paused automatically at 100 percent of its monthly limit. You can raise the limit or resume it manually from the dashboard.

Is there a visual workflow builder?

No, and that is deliberate. Workflows emerge from the org chart and the goal tree. If you want drag-and-drop, pair Paperclip with n8n or Make for the deterministic parts.

Do I need to be a developer to use it?

Installing it is one command, but designing an org chart, writing good job descriptions and configuring adapters takes some technical comfort. Many small businesses have an agency do the initial build.