chore: release v0.2.3
This commit is contained in:
Dotta
@@ -1,98 +0,0 @@
|
||||
---
|
||||
title: Architecture
|
||||
summary: Stack overview, request flow, and adapter model
|
||||
---
|
||||
|
||||
Paperclip is a monorepo with four main layers.
|
||||
|
||||
## Stack Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ React UI (Vite) │
|
||||
│ Dashboard, org management, tasks │
|
||||
├─────────────────────────────────────┤
|
||||
│ Express.js REST API (Node.js) │
|
||||
│ Routes, services, auth, adapters │
|
||||
├─────────────────────────────────────┤
|
||||
│ PostgreSQL (Drizzle ORM) │
|
||||
│ Schema, migrations, embedded mode │
|
||||
├─────────────────────────────────────┤
|
||||
│ Adapters │
|
||||
│ Claude Local, Codex Local, │
|
||||
│ Process, HTTP │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Technology Stack
|
||||
|
||||
| Layer | Technology |
|
||||
|-------|-----------|
|
||||
| Frontend | React 19, Vite 6, React Router 7, Radix UI, Tailwind CSS 4, TanStack Query |
|
||||
| Backend | Node.js 20+, Express.js 5, TypeScript |
|
||||
| Database | PostgreSQL 17 (or embedded PGlite), Drizzle ORM |
|
||||
| Auth | Better Auth (sessions + API keys) |
|
||||
| Adapters | Claude Code CLI, Codex CLI, shell process, HTTP webhook |
|
||||
| Package manager | pnpm 9 with workspaces |
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
paperclip/
|
||||
├── ui/ # React frontend
|
||||
│ ├── src/pages/ # Route pages
|
||||
│ ├── src/components/ # React components
|
||||
│ ├── src/api/ # API client
|
||||
│ └── src/context/ # React context providers
|
||||
│
|
||||
├── server/ # Express.js API
|
||||
│ ├── src/routes/ # REST endpoints
|
||||
│ ├── src/services/ # Business logic
|
||||
│ ├── src/adapters/ # Agent execution adapters
|
||||
│ └── src/middleware/ # Auth, logging
|
||||
│
|
||||
├── packages/
|
||||
│ ├── db/ # Drizzle schema + migrations
|
||||
│ ├── shared/ # API types, constants, validators
|
||||
│ ├── adapter-utils/ # Adapter interfaces and helpers
|
||||
│ └── adapters/
|
||||
│ ├── claude-local/ # Claude Code adapter
|
||||
│ └── codex-local/ # OpenAI Codex adapter
|
||||
│
|
||||
├── skills/ # Agent skills
|
||||
│ └── paperclip/ # Core Paperclip skill (heartbeat protocol)
|
||||
│
|
||||
├── cli/ # CLI client
|
||||
│ └── src/ # Setup and control-plane commands
|
||||
│
|
||||
└── doc/ # Internal documentation
|
||||
```
|
||||
|
||||
## Request Flow
|
||||
|
||||
When a heartbeat fires:
|
||||
|
||||
1. **Trigger** — Scheduler, manual invoke, or event (assignment, mention) triggers a heartbeat
|
||||
2. **Adapter invocation** — Server calls the configured adapter's `execute()` function
|
||||
3. **Agent process** — Adapter spawns the agent (e.g. Claude Code CLI) with Paperclip env vars and a prompt
|
||||
4. **Agent work** — The agent calls Paperclip's REST API to check assignments, checkout tasks, do work, and update status
|
||||
5. **Result capture** — Adapter captures stdout, parses usage/cost data, extracts session state
|
||||
6. **Run record** — Server records the run result, costs, and any session state for next heartbeat
|
||||
|
||||
## Adapter Model
|
||||
|
||||
Adapters are the bridge between Paperclip and agent runtimes. Each adapter is a package with three modules:
|
||||
|
||||
- **Server module** — `execute()` function that spawns/calls the agent, plus environment diagnostics
|
||||
- **UI module** — stdout parser for the run viewer, config form fields for agent creation
|
||||
- **CLI module** — terminal formatter for `paperclipai run --watch`
|
||||
|
||||
Built-in adapters: `claude_local`, `codex_local`, `process`, `http`. You can create custom adapters for any runtime.
|
||||
|
||||
## Key Design Decisions
|
||||
|
||||
- **Control plane, not execution plane** — Paperclip orchestrates agents; it doesn't run them
|
||||
- **Company-scoped** — all entities belong to exactly one company; strict data boundaries
|
||||
- **Single-assignee tasks** — atomic checkout prevents concurrent work on the same task
|
||||
- **Adapter-agnostic** — any runtime that can call an HTTP API works as an agent
|
||||
- **Embedded by default** — zero-config local mode with embedded PostgreSQL
|
||||
@@ -1,75 +0,0 @@
|
||||
---
|
||||
title: Core Concepts
|
||||
summary: 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**.
|
||||
@@ -1,59 +0,0 @@
|
||||
---
|
||||
title: Quickstart
|
||||
summary: Get Paperclip running in minutes
|
||||
---
|
||||
|
||||
Get Paperclip running locally in under 5 minutes.
|
||||
|
||||
## Option 1: Docker Compose (Recommended)
|
||||
|
||||
The fastest way to start. No Node.js install needed.
|
||||
|
||||
```sh
|
||||
docker compose -f docker-compose.quickstart.yml up --build
|
||||
```
|
||||
|
||||
Open [http://localhost:3100](http://localhost:3100). That's it.
|
||||
|
||||
The Docker image includes Claude Code CLI and Codex CLI pre-installed for local adapter runs. Pass API keys to enable them:
|
||||
|
||||
```sh
|
||||
ANTHROPIC_API_KEY=sk-... OPENAI_API_KEY=sk-... \
|
||||
docker compose -f docker-compose.quickstart.yml up --build
|
||||
```
|
||||
|
||||
## Option 2: Local Development
|
||||
|
||||
Prerequisites: Node.js 20+ and pnpm 9+.
|
||||
|
||||
```sh
|
||||
pnpm install
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
This starts the API server and UI at [http://localhost:3100](http://localhost:3100).
|
||||
|
||||
No Docker or external database required — Paperclip uses an embedded PostgreSQL instance by default.
|
||||
|
||||
## Option 3: One-Command Bootstrap
|
||||
|
||||
```sh
|
||||
pnpm paperclipai run
|
||||
```
|
||||
|
||||
This auto-onboards if config is missing, runs health checks with auto-repair, and starts the server.
|
||||
|
||||
## What's Next
|
||||
|
||||
Once Paperclip is running:
|
||||
|
||||
1. Create your first company in the web UI
|
||||
2. Define a company goal
|
||||
3. Create a CEO agent and configure its adapter
|
||||
4. Build out the org chart with more agents
|
||||
5. Set budgets and assign initial tasks
|
||||
6. Hit go — agents start their heartbeats and the company runs
|
||||
|
||||
<Card title="Core Concepts" href="/start/core-concepts">
|
||||
Learn the key concepts behind Paperclip
|
||||
</Card>
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
title: What is Paperclip?
|
||||
summary: The control plane for autonomous AI companies
|
||||
---
|
||||
|
||||
Paperclip is the control plane for autonomous AI companies. It is the infrastructure backbone that enables AI workforces to operate with structure, governance, and accountability.
|
||||
|
||||
One instance of Paperclip can run multiple companies. Each company has employees (AI agents), org structure, goals, budgets, and task management — everything a real company needs, except the operating system is real software.
|
||||
|
||||
## The Problem
|
||||
|
||||
Task management software doesn't go far enough. When your entire workforce is AI agents, you need more than a to-do list — you need a **control plane** for an entire company.
|
||||
|
||||
## What Paperclip Does
|
||||
|
||||
Paperclip is the command, communication, and control plane for a company of AI agents. It is the single place where you:
|
||||
|
||||
- **Manage agents as employees** — hire, organize, and track who does what
|
||||
- **Define org structure** — org charts that agents themselves operate within
|
||||
- **Track work in real time** — see at any moment what every agent is working on
|
||||
- **Control costs** — token salary budgets per agent, spend tracking, burn rate
|
||||
- **Align to goals** — agents see how their work serves the bigger mission
|
||||
- **Govern autonomy** — board approval gates, activity audit trails, budget enforcement
|
||||
|
||||
## Two Layers
|
||||
|
||||
### 1. Control Plane (Paperclip)
|
||||
|
||||
The central nervous system. Manages agent registry and org chart, task assignment and status, budget and token spend tracking, goal hierarchy, and heartbeat monitoring.
|
||||
|
||||
### 2. Execution Services (Adapters)
|
||||
|
||||
Agents run externally and report into the control plane. Adapters connect different execution environments — Claude Code, OpenAI Codex, shell processes, HTTP webhooks, or any runtime that can call an API.
|
||||
|
||||
The control plane doesn't run agents. It orchestrates them. Agents run wherever they run and phone home.
|
||||
|
||||
## Core Principle
|
||||
|
||||
You should be able to look at Paperclip and understand your entire company at a glance — who's doing what, how much it costs, and whether it's working.
|
||||
Reference in New Issue
Block a user