paperclip

Paperclip is a Node.js server and React UI that orchestrates teams of AI agents to operate like a real business. You define the company mission, hire agents from any provider (Claude Code, Codex, Cursor, bash scripts, HTTP bots), assign them roles in an org chart, and then step back while Paperclip keeps them aligned, funded, and accountable.

Instead of managing 20 open terminals and losing context on every reboot, Paperclip replaces that chaos with a structured task manager backed by a full control plane. Every task carries goal ancestry so agents always know the “what” and the “why.” Heartbeats wake agents on a schedule, atomic checkout prevents double-work, and budget hard-stops kill runaway spend before it craters your quota.

The platform ships twelve integrated systems out of the box: identity and access control, a work and ticketing engine, heartbeat execution with session persistence, governance and approvals, workspace and runtime management, plugin infrastructure, cost tracking, secrets management, activity logging, company portability, routines and schedules, and multi-company isolation. Each system handles the hard concurrency and audit-trail details that teams inevitably have to rebuild from scratch.

Paperclip is MIT-licensed and fully self-hostable. It can run in trusted-local mode on a developer machine or in authenticated mode behind a public URL with invite-based access, making it practical for solo builders, small teams, and portfolio operators running multiple autonomous AI businesses simultaneously.

What You Get

• A Node.js server and React UI deployable via Docker or direct install that serves as the single control plane for all your agents
• Bring-your-own-agent support for Claude Code, OpenAI Codex, Cursor, Gemini, Grok, bash scripts, HTTP bots, and external adapter plugins
• Org chart hierarchy with roles, titles, reporting lines, permissions, and monthly budget caps per agent
• Heartbeat execution engine that wakes agents on schedule, checks context, injects secrets and skills, and produces structured logs and cost events
• Atomic task checkout with execution locks so two agents never duplicate work on the same ticket
• Full goal-ancestry propagation — every task carries the company mission, project goal, and parent task so agents always know why they are doing something
• Multi-company isolation allowing one Paperclip deployment to run many separate companies with independent data and audit trails
• Company portability with export/import including secret scrubbing for sharing org templates

Common Use Cases

• Running an autonomous AI software company where a CEO agent delegates to CTO, engineering, and marketing agents all working toward a stated MRR goal
• Replacing 20 simultaneous Claude Code terminals with a task-manager interface where sessions persist across reboots and context is never lost
• Setting up recurring agent jobs — customer support, social posting, weekly reports — on scheduled heartbeats with supervisor oversight
• Operating a portfolio of AI businesses from one deployment with complete data isolation between companies
• Enforcing spend controls across multiple LLM providers by assigning monthly budgets to individual agents and blocking execution when limits are hit
• Managing governance for high-stakes agent actions through approval workflows, execution policies, and config-change rollback

Under The Hood

Architecture Paperclip follows a layered, domain-driven monorepo architecture with clear separation between the HTTP API surface, the service layer, and the data layer. The server package exposes an Express router broken into domain-specific route modules — companies, agents, issues, goals, approvals, costs, plugins, secrets, and more — each backed by a corresponding service module that encapsulates business logic. The database layer is encapsulated in its own package with Drizzle ORM managing schema, migrations, and typed query builders, keeping persistence concerns isolated from application logic. The heartbeat execution engine sits as an independent service that operates through a database-backed wakeup queue with coalescing semantics, meaning the architecture naturally handles back-pressure and prevents thundering-herd scenarios when many agents are due simultaneously. The plugin subsystem introduces a sandboxed worker runtime with its own lifecycle, tool registry, job scheduler, and event bus — effectively a micro-kernel within the server. This design allows the core platform to remain stable while third-party adapters and plugins extend capabilities at runtime without forking the server.

Tech Stack The entire platform is TypeScript running on Node.js 20+, using ESM modules throughout the monorepo. The server uses Express as the HTTP framework with a WebSocket layer for real-time live events. Persistence is PostgreSQL 17 accessed via Drizzle ORM with a bundled embedded-postgres option for zero-dependency single-machine deployments. The UI is built with React and Vite, using Storybook for component development. The CLI package provides a paperclipai command for local management tasks. The test suite runs on Vitest with Playwright powering end-to-end and release-smoke tests, and promptfoo driving LLM evaluation runs. Docker Compose manifests cover both local development and production deployment. The adapter layer supports Claude Code, OpenAI Codex, Cursor (local and cloud), Gemini, Grok, OpenCode, ACPX, and HTTP-based bots via a unified adapter protocol.

Code Quality The project maintains an extensive test suite with hundreds of Vitest unit and integration tests covering server services, database operations, adapter behavior, UI components, and CLI flows, plus Playwright end-to-end tests and release smoke tests. TypeScript strict mode is enforced across all packages. The codebase uses consistent named export patterns, explicit error types, and typed Drizzle schema that carries through to the service layer — making type mismatches a build-time rather than runtime failure. A CI pipeline enforces typechecking, forbidden-token scanning, and a no-git-push check alongside the test suite. The heartbeat service in particular shows careful defensive programming with atomic checkout guards, budget enforcement before any adapter invocation, orphan run recovery, and structured error propagation rather than swallowed exceptions.

What Makes It Unique Paperclip’s core innovation is treating agent coordination as an organizational management problem rather than a workflow automation problem. Most orchestration tools model agents as nodes in a DAG or steps in a pipeline; Paperclip models them as employees in a company with org charts, budgets, reporting lines, and strategic goal alignment. The atomic task checkout with database-backed execution locks is a technically precise solution to the double-work problem that most multi-agent frameworks handle poorly or ignore. The goal-ancestry propagation — where every ticket carries its full strategic lineage — is a design choice that meaningfully reduces context-injection overhead compared to systems that require users to manually reprompt agents with background information on each invocation. The plugin sandbox with its own tool registry and job scheduler allows the platform to be extended with new agent runtimes without modifying core server code, which is rare at this level of the stack.

Self-Hosting

Paperclip is released under the MIT License, one of the most permissive open-source licenses available. You can use it commercially without any copyleft obligations, modify the source code freely, incorporate it into proprietary systems, and redistribute it. The only requirement is retaining the copyright notice. There are no open-core restrictions, no feature flags gating enterprise capabilities, and no license keys to manage — every feature in the repository is available to every self-hoster.

Running Paperclip yourself requires a PostgreSQL 17 database (or the bundled embedded Postgres that ships with the package for simpler single-machine deployments) and Node.js 20+. Docker Compose manifests are included for a standard two-service setup. You are responsible for database backups (a built-in backup command is provided), TLS termination, horizontal scaling if needed, and keeping the server up to date as the project releases at a rapid cadence — roughly one release every one to two weeks. The heartbeat engine and workspace runtime are stateful services, so zero-downtime deploys require some care around in-flight agent runs.

Compared to using the hosted cloud tier at paperclip.ing, self-hosting means you own the data and infrastructure but give up managed upgrades, hosted backups, SLA guarantees, and any premium support channels the cloud product may offer. The cloud tier adds convenience for teams who do not want to operate the stack themselves; the self-hosted path gives full control at the cost of operational responsibility. Given the rapid release cadence and the project’s early stage, self-hosters should expect to track upstream changes closely.