paperclipai/paperclip instruction manual

1. What Paperclip is and how it relates to Claude Code

Paperclip is an MIT-licensed, self-hosted control plane for organizing teams of AI agents. It runs as a Node.js server with a React board UI and can coordinate Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Pi, Hermes, Grok, Kimi, HTTP bots, custom processes, and external adapters. You define company goals, create projects and tasks, arrange agents in reporting lines, assign work, approve plans or hires, and monitor execution and reported cost from one dashboard.

**Claude Code classification:** Paperclip is a **standalone application** with **orchestration**, **context injection**, and **tool-surface** mechanisms. It does not modify the Claude Code runtime or install as a native Claude Code plugin. Instead, Paperclip invokes Claude Code through an adapter or sandbox runtime, wakes it through heartbeats, supplies task/goal/project context and skills at run time, and can expose Paperclip operations through MCP. The repository also includes a Claude runtime container image. Installation mode is therefore **standalone**, with medium-to-high setup effort depending on whether you use a local instance or a production deployment.

The product is aimed at users managing many concurrent agents rather than one chat session. Its main abstractions are organizations, goals, projects, issues, agents, workspaces, skills, connections, routines, approvals, budgets, artifacts, and run history. Experimental Agent Chat and chat/email connectors can add conversations through Paperclip or configured Slack, Discord, Telegram, and AgentMail services.

2. Install, onboard, configure, and test-drive

Paperclip requires Node.js 24.11 or newer. The standard onboarding command runs the CLI from npm’s cache while retaining instance configuration and data locally:

npx paperclipai@latest onboard --yes

This defaults to trusted local loopback mode. For authenticated/private access, explicitly select a LAN or tailnet bind:

npx paperclipai@latest onboard --yes --bind lan
# or:
npx paperclipai@latest onboard --yes --bind tailnet

Rerunning `onboard` preserves an existing configuration. Edit it with:

npx paperclipai configure

If a private npm registry causes an `E404`, inspect the selected registry and force the public registry for onboarding:

npm config get registry
npx --registry https://registry.npmjs.org paperclipai@latest onboard --yes

For an isolated foreground instance initialized with a CEO agent, use a documented test-drive command. Each run without `--data-dir` retains a unique temporary data directory and prints its path; `--data-dir` reuses one and `--no-browser` suppresses opening the UI.

ANTHROPIC_API_KEY=... npx paperclipai test-drive
OPENAI_API_KEY=... npx paperclipai test-drive --harness codex
OPENROUTER_API_KEY=... npx paperclipai test-drive \
  --harness opencode \
  --model openrouter/anthropic/claude-sonnet-4.5

A local test-drive does not install a service or create a first task. When launched from a linked Git worktree, it enables task execution there.

3. Source setup, UI package, and operating basics

For source development, the documented requirements are Node.js 24.11+, pnpm 9.15+, and—when the native Runner is enabled—a Rust toolchain or a compatible binary selected through `PAPERCLIP_RUNNER_BINARY`.

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

This starts the UI and API at `http://localhost:3100` and creates an embedded PostgreSQL database automatically. A typical local deployment is one Node process, embedded Postgres, and local file storage. Production can use an external Postgres deployment; authenticated mode and private networking are recommended for remote access.

In the board, create an organization, define goals, configure projects and their workspaces, add agents with roles and reporting lines, then assign issues. An agent wakes for assigned work, follow-up messages, configured timer heartbeats, or routine triggers. Mentions alone do not necessarily assign or wake another agent. Atomic checkout and execution locks prevent competing runs from claiming the same issue. Supporting adapters can retain session state across runs.

The separately published `@paperclipai/ui` package contains only production assets under `dist/`; consumers serve or copy that directory. Storybook development is documented as:

pnpm --filter @paperclipai/ui storybook
pnpm --filter @paperclipai/ui build-storybook

Keep root/workspace overrides for CodeMirror and Lezer dependencies aligned, because duplicate identities can break extensions or syntax highlighting.

4. Work, governance, costs, organizations, and reusable operations

Issues hold project, company, goal, parent, blocker, label, inbox, attachment, document, comment, work-product, and run information. Goal ancestry tells an agent why the work matters. Operators can search work, inspect revisions and artifacts, leave anchored document feedback, reassign tasks, and pause, resume, or terminate agents. Review policies and approval stages govern completion; connection approvals separately govern external tool calls.

Budgets can apply to a company, agent, or project. Paperclip records token and cost data by company, agent, project, goal, issue, provider, and model, raises threshold warnings, and can pause work at hard limits. Enforcement uses reported spend, so delayed reporting or in-flight work can delay a stop.

Routines create assigned issues on cron schedules or through API/webhook triggers. They support concurrency and catch-up policy and retain run history. Ready-made teams can package roles, skills, projects, and routines. Skill Studio supports shared skills, saved test inputs, result inspection, version history, and restoration.

One deployment can host multiple organizations with scoped tasks, agents, permissions, and activity. Company portability exports and imports operating setups while omitting referenced secret values; users must still review packages because ordinary environment values and local paths may remain. CLI examples documented by the repository are:

paperclipai company export <company-id> --out ./my-export
paperclipai company import ./my-export --dry-run
paperclipai company import org/repo --target new

Imported agents and routines start paused in the board flow. Export/import is not a replacement for full-instance backup and recovery.

5. Connections, credentials, MCP, and the complete agent tool surface

Connections combine a credential reference, capability catalog, governance rules, and audit trail. They may use MCP, native REST/OpenAPI, OAuth app installation, or webhooks. Operators can set gateway actions to Allowed, Ask first, or Off and limit which humans and agents may use each connection. Durable provider credentials belong in the instance vault—or, for an explicitly reviewed connection, Vercel Connect—not in agent configuration. Sign-in credentials and resource-connection credentials are separate.

Run the Paperclip MCP wrapper with `PAPERCLIP_API_URL` and `PAPERCLIP_API_KEY`; optional defaults are `PAPERCLIP_COMPANY_ID`, `PAPERCLIP_AGENT_ID`, and `PAPERCLIP_RUN_ID`:

npx -y @paperclipai/mcp-server

Read tools identify the caller; show a lightweight inbox; list/get agents, issues, comments, documents, projects, goals, approvals, approval issues/comments, and document revisions; retrieve heartbeat context and workspace runtime; and wait for a workspace service. Write tools create/update, checkout/release issues; add comments; suggest tasks; ask user questions; request confirmation; upsert or restore issue documents; control workspace services; create/link/unlink/decide approvals; and add approval comments.

During a heartbeat, injected run-scoped variables additionally enable `connections_search` to discover allowed connection actions and `connection_request` to request one. These expire with the run. `paperclipApiRequest` is a JSON-only escape hatch limited to `/api` paths when no dedicated MCP tool exists. The MCP server is only a REST wrapper: it neither accesses the database directly nor duplicates business logic.

6. Workspaces, sandbox runtimes, secrets, auditing, and observability

Paperclip resolves project repositories and workspaces before execution. Optional isolation can use Git worktrees and operator branches; configured sandbox providers extend execution beyond the local host. Runtime services can expose development servers and preview URLs. Every heartbeat passes through a database-backed wake queue, budget checks, workspace resolution, secret and skill loading, adapter invocation, log/usage recording, and bounded recovery.

The repository’s runtime image family provides Ubuntu 22.04, Node 24, Git, tini, a non-root UID/GID 1000 user, `/workspace`, and a harness-neutral shim. Derived images add OpenCode, Pi, Codex, Gemini CLI, or Claude Code. The shim reads `/run/paperclip/runtime-command.json`, resolves its command, and replaces itself so signals reach the harness. Images do not bake in secrets; per-run credentials arrive through ephemeral environment variables or files. The documented Claude smoke test is:

docker buildx bake -f docker/agent-runtime/buildx-bake.hcl base claude --load
docker run --rm ghcr.io/paperclipai/agent-runtime-claude:dev claude-code --version

Mutations, heartbeat transitions, costs, approvals, comments, and work products become durable activity records. File storage may be local or S3-compatible; credential storage is encrypted. Opt-in OpenTelemetry tracing activates when `OTEL_EXPORTER_OTLP_ENDPOINT` is set. Sentry activates independently with `SENTRY_DSN_FRONTEND` and/or `SENTRY_DSN_BACKEND`.

Anonymous product telemetry is enabled by default. Disable it with `PAPERCLIP_TELEMETRY_DISABLED=1`, `DO_NOT_TRACK=1`, `CI=true`, or `telemetry.enabled: false` in configuration.

7. Extending Paperclip with trusted plugins

The TypeScript plugin SDK provides worker lifecycle, host APIs, UI hooks, testing, bundler presets, and a development server. Install it with:

pnpm add @paperclipai/plugin-sdk

A plugin’s required `setup(ctx)` registers behavior. Optional lifecycle functions are `onHealth` for status, `onConfigChanged` for live configuration, `onShutdown` for cleanup, `onValidateConfig` for validation, and `onWebhook` for declared webhooks. `runWorker(plugin, import.meta.url)` starts the RPC worker only when executed as the main module.

The context exposes configuration, events, jobs, launchers, HTTP, secrets, activity, state, entities, projects, companies, issues, agents, goals, access/authorization, data, actions, streams, tools, metrics, logging, local folders, and the manifest. Capabilities declared in the manifest gate host APIs. Event subscriptions cover company, project/workspace, issue/comment/document/relation, agent/run, goal, approval, budget, cost, and activity changes. Plugins can emit namespaced events.

Jobs are declared with a five-field cron expression and registered with `ctx.jobs.register`; runs may be scheduled, manual, or retries, and thrown errors mark failure. UI slots include pages, sidebars, settings, dashboard widgets, entity tabs/views, toolbars, project items, comment annotations/actions, and a persistent app-shell overlay. Launchers navigate, open overlays, perform actions, or deep-link.

Worker functions include data/actions/tools registration, scoped state get/set/delete, agent invocation and chat sessions, issue creation/relations/subtree/checkout/wakeup/summary operations, safe local-folder reads and atomic writes, scoped JSON API routes, external-object detection/resolution, restricted plugin database namespaces, and SSE streams. UI hooks fetch worker data, run actions, read host context, navigate without reload, and subscribe to streams.

**Trust warning:** workers and same-origin plugin UI are trusted code; manifest capabilities are not a sandbox. npm-packaged installation is the supported deployed path, and dynamic installs currently suit persistent single-node deployments best.

8. Development, testing, evaluation, and known boundaries

Repository development commands are:

pnpm dev
pnpm dev:once
pnpm dev:server
pnpm dev:mobile
pnpm dev:both
pnpm build
pnpm typecheck
pnpm test
pnpm test:watch
pnpm test:e2e
pnpm db:generate
pnpm db:migrate

`pnpm test` runs Vitest, not Playwright. The server’s feature modules follow `adapters → application → domain`: domain code is pure and receives time explicitly; application code contains use cases and ports; adapters implement database and I/O behavior. External code imports only a module’s `index.ts`. Check this with `pnpm check:module-boundaries`. Database-backed server tests must use the shared embedded-Postgres helper to avoid touching a live control-plane database.

Prompt behavior evaluations require Promptfoo and a provider key:

pnpm add -g promptfoo
pnpm evals:smoke
cd evals/promptfoo && npx promptfoo@latest validate -c promptfooconfig.yaml

The documented cases test assignment pickup, checkout, progress and blocking, approvals, company boundaries, no-work exits, conflict handling, governed MCP calls, missing/revoked credentials, rate limits, elicitation, memory provenance, and auditable board commands. Paid browser runner campaigns are explicitly billable and should be narrowed to one selector; credential-free checks are `pnpm test:e2e:runner:unit` and `pnpm test:e2e:runner:typecheck`.

Key boundaries: Paperclip is not an agent framework or prompt manager; users bring models, harnesses, and prompts. Experimental Agent Chat/connectors may change. Sandboxing depends on the configured environment. Plugins are trusted, external services can receive data, and spend stops may lag. The supplied files do not provide an independent security audit, a Claude Code version matrix, or proof of every production deployment mode.