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
- server/…/agents.ts,
server/src/services/agents/**,apps/web/src/**/agents/**-> docs/agent-work-management.md - server/…/issues.ts, server/…/issues.ts,
apps/web/src/**/issues/**-> docs/issue-execution.md - server/…/environment-*.ts,
server/src/services/environment/**,packages/plugins/sandbox-providers/**-> docs/execution-environments.md - server/…/agent-instruction-revisions.ts,
server/src/services/agent-instructions/**,apps/web/src/**/agent-instructions/**-> docs/agent-instructions.md packages/adapters/**,server/src/services/adapters/**-> docs/adapter-integrations.mdpackages/paperclip-runner/src/{backends,control-plane,drivers,live,native-session-runtime.ts,protocol-actions,semantic-tools}/**-> docs/native-runner-execution.md- server/…/companies.ts,
server/src/services/companies/**, packages/…/companies.ts -> docs/organization-work-management.md server/src/routes/{projects,goals,teams}.ts,server/src/services/{projects,goals,teams}/**-> docs/projects-goals-and-teams.mdserver/src/services/{artifacts,documents,comments,annotations,search}/**,server/src/routes/{artifacts,documents}.ts-> docs/work-products-and-conversations.mdserver/src/services/skills/**, server/…/skills.ts, packages/…/skills.ts -> docs/skills-and-knowledge-sources.mdserver/src/services/chat/**,server/src/services/connectors/chat/**, server/…/chat*.ts -> docs/chat-integrations.mdserver/src/services/heartbeat/**-> docs/automation-and-control.md- server/…/routines.ts,
server/src/services/{routines,routine-tools,routine-trigger-update-plan}.ts,apps/web/src/**/routines/**-> docs/routines-and-pipelines.md server/src/services/{decisions,approvals,inbox,alerts}/**, server/…/status-decision-committer.ts -> docs/decisions-approvals-and-attention.mdserver/src/services/{authorization,policy,security}/**,server/src/routes/security/**-> docs/security-and-governance.md- server/…/auth.ts,
server/src/services/{auth,authorization,memberships}/**-> docs/identity-and-access-control.md server/src/services/{secrets,credentials}/**, server/…/secrets.ts -> docs/secrets-and-credentials.mdserver/src/services/native-runtime/**,server/src/services/tool-access/**, server/…/tool-gateway.ts -> docs/runtime-and-tool-governance.mdpackages/plugins/**, server/…/plugin-*.ts -> docs/extensibility-platform.mdpackages/plugins/sdk/**, server/…/plugin-connector-runtime.ts -> docs/plugin-platform.mdpackages/cli/**,packages/mcp/**,server/src/routes/mcp/**-> docs/cli-and-mcp-interfaces.mdserver/src/services/{ai-connections,connector-telemetry,plugin-connector-runtime}.ts,server/src/services/connectors/**-> docs/external-app-connections.md- server/…/index.ts, server/…/openapi.ts,
packages/db/src/{migrations,schema}/**,docker/**-> docs/application-platform-operations.md server/src/services/{telemetry,analytics}/**,apps/web/src/**/{telemetry,analytics,consent}/**-> docs/product-telemetry-and-analytics.mdpackages/paperclip-runner/src/{catalog,contracts,eval}/**, packages/…/capability-contract.ts -> docs/runner-evaluation-and-conformance.mdserver/src/services/{cases,handoffs}/**, server/…/cases.ts -> docs/case-handoffs-and-continuity.mdserver/src/services/workflows/**, server/…/workflows.ts,apps/web/src/**/workflows/**-> docs/reusable-workflows.mdserver/src/services/budgets/**,server/src/services/cost/**, packages/…/budgets.ts -> docs/budgets-and-cost-controls.md- packages/…/responsibilities.ts, server/…/responsibilit*.ts, server/…/responsibilities-disabled.ts -> docs/organizational-responsibilities.md