The Paperclip Compendium

What Paperclip does, how to install it, how to build your first agent company, and how to keep its agents, costs and permissions under control.

Paperclip gives AI agents an org chart, task board, budgets and a human board. This compendium covers stable release 2026.916.1, tested on September 28, 2026. The main lab ran on Debian 13 with Node 24.21, four CPU cores, 8 GB of RAM and embedded Postgres. Those were test resources, not a measured minimum.

The first local-model check captured the tradeoff in one line. Ollama returned “local model OK” through Codex, but the run recorded 91,630 tokens because Codex also sent its system prompt and tool definitions. Paperclip made the work visible. It did not make the overhead disappear.

If you have never used an AI agent, start with the first chapter; it assumes nothing. If you already run agents, skip to installation, costs and troubleshooting.

In this compendium:

• What Paperclip is and when its control plane earns its keep
• A safe installation for a laptop or private server
• A first company, CEO, task and hiring approval
• Connections to subscriptions, APIs, local models and gateways
• Cost controls, security defaults and tested failure modes
• Three starter configurations and a troubleshooting field guide

What Paperclip is, in plain English

First, what an AI agent is. A chatbot answers you in a window. An agent is a program that uses an AI model to act: it reads files, runs commands, calls web services and writes results, often for minutes at a time without you watching. Claude Code and Codex are the best-known examples; you start one in a terminal, describe a job, and it works through it step by step.

One agent is manageable. Five agents with different jobs, schedules and access are not, unless something keeps track of who is doing what, what it costs and who approved it. That is the job Paperclip takes on.

Paperclip is a management layer for AI agents. It is not an AI model, chatbot, prompt library, coding assistant or general workflow builder. The models and command-line agents do the work. Paperclip gives them assignments, reporting lines, working directories, budgets and a shared record.

The simplest analogy is a small company. You are the board. The agents are employees. Issues are work tickets. An adapter connects each employee to the command-line program or service that supplies its intelligence. The official introduction calls Paperclip an operating system for an AI company.

The main parts are:

• Company: An isolated organization containing its goal, agents, work, budget and approvals.
• Board: The human authority. The board can approve proposals, pause agents and override decisions.
• Agent: An AI worker with a role, manager, instructions, adapter, budget and run policy.
• Adapter: The integration layer that starts a runtime, supplies context and collects output.
• Issue or task: Two names for the same unit of work. An agent checks it out, works it and records a disposition.
• Atomic checkout: A server-side claim that prevents two agents from owning the same task simultaneously.
• Heartbeat: One execution window. The agent is dormant again when the run ends.
• Routine: A scheduled or webhook-triggered action that creates or reopens work.
• Budget: A dollar-denominated policy for a company, project or agent.
• Approval: A durable proposal that waits for a board decision.
• Skill: A reusable set of instructions attached to an agent.
• Secret: An encrypted credential referenced by configuration rather than written in plain text.
• Workspace: The directory or repository in which an agent acts.
• Run record: The stored command, context, transcript, usage and result from one heartbeat.

A normal day might begin when the CEO creates a task for a researcher. Assignment wakes the researcher. The researcher checks out the task, reads its comments, writes in the assigned workspace and posts a completion note. If the work needs a subordinate task, the agent creates one with the same goal and a parent-task reference. Paperclip retains the thread, run and cost event for review.

A heartbeat is not a resident mind. Four events can wake one: a timer, an assignment or comment, a person’s on-demand request, or an automation such as a routine. New agents have timer heartbeats off by default. That is the right starting state.

A short history

The Paperclip repository was created on March 2, 2026. The first npm package, 0.1.1, appeared the next day. Six versions were published on that first release day.

A registry snapshot fetched September 28 Pacific time counted 1,602 versions: 34 stable, 1,519 canary, 39 nightly and 10 beta. Stable releases tended to arrive every one to three weeks, while experimental builds accounted for most of the volume. The four named channels are stable, beta, nightly and canary.

Attention rose quickly. Dated snapshots recorded 43,911 stars on April 2 and 69,955 on June 11. The GitHub API returned 92,924 stars, 15,904 forks, 452 watchers, 6,001 open issues and pull requests combined, and 198 discussions on September 28. The earlier star figures come from dated secondary snapshots; the final count came from the repository API.

The creator uses the name Dotta and is the npm maintainer and company CEO. In an August interview, Dotta identified Scott Tong as a co-founder. That is a self-reported company history, not a verified identification of Dotta.

Paperclip published eleven security advisories in April. Ten list 2026.416.0 as the patched release. One report about a connector lists no patched version. A twelfth advisory followed in July. Stable 2026.916.1, released September 21, was the current version at this compendium’s cutoff.

A September 24 NetworkChuck video showed Paperclip running a homelab IT desk. Paperclip Cloud was still a waitlist product, with no public general-availability date.