How paperclipai/paperclip works
Paperclip is an application for orchestrating AI-agent organizations. The documented workflow is to define company goals, organize agents and work, approve or govern execution, then monitor results and costs in the UI. Its server, UI, relational domain model, and adapter ecosystem are the main runtime layers. The excerpts show schema responsibilities and selected storage/runtime helpers, but not the server route wiring or most UI/API calls; those links are therefore documented only where the README supports them, and otherwise omitted.
Main entry points: app.ts Application server · run-lifecycle.ts Agent run lifecycle · adapters Agent adapters · App.tsx Manage and monitor
Components 20
Goals and work
- Business goals
packages/db/src/schema/goals.ts - Projects
packages/db/src/schema/projects.ts - Tasks and approvals
packages/db/src/schema/issues.ts - Workflow pipelines
packages/db/src/schema/pipelines.ts - Pipeline cases
packages/db/src/schema/pipeline_cases.ts - Activity and run history
packages/db/src/schema/heartbeat_runs.ts
Organization and governance
- Company settings
packages/db/src/schema/companies.ts - Agent roster
packages/db/src/schema/agents.ts - Skills and training
server/src - Budgets and costs
packages/db/src/schema/companies.ts
Execution platform
- Application server
server/src/app.ts - Agent run lifecycle
server/src/services/heartbeat/run-lifecycle.ts - Agent adapters
packages/adapters - Agent runner
packages/paperclip-runner/src - MCP and integrations
packages/mcp-server/src/client.ts - Workspace snapshots
server/src/services/remote-workspace-snapshot-storage.ts - Setup and operations
cli/src/index.ts
User interface
- Manage and monitor
ui/src/App.tsx
Persistent state
- PostgreSQL state
packages/db/src/client.ts
Other components
- Human user
Connections 19
- Human user → Manage and monitor: sets goals
README.md - Manage and monitor → Application server: manages organization
README.md - Application server → Company settings: persists settings
- Application server → Agent roster: manages roster
- Application server → Business goals: records intent
- Application server → Projects: organizes work
- Application server → Tasks and approvals: tracks tasks
- Application server → Workflow pipelines: configures workflows
- Application server → Pipeline cases: tracks cases
- Application server → Agent run lifecycle: starts agent runs
- Agent run lifecycle → Agent adapters: dispatches runs
- Agent adapters → Agent runner: executes agent work
- Application server → Skills and training: manages training
- Application server → MCP and integrations: offers integrations
- Application server → Budgets and costs: enforces cost controls
- Application server → Activity and run history: records run history
- Application server → Workspace snapshots: stores snapshots
server/src/services/remote-workspace-snapshot-storage.ts - Application server → PostgreSQL state: reads and writes
- Setup and operations → Human user: configures instance