Paperclip is a self-hosted Node.js server and React dashboard that runs a team of AI agents like a company, with an org chart, budgets, approval gates and scheduled heartbeats instead of a pile of terminal tabs. It picked up roughly 571 GitHub stars in a day to reach about 77,900 total, making it one of the largest MIT licensed agent orchestration projects on GitHub barely five months after its first commit. A working local install takes about five minutes, because the installer ships an embedded PostgreSQL and needs no account.

  • It orchestrates agents, it does not provide them. Claude Code, Codex, Cursor CLI, OpenClaw, bash scripts and plain HTTP bots all plug in. You bring the agent, the model and the API bill.
  • The unit of work is a ticket, not a chat. Every task carries its goal ancestry, gets checked out atomically so two agents cannot grab it, and produces an audit trail.
  • Install is one script. bash install.sh on macOS, Linux or WSL2 installs a managed CLI under ~/.paperclip/cli and starts onboarding. There is also an npx tryout that leaves nothing behind.
  • Budgets are enforced, not advisory. Per agent monthly limits stop work when hit, which is the whole point if you have ever watched a loop burn a quota overnight.
How Paperclip turns a company goal into agent work through the heartbeat loop A company goal becomes a scoped issue. A heartbeat wakes the assigned agent after checking its budget. The agent runs inside a workspace with scoped secrets and returns a work product. An approval gate applies board review, budget hard stops and audit logging, then feeds back into the goal. Any runtime can be attached, including Claude Code, Codex, Cursor, OpenClaw, bash and HTTP bots. Everything runs in one Node.js server with an embedded Postgres on localhost port 3100. PAPERCLIP · THE HEARTBEAT LOOP Work is a ticket with a budget, not a chat window you babysit. Goal company mission Issue scoped ticket Heartbeat wake + budget check Agent run workspace, secrets Work product diff, doc, report Approval gate: board review · budget hard stop · immutable audit log re-plan ANY RUNTIME, ONE ORG CHART Claude Code Codex Cursor CLI OpenClaw bash HTTP bots One Node.js process, embedded Postgres, dashboard on localhost:3100. genztech.blog
Fig 1 The heartbeat is the load bearing idea. Agents are not left running; they are woken on a schedule, budget checked, handed a scoped ticket, and their output goes through a gate before it counts.

What is Paperclip and why is it trending?

Paperclip describes itself in one line that does most of the explaining: if a coding agent is an employee, Paperclip is the company. It is not an agent framework and it does not tell you how to build agents. It assumes you already have several, running on different providers, and that the actual problem is coordination: who has what checked out, what the work is for, who approves it, and how much it is costing.

RelatedBlock Buzz Setup: Self-Host the AI Agent Workspace

The repo was created on 2 March 2026, is MIT licensed, and has around 180 contributors, 14,300 forks and 77,900 stars at the time of writing. The latest tagged release is v2026.722.0, published on 22 July 2026, and the default branch is pushed to constantly. That growth curve, plus a README that leans hard into the autonomous company framing, is most of why it keeps surfacing on GitHub trending.

Underneath the framing, the feature list is unusually concrete for a project this young. Agents get roles, titles, reporting lines and permissions. Issues carry company, project, goal and parent links, with atomic checkout backed by execution locks and first class blocker dependencies. Heartbeats come from a database backed wakeup queue with coalescing, budget checks, workspace resolution and secret injection. Cost is tracked by company, agent, project, goal, issue, provider and model, and overspend pauses the agent and cancels queued work rather than warning you afterwards.

How do you install Paperclip on macOS, Linux or WSL2?

The recommended path is the managed installer, because it gives you atomic updates, rollback and a stable entrypoint for the background service. These are the exact commands from the project documentation, checksum verification included:

# macOS, Linux or WSL2
$ curl -fsSLO https://paperclip.ing/install.sh
$ curl -fsSLO https://paperclip.ing/install.sh.sha256
$ if command -v sha256sum >/dev/null 2>&1; then
    sha256sum -c install.sh.sha256
  else
    shasum -a 256 -c install.sh.sha256
  fi
$ bash install.sh

The script verifies the platform, ensures Node.js 20 or newer is available, delegates to paperclipai install, and starts interactive onboarding if it has a terminal. Managed code lands in ~/.paperclip/cli with a stable shim at ~/.local/bin/paperclipai, while your config, database, uploads, logs, secrets and workspaces live separately under ~/.paperclip/instances/.

There is no native Windows path in the docs. Windows users go through WSL2, which the installer supports directly. The docs are also unusually honest about the checksum: it is served from the same origin as the script, so it catches transfer mistakes but is not an independent authenticity proof. If you care about that distinction, fetch a commit pinned copy from GitHub raw content and read it before running it.

For automation, or if you would rather not commit to an install yet:

# non-interactive managed install
$ curl -fsSL https://paperclip.ing/install.sh | bash -s -- --no-prompt --no-onboard
$ paperclipai onboard --yes

# ephemeral tryout, nothing installed permanently
$ npx --registry https://registry.npmjs.org paperclipai onboard --yes

# traditional global npm install
$ npm install --global --registry https://registry.npmjs.org paperclipai
$ paperclipai onboard

The --registry flag is not decoration. The docs call out a specific failure where a global ~/.npmrc pointing at a private registry makes npx resolve paperclipai against that registry and return a 404. Check with npm config get registry if the install fails that way.

How do you run it from source instead?

If you want to read the code or contribute, the source checkout is four commands and needs no database setup at all:

$ git clone https://github.com/paperclipai/paperclip.git
$ cd paperclip
$ pnpm install
$ pnpm dev

That starts the API server at http://localhost:3100 with an embedded PostgreSQL created automatically. Requirements are Node.js 20 or newer and pnpm 9.15 or newer. Useful sibling scripts are pnpm dev:server for the API only, pnpm dev:mobile to serve a prebuilt UI on port 3101 for phones and tablets, and pnpm test, which deliberately runs Vitest only. The Playwright browser suite is separate, behind pnpm test:e2e.

How do you keep it running in the background?

The quickstart path defaults to trusted local loopback mode, which is the fastest first run and also the least exposed. If you want it reachable from your LAN or a tailnet, you pick that explicitly at onboarding time, then install the service:

# choose a bind preset instead of loopback
$ paperclipai onboard --yes --bind lan
$ paperclipai onboard --yes --bind tailnet

# background service
$ paperclipai service install
$ paperclipai service status
$ paperclipai service logs -f

# health check when something looks wrong
$ paperclipai doctor

Paperclip uses a systemd user service on Linux and WSL2 systems that have user systemd, and a LaunchAgent on macOS. Containers, WSL1 and anything without a supported user service manager get foreground paperclipai run guidance rather than a hard failure. Updates take a database backup before switching payloads and can be reversed with paperclipai update --rollback, which retains the two previous payloads.

RelatedTencentDB Agent Memory Setup: Team Memory for Coding Agents

How does it compare to the usual setup?

ApproachPaperclipTerminal tabs per agentLinear or Asana plus agentsAgent framework
Survives a rebootSessions persist, tickets are durableNo, you lose everythingTickets persist, agent state does notDepends what you wrote
Who has work checked outAtomic checkout with execution locksYou, in your headAssignee field, no enforcementYou build it
Cost controlPer agent budgets with hard stopsProvider dashboard, after the factNoneYou build it
Approval before it shipsReview gates and board approvalYou watch the terminalHuman workflow onlyYou build it
Recurring workCron, webhook and API routinesYou remember to start itRecurring tasks, no runnerYou build it
Agent choiceAny runtime that takes a heartbeatAnyAny, glued by handUsually one ecosystem

What are the gotchas before you rely on it?

It is explicitly not for one agent. The README says so directly: if you run a single agent, you probably do not need this. The overhead of org charts, roles and approval gates only pays for itself when you are coordinating many agents toward one goal.

The project is moving very fast. Roughly 77,900 stars in five months with around 5,000 open issues is a lot of surface area still settling. Pin an exact version if you are wiring it into anything that needs to be reproducible; the installer supports --version and --ref for exactly that.

Telemetry is on by default. Paperclip collects anonymous usage data and states that prompts, issue content, file paths and secrets are never sent, with private repo references hashed per install. Disable it with PAPERCLIP_TELEMETRY_DISABLED=1, the standard DO_NOT_TRACK=1, or the config file. It is off automatically when CI=true.

One server process per instance, and it means it. paperclipai run refuses to start when the same instance is already supervised. Stop the service first rather than reaching for --force, which the docs frame as accepting single writer risk.

Uninstalling does not remove your data. paperclipai uninstall deliberately preserves ~/.paperclip/instances/, including databases, secrets and backups. That is the right default, but it means a clean slate takes a second, manual step.

What to watch · next 90 days
  • Whether the issue count converges. Around 5,000 open issues against a fast release cadence is the number that tells you if the ship rate is outrunning the fixes.
  • Bring your own ticket system. Asana, Linear and Jira on-ramps are on the roadmap but not shipped. That single feature decides whether Paperclip slots into existing teams or asks them to migrate.
  • Memory and knowledge. Still unchecked on the roadmap, and it is the gap between agents that resume a task and agents that actually accumulate context about your business.
  • Whether governance becomes the selling point. Scoped secrets, audit logs and budget hard stops are the parts an enterprise buyer would actually pay for, and almost nothing else in this category has them.

Our take

Paperclip is the first agent orchestration project we have looked at that treats cost and governance as core features rather than a settings page. Budget hard stops that cancel queued work, secrets scoped so they stay out of prompts unless a run explicitly needs them, and an approval gate that sits between agent output and anything shipping are all things most teams currently reimplement badly in shell scripts. Getting them in one MIT licensed install is a genuinely good trade.

The catch is that the framing oversells the reality. An autonomous company that hits a $1M run rate on its own is not what you get; what you get is very good infrastructure for supervising agents that still need supervising. Judged as that, it is excellent. Judged against the pitch, it will disappoint anyone who installs it expecting to walk away. Run it on a real but non critical workload first, pin a version, and let the issue backlog settle before it becomes load bearing for a team.

Primary sources

Original analysis by GenZTech. Every command above is quoted from the project's own README and installation documentation. Star counts, contributor totals and release details current as of 13 August 2026 via the GitHub repository.