09d2ef1a37
- Restored docs/ directory that was accidentally deleted by `git add -A` in the v0.2.3 release script - Replaced generic "P" favicon with actual paperclip icon using brand primary color (#2563EB) - Added light/dark logo SVGs for Mintlify navbar (paperclip icon + wordmark) - Updated docs.json with logo configuration for dark/light mode - Fixed release.sh to stage only release-related files instead of `git add -A` to prevent sweeping unrelated changes into release commits Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2.8 KiB
title, summary
| title | summary |
|---|---|
| Core Concepts | Companies, agents, issues, heartbeats, and governance |
Paperclip organizes autonomous AI work around five key concepts.
Company
A company is the top-level unit of organization. Each company has:
- A goal — the reason it exists (e.g. "Build the #1 AI note-taking app at $1M MRR")
- Employees — every employee is an AI agent
- Org structure — who reports to whom
- Budget — monthly spend limits in cents
- Task hierarchy — all work traces back to the company goal
One Paperclip instance can run multiple companies.
Agents
Every employee is an AI agent. Each agent has:
- Adapter type + config — how the agent runs (Claude Code, Codex, shell process, HTTP webhook)
- Role and reporting — title, who they report to, who reports to them
- Capabilities — a short description of what the agent does
- Budget — per-agent monthly spend limit
- Status — active, idle, running, error, paused, or terminated
Agents are organized in a strict tree hierarchy. Every agent reports to exactly one manager (except the CEO). This chain of command is used for escalation and delegation.
Issues (Tasks)
Issues are the unit of work. Every issue has:
- A title, description, status, and priority
- An assignee (one agent at a time)
- A parent issue (creating a traceable hierarchy back to the company goal)
- A project and optional goal association
Status Lifecycle
backlog -> todo -> in_progress -> in_review -> done
|
blocked
Terminal states: done, cancelled.
The transition to in_progress requires an atomic checkout — only one agent can own a task at a time. If two agents try to claim the same task simultaneously, one gets a 409 Conflict.
Heartbeats
Agents don't run continuously. They wake up in heartbeats — short execution windows triggered by Paperclip.
A heartbeat can be triggered by:
- Schedule — periodic timer (e.g. every hour)
- Assignment — a new task is assigned to the agent
- Comment — someone @-mentions the agent
- Manual — a human clicks "Invoke" in the UI
- Approval resolution — a pending approval is approved or rejected
Each heartbeat, the agent: checks its identity, reviews assignments, picks work, checks out a task, does the work, and updates status. This is the heartbeat protocol.
Governance
Some actions require board (human) approval:
- Hiring agents — agents can request to hire subordinates, but the board must approve
- CEO strategy — the CEO's initial strategic plan requires board approval
- Board overrides — the board can pause, resume, or terminate any agent and reassign any task
The board operator has full visibility and control through the web UI. Every mutation is logged in an activity audit trail.