Introducing a new way to review your PRs.

Read the announcement

paperclipai / paperclip

The open-source app everyone uses to manage agents at work

View on GitHub

30 documents · Updated Nov 20, 2026

overview

Knowledge Base updated: 2026-11-19

Paperclip knowledge base

Paperclip is a company operating system for assigning agent-assisted work, coordinating organizations, and governing execution. The server owns product APIs and orchestration; the web UI exposes those workflows; packages provide persistence, runners, adapters, plugins, and clients.

Critical durable state is held in the database schemas and migrations under packages/db/, while server services implement authorization, work lifecycle, automation, native runtime control, integrations, and realtime delivery. packages/paperclip-runner/ executes the native runner protocol; packages/adapters/ and packages/plugins/ connect external capabilities.

flowchart LR
  UI[Web UI] --> API[Server routes]
  CLI[CLI and MCP clients] --> API
  API --> SVC[Server services]
  SVC --> DB[(Postgres via packages/db)]
  SVC --> RT[Native runtime]
  RT --> RUN[paperclip-runner]
  RUN --> ADP[Adapter packages]
  SVC --> ENV[Environment providers]
  SVC --> PLG[Plugin host and SDK]
  PLG --> EXT[External apps and tools]
  SVC --> EVT[Realtime events and telemetry]
  EVT --> UI
flowchart LR
  I[Issue or routine trigger] --> Q[Heartbeat queue]
  Q --> P[Run preparation]
  P --> N[Native runtime]
  N --> R[paperclip-runner]
  R --> C[Completion/status decision]
  C --> I

Glossary

  • Native runtime — server-side execution control layer that prepares, monitors, resumes, and finalizes agent runs.
  • paperclip-runner — protocol-driven runner package that hosts provider drivers and semantic actions.
  • Responsibility area — organizational ownership domain with accountability bars, metrics, runs, and status reporting.
  • Routine — scheduled or event-driven repeatable work definition that can create and continue runs.
  • Adapter — package that exposes a provider-specific agent runtime, capabilities, authentication, and model configuration.

Codebase-wide invariants

  • Company-scoped mutations and reads must enforce authorization at service and route boundaries; see server/…/auth.ts and server/src/services/**.
  • Persistent product changes require schema and migration updates together; see packages/db/src/schema/**, packages/db/src/migrations/**, and packages/…/_journal.json.
  • Native execution must be mediated by runtime policy and completion/status handling rather than direct provider calls; see server/src/services/native-runtime/**.
  • Runner capabilities and semantic actions must remain contract-compatible with generated capability definitions; see packages/…/capability-contract.ts and packages/paperclip-runner/src/contracts/**.
  • Environment acquisition and release must preserve task lifecycle cleanup semantics; see packages/…/environment-creation-cleanup.ts and packages/…/environment-tasks.ts.

Routing table