fix: restore docs deleted in v0.2.3 release, add Paperclip branding
- 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>
This commit is contained in:
Dotta
57
docs/adapters/claude-local.md
Normal file
57
docs/adapters/claude-local.md
Normal file
@@ -0,0 +1,57 @@
|
||||
---
|
||||
title: Claude Local
|
||||
summary: Claude Code local adapter setup and configuration
|
||||
---
|
||||
|
||||
The `claude_local` adapter runs Anthropic's Claude Code CLI locally. It supports session persistence, skills injection, and structured output parsing.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Claude Code CLI installed (`claude` command available)
|
||||
- `ANTHROPIC_API_KEY` set in the environment or agent config
|
||||
|
||||
## Configuration Fields
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `cwd` | string | Yes | Working directory for the agent process (absolute path; created automatically if missing when permissions allow) |
|
||||
| `model` | string | No | Claude model to use (e.g. `claude-opus-4-6`) |
|
||||
| `promptTemplate` | string | No | Prompt used for all runs |
|
||||
| `env` | object | No | Environment variables (supports secret refs) |
|
||||
| `timeoutSec` | number | No | Process timeout (0 = no timeout) |
|
||||
| `graceSec` | number | No | Grace period before force-kill |
|
||||
| `maxTurnsPerRun` | number | No | Max agentic turns per heartbeat |
|
||||
| `dangerouslySkipPermissions` | boolean | No | Skip permission prompts (dev only) |
|
||||
|
||||
## Prompt Templates
|
||||
|
||||
Templates support `{{variable}}` substitution:
|
||||
|
||||
| Variable | Value |
|
||||
|----------|-------|
|
||||
| `{{agentId}}` | Agent's ID |
|
||||
| `{{companyId}}` | Company ID |
|
||||
| `{{runId}}` | Current run ID |
|
||||
| `{{agent.name}}` | Agent's name |
|
||||
| `{{company.name}}` | Company name |
|
||||
|
||||
## Session Persistence
|
||||
|
||||
The adapter persists Claude Code session IDs between heartbeats. On the next wake, it resumes the existing conversation so the agent retains full context.
|
||||
|
||||
Session resume is cwd-aware: if the agent's working directory changed since the last run, a fresh session starts instead.
|
||||
|
||||
If resume fails with an unknown session error, the adapter automatically retries with a fresh session.
|
||||
|
||||
## Skills Injection
|
||||
|
||||
The adapter creates a temporary directory with symlinks to Paperclip skills and passes it via `--add-dir`. This makes skills discoverable without polluting the agent's working directory.
|
||||
|
||||
## Environment Test
|
||||
|
||||
Use the "Test Environment" button in the UI to validate the adapter config. It checks:
|
||||
|
||||
- Claude CLI is installed and accessible
|
||||
- Working directory is absolute and available (auto-created if missing and permitted)
|
||||
- API key/auth mode hints (`ANTHROPIC_API_KEY` vs subscription login)
|
||||
- A live hello probe (`claude --print - --output-format stream-json --verbose` with prompt `Respond with hello.`) to verify CLI readiness
|
||||
40
docs/adapters/codex-local.md
Normal file
40
docs/adapters/codex-local.md
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Codex Local
|
||||
summary: OpenAI Codex local adapter setup and configuration
|
||||
---
|
||||
|
||||
The `codex_local` adapter runs OpenAI's Codex CLI locally. It supports session persistence via `previous_response_id` chaining and skills injection through the global Codex skills directory.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Codex CLI installed (`codex` command available)
|
||||
- `OPENAI_API_KEY` set in the environment or agent config
|
||||
|
||||
## Configuration Fields
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `cwd` | string | Yes | Working directory for the agent process (absolute path; created automatically if missing when permissions allow) |
|
||||
| `model` | string | No | Model to use |
|
||||
| `promptTemplate` | string | No | Prompt used for all runs |
|
||||
| `env` | object | No | Environment variables (supports secret refs) |
|
||||
| `timeoutSec` | number | No | Process timeout (0 = no timeout) |
|
||||
| `graceSec` | number | No | Grace period before force-kill |
|
||||
| `dangerouslyBypassApprovalsAndSandbox` | boolean | No | Skip safety checks (dev only) |
|
||||
|
||||
## Session Persistence
|
||||
|
||||
Codex uses `previous_response_id` for session continuity. The adapter serializes and restores this across heartbeats, allowing the agent to maintain conversation context.
|
||||
|
||||
## Skills Injection
|
||||
|
||||
The adapter symlinks Paperclip skills into the global Codex skills directory (`~/.codex/skills`). Existing user skills are not overwritten.
|
||||
|
||||
## Environment Test
|
||||
|
||||
The environment test checks:
|
||||
|
||||
- Codex CLI is installed and accessible
|
||||
- Working directory is absolute and available (auto-created if missing and permitted)
|
||||
- Authentication signal (`OPENAI_API_KEY` presence)
|
||||
- A live hello probe (`codex exec --json -` with prompt `Respond with hello.`) to verify the CLI can actually run
|
||||
103
docs/adapters/creating-an-adapter.md
Normal file
103
docs/adapters/creating-an-adapter.md
Normal file
@@ -0,0 +1,103 @@
|
||||
---
|
||||
title: Creating an Adapter
|
||||
summary: Guide to building a custom adapter
|
||||
---
|
||||
|
||||
Build a custom adapter to connect Paperclip to any agent runtime.
|
||||
|
||||
## Package Structure
|
||||
|
||||
```
|
||||
packages/adapters/<name>/
|
||||
package.json
|
||||
tsconfig.json
|
||||
src/
|
||||
index.ts # Shared metadata
|
||||
server/
|
||||
index.ts # Server exports
|
||||
execute.ts # Core execution logic
|
||||
parse.ts # Output parsing
|
||||
test.ts # Environment diagnostics
|
||||
ui/
|
||||
index.ts # UI exports
|
||||
parse-stdout.ts # Transcript parser
|
||||
build-config.ts # Config builder
|
||||
cli/
|
||||
index.ts # CLI exports
|
||||
format-event.ts # Terminal formatter
|
||||
```
|
||||
|
||||
## Step 1: Root Metadata
|
||||
|
||||
`src/index.ts` is imported by all three consumers. Keep it dependency-free.
|
||||
|
||||
```ts
|
||||
export const type = "my_agent"; // snake_case, globally unique
|
||||
export const label = "My Agent (local)";
|
||||
export const models = [
|
||||
{ id: "model-a", label: "Model A" },
|
||||
];
|
||||
export const agentConfigurationDoc = `# my_agent configuration
|
||||
Use when: ...
|
||||
Don't use when: ...
|
||||
Core fields: ...
|
||||
`;
|
||||
```
|
||||
|
||||
## Step 2: Server Execute
|
||||
|
||||
`src/server/execute.ts` is the core. It receives an `AdapterExecutionContext` and returns an `AdapterExecutionResult`.
|
||||
|
||||
Key responsibilities:
|
||||
|
||||
1. Read config using safe helpers (`asString`, `asNumber`, etc.)
|
||||
2. Build environment with `buildPaperclipEnv(agent)` plus context vars
|
||||
3. Resolve session state from `runtime.sessionParams`
|
||||
4. Render prompt with `renderTemplate(template, data)`
|
||||
5. Spawn the process with `runChildProcess()` or call via `fetch()`
|
||||
6. Parse output for usage, costs, session state, errors
|
||||
7. Handle unknown session errors (retry fresh, set `clearSession: true`)
|
||||
|
||||
## Step 3: Environment Test
|
||||
|
||||
`src/server/test.ts` validates the adapter config before running.
|
||||
|
||||
Return structured diagnostics:
|
||||
|
||||
- `error` for invalid/unusable setup
|
||||
- `warn` for non-blocking issues
|
||||
- `info` for successful checks
|
||||
|
||||
## Step 4: UI Module
|
||||
|
||||
- `parse-stdout.ts` — converts stdout lines to `TranscriptEntry[]` for the run viewer
|
||||
- `build-config.ts` — converts form values to `adapterConfig` JSON
|
||||
- Config fields React component in `ui/src/adapters/<name>/config-fields.tsx`
|
||||
|
||||
## Step 5: CLI Module
|
||||
|
||||
`format-event.ts` — pretty-prints stdout for `paperclipai run --watch` using `picocolors`.
|
||||
|
||||
## Step 6: Register
|
||||
|
||||
Add the adapter to all three registries:
|
||||
|
||||
1. `server/src/adapters/registry.ts`
|
||||
2. `ui/src/adapters/registry.ts`
|
||||
3. `cli/src/adapters/registry.ts`
|
||||
|
||||
## Skills Injection
|
||||
|
||||
Make Paperclip skills discoverable to your agent runtime without writing to the agent's working directory:
|
||||
|
||||
1. **Best: tmpdir + flag** — create tmpdir, symlink skills, pass via CLI flag, clean up after
|
||||
2. **Acceptable: global config dir** — symlink to the runtime's global plugins directory
|
||||
3. **Acceptable: env var** — point a skills path env var at the repo's `skills/` directory
|
||||
4. **Last resort: prompt injection** — include skill content in the prompt template
|
||||
|
||||
## Security
|
||||
|
||||
- Treat agent output as untrusted (parse defensively, never execute)
|
||||
- Inject secrets via environment variables, not prompts
|
||||
- Configure network access controls if the runtime supports them
|
||||
- Always enforce timeout and grace period
|
||||
51
docs/adapters/http.md
Normal file
51
docs/adapters/http.md
Normal file
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title: HTTP Adapter
|
||||
summary: HTTP webhook adapter
|
||||
---
|
||||
|
||||
The `http` adapter sends a webhook request to an external agent service. The agent runs externally and Paperclip just triggers it.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Agent runs as an external service (cloud function, dedicated server)
|
||||
- Fire-and-forget invocation model
|
||||
- Integration with third-party agent platforms
|
||||
|
||||
## When Not to Use
|
||||
|
||||
- If the agent runs locally on the same machine (use `process`, `claude_local`, or `codex_local`)
|
||||
- If you need stdout capture and real-time run viewing
|
||||
|
||||
## Configuration
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `url` | string | Yes | Webhook URL to POST to |
|
||||
| `headers` | object | No | Additional HTTP headers |
|
||||
| `timeoutSec` | number | No | Request timeout |
|
||||
|
||||
## How It Works
|
||||
|
||||
1. Paperclip sends a POST request to the configured URL
|
||||
2. The request body includes the execution context (agent ID, task info, wake reason)
|
||||
3. The external agent processes the request and calls back to the Paperclip API
|
||||
4. Response from the webhook is captured as the run result
|
||||
|
||||
## Request Body
|
||||
|
||||
The webhook receives a JSON payload with:
|
||||
|
||||
```json
|
||||
{
|
||||
"runId": "...",
|
||||
"agentId": "...",
|
||||
"companyId": "...",
|
||||
"context": {
|
||||
"taskId": "...",
|
||||
"wakeReason": "...",
|
||||
"commentId": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The external agent uses `PAPERCLIP_API_URL` and an API key to call back to Paperclip.
|
||||
58
docs/adapters/overview.md
Normal file
58
docs/adapters/overview.md
Normal file
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: Adapters Overview
|
||||
summary: What adapters are and how they connect agents to Paperclip
|
||||
---
|
||||
|
||||
Adapters are the bridge between Paperclip's orchestration layer and agent runtimes. Each adapter knows how to invoke a specific type of AI agent and capture its results.
|
||||
|
||||
## How Adapters Work
|
||||
|
||||
When a heartbeat fires, Paperclip:
|
||||
|
||||
1. Looks up the agent's `adapterType` and `adapterConfig`
|
||||
2. Calls the adapter's `execute()` function with the execution context
|
||||
3. The adapter spawns or calls the agent runtime
|
||||
4. The adapter captures stdout, parses usage/cost data, and returns a structured result
|
||||
|
||||
## Built-in Adapters
|
||||
|
||||
| Adapter | Type Key | Description |
|
||||
|---------|----------|-------------|
|
||||
| [Claude Local](/adapters/claude-local) | `claude_local` | Runs Claude Code CLI locally |
|
||||
| [Codex Local](/adapters/codex-local) | `codex_local` | Runs OpenAI Codex CLI locally |
|
||||
| [Process](/adapters/process) | `process` | Executes arbitrary shell commands |
|
||||
| [HTTP](/adapters/http) | `http` | Sends webhooks to external agents |
|
||||
|
||||
## Adapter Architecture
|
||||
|
||||
Each adapter is a package with three modules:
|
||||
|
||||
```
|
||||
packages/adapters/<name>/
|
||||
src/
|
||||
index.ts # Shared metadata (type, label, models)
|
||||
server/
|
||||
execute.ts # Core execution logic
|
||||
parse.ts # Output parsing
|
||||
test.ts # Environment diagnostics
|
||||
ui/
|
||||
parse-stdout.ts # Stdout -> transcript entries for run viewer
|
||||
build-config.ts # Form values -> adapterConfig JSON
|
||||
cli/
|
||||
format-event.ts # Terminal output for `paperclipai run --watch`
|
||||
```
|
||||
|
||||
Three registries consume these modules:
|
||||
|
||||
| Registry | What it does |
|
||||
|----------|-------------|
|
||||
| **Server** | Executes agents, captures results |
|
||||
| **UI** | Renders run transcripts, provides config forms |
|
||||
| **CLI** | Formats terminal output for live watching |
|
||||
|
||||
## Choosing an Adapter
|
||||
|
||||
- **Need a coding agent?** Use `claude_local` or `codex_local`
|
||||
- **Need to run a script or command?** Use `process`
|
||||
- **Need to call an external service?** Use `http`
|
||||
- **Need something custom?** [Create your own adapter](/adapters/creating-an-adapter)
|
||||
50
docs/adapters/process.md
Normal file
50
docs/adapters/process.md
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: Process Adapter
|
||||
summary: Generic shell process adapter
|
||||
---
|
||||
|
||||
The `process` adapter executes arbitrary shell commands. Use it for simple scripts, one-shot tasks, or agents built on custom frameworks.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Running a Python script that calls the Paperclip API
|
||||
- Executing a custom agent loop
|
||||
- Any runtime that can be invoked as a shell command
|
||||
|
||||
## When Not to Use
|
||||
|
||||
- If you need session persistence across runs (use `claude_local` or `codex_local`)
|
||||
- If the agent needs conversational context between heartbeats
|
||||
|
||||
## Configuration
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `command` | string | Yes | Shell command to execute |
|
||||
| `cwd` | string | No | Working directory |
|
||||
| `env` | object | No | Environment variables |
|
||||
| `timeoutSec` | number | No | Process timeout |
|
||||
|
||||
## How It Works
|
||||
|
||||
1. Paperclip spawns the configured command as a child process
|
||||
2. Standard Paperclip environment variables are injected (`PAPERCLIP_AGENT_ID`, `PAPERCLIP_API_KEY`, etc.)
|
||||
3. The process runs to completion
|
||||
4. Exit code determines success/failure
|
||||
|
||||
## Example
|
||||
|
||||
An agent that runs a Python script:
|
||||
|
||||
```json
|
||||
{
|
||||
"adapterType": "process",
|
||||
"adapterConfig": {
|
||||
"command": "python3 /path/to/agent.py",
|
||||
"cwd": "/path/to/workspace",
|
||||
"timeoutSec": 300
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The script can use the injected environment variables to authenticate with the Paperclip API and perform work.
|
||||
175
docs/agents-runtime.md
Normal file
175
docs/agents-runtime.md
Normal file
@@ -0,0 +1,175 @@
|
||||
# Agent Runtime Guide
|
||||
|
||||
Status: User-facing guide
|
||||
Last updated: 2026-02-17
|
||||
Audience: Operators setting up and running agents in Paperclip
|
||||
|
||||
## 1. What this system does
|
||||
|
||||
Agents in Paperclip do not run continuously.
|
||||
They run in **heartbeats**: short execution windows triggered by a wakeup.
|
||||
|
||||
Each heartbeat:
|
||||
|
||||
1. Starts the configured agent adapter (for example, Claude CLI or Codex CLI)
|
||||
2. Gives it the current prompt/context
|
||||
3. Lets it work until it exits, times out, or is cancelled
|
||||
4. Stores results (status, token usage, errors, logs)
|
||||
5. Updates the UI live
|
||||
|
||||
## 2. When an agent wakes up
|
||||
|
||||
An agent can be woken up in four ways:
|
||||
|
||||
- `timer`: scheduled interval (for example every 5 minutes)
|
||||
- `assignment`: when work is assigned/checked out to that agent
|
||||
- `on_demand`: manual wakeup (button/API)
|
||||
- `automation`: system-triggered wakeup for future automations
|
||||
|
||||
If an agent is already running, new wakeups are merged (coalesced) instead of launching duplicate runs.
|
||||
|
||||
## 3. What to configure per agent
|
||||
|
||||
## 3.1 Adapter choice
|
||||
|
||||
Common choices:
|
||||
|
||||
- `claude_local`: runs your local `claude` CLI
|
||||
- `codex_local`: runs your local `codex` CLI
|
||||
- `process`: generic shell command adapter
|
||||
- `http`: calls an external HTTP endpoint
|
||||
|
||||
For `claude_local` and `codex_local`, Paperclip assumes the CLI is already installed and authenticated on the host machine.
|
||||
|
||||
## 3.2 Runtime behavior
|
||||
|
||||
In agent runtime settings, configure heartbeat policy:
|
||||
|
||||
- `enabled`: allow scheduled heartbeats
|
||||
- `intervalSec`: timer interval (0 = disabled)
|
||||
- `wakeOnAssignment`: wake when assigned work
|
||||
- `wakeOnOnDemand`: allow ping-style on-demand wakeups
|
||||
- `wakeOnAutomation`: allow system automation wakeups
|
||||
|
||||
## 3.3 Working directory and execution limits
|
||||
|
||||
For local adapters, set:
|
||||
|
||||
- `cwd` (working directory)
|
||||
- `timeoutSec` (max runtime per heartbeat)
|
||||
- `graceSec` (time before force-kill after timeout/cancel)
|
||||
- optional env vars and extra CLI args
|
||||
- use **Test environment** in agent configuration to run adapter-specific diagnostics before saving
|
||||
|
||||
## 3.4 Prompt templates
|
||||
|
||||
You can set:
|
||||
|
||||
- `promptTemplate`: used for every run (first run and resumed sessions)
|
||||
|
||||
Templates support variables like `{{agent.id}}`, `{{agent.name}}`, and run context values.
|
||||
|
||||
## 4. Session resume behavior
|
||||
|
||||
Paperclip stores session IDs for resumable adapters.
|
||||
|
||||
- Next heartbeat reuses the saved session automatically.
|
||||
- This gives continuity across heartbeats.
|
||||
- You can reset a session if context gets stale or confused.
|
||||
|
||||
Use session reset when:
|
||||
|
||||
- you significantly changed prompt strategy
|
||||
- the agent is stuck in a bad loop
|
||||
- you want a clean restart
|
||||
|
||||
## 5. Logs, status, and run history
|
||||
|
||||
For each heartbeat run you get:
|
||||
|
||||
- run status (`queued`, `running`, `succeeded`, `failed`, `timed_out`, `cancelled`)
|
||||
- error text and stderr/stdout excerpts
|
||||
- token usage/cost when available from the adapter
|
||||
- full logs (stored outside core run rows, optimized for large output)
|
||||
|
||||
In local/dev setups, full logs are stored on disk under the configured run-log path.
|
||||
|
||||
## 6. Live updates in the UI
|
||||
|
||||
Paperclip pushes runtime/activity updates to the browser in real time.
|
||||
|
||||
You should see live changes for:
|
||||
|
||||
- agent status
|
||||
- heartbeat run status
|
||||
- task/activity updates caused by agent work
|
||||
- dashboard/cost/activity panels as relevant
|
||||
|
||||
If the connection drops, the UI reconnects automatically.
|
||||
|
||||
## 7. Common operating patterns
|
||||
|
||||
## 7.1 Simple autonomous loop
|
||||
|
||||
1. Enable timer wakeups (for example every 300s)
|
||||
2. Keep assignment wakeups on
|
||||
3. Use a focused prompt template
|
||||
4. Watch run logs and adjust prompt/config over time
|
||||
|
||||
## 7.2 Event-driven loop (less constant polling)
|
||||
|
||||
1. Disable timer or set a long interval
|
||||
2. Keep wake-on-assignment enabled
|
||||
3. Use on-demand wakeups for manual nudges
|
||||
|
||||
## 7.3 Safety-first loop
|
||||
|
||||
1. Short timeout
|
||||
2. Conservative prompt
|
||||
3. Monitor errors + cancel quickly when needed
|
||||
4. Reset sessions when drift appears
|
||||
|
||||
## 8. Troubleshooting
|
||||
|
||||
If runs fail repeatedly:
|
||||
|
||||
1. Check adapter command availability (`claude`/`codex` installed and logged in).
|
||||
2. Verify `cwd` exists and is accessible.
|
||||
3. Inspect run error + stderr excerpt, then full log.
|
||||
4. Confirm timeout is not too low.
|
||||
5. Reset session and retry.
|
||||
6. Pause agent if it is causing repeated bad updates.
|
||||
|
||||
Typical failure causes:
|
||||
|
||||
- CLI not installed/authenticated
|
||||
- bad working directory
|
||||
- malformed adapter args/env
|
||||
- prompt too broad or missing constraints
|
||||
- process timeout
|
||||
|
||||
Claude-specific note:
|
||||
|
||||
- If `ANTHROPIC_API_KEY` is set in adapter env or host environment, Claude uses API-key auth instead of subscription login. Paperclip surfaces this as a warning in environment tests, not a hard error.
|
||||
|
||||
## 9. Security and risk notes
|
||||
|
||||
Local CLI adapters run unsandboxed on the host machine.
|
||||
|
||||
That means:
|
||||
|
||||
- prompt instructions matter
|
||||
- configured credentials/env vars are sensitive
|
||||
- working directory permissions matter
|
||||
|
||||
Start with least privilege where possible, and avoid exposing secrets in broad reusable prompts unless intentionally required.
|
||||
|
||||
## 10. Minimal setup checklist
|
||||
|
||||
1. Choose adapter (`claude_local` or `codex_local`).
|
||||
2. Set `cwd` to the target workspace.
|
||||
3. Add bootstrap + normal prompt templates.
|
||||
4. Configure heartbeat policy (timer and/or assignment wakeups).
|
||||
5. Trigger a manual wakeup.
|
||||
6. Confirm run succeeds and session/token usage is recorded.
|
||||
7. Watch live updates and iterate prompt/config.
|
||||
46
docs/api/activity.md
Normal file
46
docs/api/activity.md
Normal file
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: Activity
|
||||
summary: Activity log queries
|
||||
---
|
||||
|
||||
Query the audit trail of all mutations across the company.
|
||||
|
||||
## List Activity
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/activity
|
||||
```
|
||||
|
||||
Query parameters:
|
||||
|
||||
| Param | Description |
|
||||
|-------|-------------|
|
||||
| `agentId` | Filter by actor agent |
|
||||
| `entityType` | Filter by entity type (`issue`, `agent`, `approval`) |
|
||||
| `entityId` | Filter by specific entity |
|
||||
|
||||
## Activity Record
|
||||
|
||||
Each entry includes:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `actor` | Agent or user who performed the action |
|
||||
| `action` | What was done (created, updated, commented, etc.) |
|
||||
| `entityType` | What type of entity was affected |
|
||||
| `entityId` | ID of the affected entity |
|
||||
| `details` | Specifics of the change |
|
||||
| `createdAt` | When the action occurred |
|
||||
|
||||
## What Gets Logged
|
||||
|
||||
All mutations are recorded:
|
||||
|
||||
- Issue creation, updates, status transitions, assignments
|
||||
- Agent creation, configuration changes, pausing, resuming, termination
|
||||
- Approval creation, approval/rejection decisions
|
||||
- Comment creation
|
||||
- Budget changes
|
||||
- Company configuration changes
|
||||
|
||||
The activity log is append-only and immutable.
|
||||
133
docs/api/agents.md
Normal file
133
docs/api/agents.md
Normal file
@@ -0,0 +1,133 @@
|
||||
---
|
||||
title: Agents
|
||||
summary: Agent lifecycle, configuration, keys, and heartbeat invocation
|
||||
---
|
||||
|
||||
Manage AI agents (employees) within a company.
|
||||
|
||||
## List Agents
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/agents
|
||||
```
|
||||
|
||||
Returns all agents in the company.
|
||||
|
||||
## Get Agent
|
||||
|
||||
```
|
||||
GET /api/agents/{agentId}
|
||||
```
|
||||
|
||||
Returns agent details including chain of command.
|
||||
|
||||
## Get Current Agent
|
||||
|
||||
```
|
||||
GET /api/agents/me
|
||||
```
|
||||
|
||||
Returns the agent record for the currently authenticated agent.
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "agent-42",
|
||||
"name": "BackendEngineer",
|
||||
"role": "engineer",
|
||||
"title": "Senior Backend Engineer",
|
||||
"companyId": "company-1",
|
||||
"reportsTo": "mgr-1",
|
||||
"capabilities": "Node.js, PostgreSQL, API design",
|
||||
"status": "running",
|
||||
"budgetMonthlyCents": 5000,
|
||||
"spentMonthlyCents": 1200,
|
||||
"chainOfCommand": [
|
||||
{ "id": "mgr-1", "name": "EngineeringLead", "role": "manager" },
|
||||
{ "id": "ceo-1", "name": "CEO", "role": "ceo" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Create Agent
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/agents
|
||||
{
|
||||
"name": "Engineer",
|
||||
"role": "engineer",
|
||||
"title": "Software Engineer",
|
||||
"reportsTo": "{managerAgentId}",
|
||||
"capabilities": "Full-stack development",
|
||||
"adapterType": "claude_local",
|
||||
"adapterConfig": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
## Update Agent
|
||||
|
||||
```
|
||||
PATCH /api/agents/{agentId}
|
||||
{
|
||||
"adapterConfig": { ... },
|
||||
"budgetMonthlyCents": 10000
|
||||
}
|
||||
```
|
||||
|
||||
## Pause Agent
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/pause
|
||||
```
|
||||
|
||||
Temporarily stops heartbeats for the agent.
|
||||
|
||||
## Resume Agent
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/resume
|
||||
```
|
||||
|
||||
Resumes heartbeats for a paused agent.
|
||||
|
||||
## Terminate Agent
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/terminate
|
||||
```
|
||||
|
||||
Permanently deactivates the agent. **Irreversible.**
|
||||
|
||||
## Create API Key
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/keys
|
||||
```
|
||||
|
||||
Returns a long-lived API key for the agent. Store it securely — the full value is only shown once.
|
||||
|
||||
## Invoke Heartbeat
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/heartbeat/invoke
|
||||
```
|
||||
|
||||
Manually triggers a heartbeat for the agent.
|
||||
|
||||
## Org Chart
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/org
|
||||
```
|
||||
|
||||
Returns the full organizational tree for the company.
|
||||
|
||||
## Config Revisions
|
||||
|
||||
```
|
||||
GET /api/agents/{agentId}/config-revisions
|
||||
POST /api/agents/{agentId}/config-revisions/{revisionId}/rollback
|
||||
```
|
||||
|
||||
View and roll back agent configuration changes.
|
||||
104
docs/api/approvals.md
Normal file
104
docs/api/approvals.md
Normal file
@@ -0,0 +1,104 @@
|
||||
---
|
||||
title: Approvals
|
||||
summary: Approval workflow endpoints
|
||||
---
|
||||
|
||||
Approvals gate certain actions (agent hiring, CEO strategy) behind board review.
|
||||
|
||||
## List Approvals
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/approvals
|
||||
```
|
||||
|
||||
Query parameters:
|
||||
|
||||
| Param | Description |
|
||||
|-------|-------------|
|
||||
| `status` | Filter by status (e.g. `pending`) |
|
||||
|
||||
## Get Approval
|
||||
|
||||
```
|
||||
GET /api/approvals/{approvalId}
|
||||
```
|
||||
|
||||
Returns approval details including type, status, payload, and decision notes.
|
||||
|
||||
## Create Approval Request
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/approvals
|
||||
{
|
||||
"type": "approve_ceo_strategy",
|
||||
"requestedByAgentId": "{agentId}",
|
||||
"payload": { "plan": "Strategic breakdown..." }
|
||||
}
|
||||
```
|
||||
|
||||
## Create Hire Request
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/agent-hires
|
||||
{
|
||||
"name": "Marketing Analyst",
|
||||
"role": "researcher",
|
||||
"reportsTo": "{managerAgentId}",
|
||||
"capabilities": "Market research",
|
||||
"budgetMonthlyCents": 5000
|
||||
}
|
||||
```
|
||||
|
||||
Creates a draft agent and a linked `hire_agent` approval.
|
||||
|
||||
## Approve
|
||||
|
||||
```
|
||||
POST /api/approvals/{approvalId}/approve
|
||||
{ "decisionNote": "Approved. Good hire." }
|
||||
```
|
||||
|
||||
## Reject
|
||||
|
||||
```
|
||||
POST /api/approvals/{approvalId}/reject
|
||||
{ "decisionNote": "Budget too high for this role." }
|
||||
```
|
||||
|
||||
## Request Revision
|
||||
|
||||
```
|
||||
POST /api/approvals/{approvalId}/request-revision
|
||||
{ "decisionNote": "Please reduce the budget and clarify capabilities." }
|
||||
```
|
||||
|
||||
## Resubmit
|
||||
|
||||
```
|
||||
POST /api/approvals/{approvalId}/resubmit
|
||||
{ "payload": { "updated": "config..." } }
|
||||
```
|
||||
|
||||
## Linked Issues
|
||||
|
||||
```
|
||||
GET /api/approvals/{approvalId}/issues
|
||||
```
|
||||
|
||||
Returns issues linked to this approval.
|
||||
|
||||
## Approval Comments
|
||||
|
||||
```
|
||||
GET /api/approvals/{approvalId}/comments
|
||||
POST /api/approvals/{approvalId}/comments
|
||||
{ "body": "Discussion comment..." }
|
||||
```
|
||||
|
||||
## Approval Lifecycle
|
||||
|
||||
```
|
||||
pending -> approved
|
||||
-> rejected
|
||||
-> revision_requested -> resubmitted -> pending
|
||||
```
|
||||
56
docs/api/authentication.md
Normal file
56
docs/api/authentication.md
Normal file
@@ -0,0 +1,56 @@
|
||||
---
|
||||
title: Authentication
|
||||
summary: API keys, JWTs, and auth modes
|
||||
---
|
||||
|
||||
Paperclip supports multiple authentication methods depending on the deployment mode and caller type.
|
||||
|
||||
## Agent Authentication
|
||||
|
||||
### Run JWTs (Recommended for agents)
|
||||
|
||||
During heartbeats, agents receive a short-lived JWT via the `PAPERCLIP_API_KEY` environment variable. Use it in the Authorization header:
|
||||
|
||||
```
|
||||
Authorization: Bearer <PAPERCLIP_API_KEY>
|
||||
```
|
||||
|
||||
This JWT is scoped to the agent and the current run.
|
||||
|
||||
### Agent API Keys
|
||||
|
||||
Long-lived API keys can be created for agents that need persistent access:
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/keys
|
||||
```
|
||||
|
||||
Returns a key that should be stored securely. The key is hashed at rest — you can only see the full value at creation time.
|
||||
|
||||
### Agent Identity
|
||||
|
||||
Agents can verify their own identity:
|
||||
|
||||
```
|
||||
GET /api/agents/me
|
||||
```
|
||||
|
||||
Returns the agent record including ID, company, role, chain of command, and budget.
|
||||
|
||||
## Board Operator Authentication
|
||||
|
||||
### Local Trusted Mode
|
||||
|
||||
No authentication required. All requests are treated as the local board operator.
|
||||
|
||||
### Authenticated Mode
|
||||
|
||||
Board operators authenticate via Better Auth sessions (cookie-based). The web UI handles login/logout flows automatically.
|
||||
|
||||
## Company Scoping
|
||||
|
||||
All entities belong to a company. The API enforces company boundaries:
|
||||
|
||||
- Agents can only access entities in their own company
|
||||
- Board operators can access all companies they're members of
|
||||
- Cross-company access is denied with `403`
|
||||
63
docs/api/companies.md
Normal file
63
docs/api/companies.md
Normal file
@@ -0,0 +1,63 @@
|
||||
---
|
||||
title: Companies
|
||||
summary: Company CRUD endpoints
|
||||
---
|
||||
|
||||
Manage companies within your Paperclip instance.
|
||||
|
||||
## List Companies
|
||||
|
||||
```
|
||||
GET /api/companies
|
||||
```
|
||||
|
||||
Returns all companies the current user/agent has access to.
|
||||
|
||||
## Get Company
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}
|
||||
```
|
||||
|
||||
Returns company details including name, description, budget, and status.
|
||||
|
||||
## Create Company
|
||||
|
||||
```
|
||||
POST /api/companies
|
||||
{
|
||||
"name": "My AI Company",
|
||||
"description": "An autonomous marketing agency"
|
||||
}
|
||||
```
|
||||
|
||||
## Update Company
|
||||
|
||||
```
|
||||
PATCH /api/companies/{companyId}
|
||||
{
|
||||
"name": "Updated Name",
|
||||
"description": "Updated description",
|
||||
"budgetMonthlyCents": 100000
|
||||
}
|
||||
```
|
||||
|
||||
## Archive Company
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/archive
|
||||
```
|
||||
|
||||
Archives a company. Archived companies are hidden from default listings.
|
||||
|
||||
## Company Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | string | Unique identifier |
|
||||
| `name` | string | Company name |
|
||||
| `description` | string | Company description |
|
||||
| `status` | string | `active`, `paused`, `archived` |
|
||||
| `budgetMonthlyCents` | number | Monthly budget limit |
|
||||
| `createdAt` | string | ISO timestamp |
|
||||
| `updatedAt` | string | ISO timestamp |
|
||||
71
docs/api/costs.md
Normal file
71
docs/api/costs.md
Normal file
@@ -0,0 +1,71 @@
|
||||
---
|
||||
title: Costs
|
||||
summary: Cost events, summaries, and budget management
|
||||
---
|
||||
|
||||
Track token usage and spending across agents, projects, and the company.
|
||||
|
||||
## Report Cost Event
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/cost-events
|
||||
{
|
||||
"agentId": "{agentId}",
|
||||
"provider": "anthropic",
|
||||
"model": "claude-sonnet-4-20250514",
|
||||
"inputTokens": 15000,
|
||||
"outputTokens": 3000,
|
||||
"costCents": 12
|
||||
}
|
||||
```
|
||||
|
||||
Typically reported automatically by adapters after each heartbeat.
|
||||
|
||||
## Company Cost Summary
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/costs/summary
|
||||
```
|
||||
|
||||
Returns total spend, budget, and utilization for the current month.
|
||||
|
||||
## Costs by Agent
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/costs/by-agent
|
||||
```
|
||||
|
||||
Returns per-agent cost breakdown for the current month.
|
||||
|
||||
## Costs by Project
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/costs/by-project
|
||||
```
|
||||
|
||||
Returns per-project cost breakdown for the current month.
|
||||
|
||||
## Budget Management
|
||||
|
||||
### Set Company Budget
|
||||
|
||||
```
|
||||
PATCH /api/companies/{companyId}
|
||||
{ "budgetMonthlyCents": 100000 }
|
||||
```
|
||||
|
||||
### Set Agent Budget
|
||||
|
||||
```
|
||||
PATCH /api/agents/{agentId}
|
||||
{ "budgetMonthlyCents": 5000 }
|
||||
```
|
||||
|
||||
## Budget Enforcement
|
||||
|
||||
| Threshold | Effect |
|
||||
|-----------|--------|
|
||||
| 80% | Soft alert — agent should focus on critical tasks |
|
||||
| 100% | Hard stop — agent is auto-paused |
|
||||
|
||||
Budget windows reset on the first of each month (UTC).
|
||||
28
docs/api/dashboard.md
Normal file
28
docs/api/dashboard.md
Normal file
@@ -0,0 +1,28 @@
|
||||
---
|
||||
title: Dashboard
|
||||
summary: Dashboard metrics endpoint
|
||||
---
|
||||
|
||||
Get a health summary for a company in a single call.
|
||||
|
||||
## Get Dashboard
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/dashboard
|
||||
```
|
||||
|
||||
## Response
|
||||
|
||||
Returns a summary including:
|
||||
|
||||
- **Agent counts** by status (active, idle, running, error, paused)
|
||||
- **Task counts** by status (backlog, todo, in_progress, blocked, done)
|
||||
- **Stale tasks** — tasks in progress with no recent activity
|
||||
- **Cost summary** — current month spend vs budget
|
||||
- **Recent activity** — latest mutations
|
||||
|
||||
## Use Cases
|
||||
|
||||
- Board operators: quick health check from the web UI
|
||||
- CEO agents: situational awareness at the start of each heartbeat
|
||||
- Manager agents: check team status and identify blockers
|
||||
121
docs/api/goals-and-projects.md
Normal file
121
docs/api/goals-and-projects.md
Normal file
@@ -0,0 +1,121 @@
|
||||
---
|
||||
title: Goals and Projects
|
||||
summary: Goal hierarchy and project management
|
||||
---
|
||||
|
||||
Goals define the "why" and projects define the "what" for organizing work.
|
||||
|
||||
## Goals
|
||||
|
||||
Goals form a hierarchy: company goals break down into team goals, which break down into agent-level goals.
|
||||
|
||||
### List Goals
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/goals
|
||||
```
|
||||
|
||||
### Get Goal
|
||||
|
||||
```
|
||||
GET /api/goals/{goalId}
|
||||
```
|
||||
|
||||
### Create Goal
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/goals
|
||||
{
|
||||
"title": "Launch MVP by Q1",
|
||||
"description": "Ship minimum viable product",
|
||||
"level": "company",
|
||||
"status": "active"
|
||||
}
|
||||
```
|
||||
|
||||
### Update Goal
|
||||
|
||||
```
|
||||
PATCH /api/goals/{goalId}
|
||||
{
|
||||
"status": "completed",
|
||||
"description": "Updated description"
|
||||
}
|
||||
```
|
||||
|
||||
## Projects
|
||||
|
||||
Projects group related issues toward a deliverable. They can be linked to goals and have workspaces (repository/directory configurations).
|
||||
|
||||
### List Projects
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/projects
|
||||
```
|
||||
|
||||
### Get Project
|
||||
|
||||
```
|
||||
GET /api/projects/{projectId}
|
||||
```
|
||||
|
||||
Returns project details including workspaces.
|
||||
|
||||
### Create Project
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/projects
|
||||
{
|
||||
"name": "Auth System",
|
||||
"description": "End-to-end authentication",
|
||||
"goalIds": ["{goalId}"],
|
||||
"status": "planned",
|
||||
"workspace": {
|
||||
"name": "auth-repo",
|
||||
"cwd": "/path/to/workspace",
|
||||
"repoUrl": "https://github.com/org/repo",
|
||||
"repoRef": "main",
|
||||
"isPrimary": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `workspace` is optional. If present, the project is created and seeded with that workspace.
|
||||
- A workspace must include at least one of `cwd` or `repoUrl`.
|
||||
- For repo-only projects, omit `cwd` and provide `repoUrl`.
|
||||
|
||||
### Update Project
|
||||
|
||||
```
|
||||
PATCH /api/projects/{projectId}
|
||||
{
|
||||
"status": "in_progress"
|
||||
}
|
||||
```
|
||||
|
||||
## Project Workspaces
|
||||
|
||||
Workspaces link a project to a repository and directory:
|
||||
|
||||
```
|
||||
POST /api/projects/{projectId}/workspaces
|
||||
{
|
||||
"name": "auth-repo",
|
||||
"cwd": "/path/to/workspace",
|
||||
"repoUrl": "https://github.com/org/repo",
|
||||
"repoRef": "main",
|
||||
"isPrimary": true
|
||||
}
|
||||
```
|
||||
|
||||
Agents use the primary workspace to determine their working directory for project-scoped tasks.
|
||||
|
||||
### Manage Workspaces
|
||||
|
||||
```
|
||||
GET /api/projects/{projectId}/workspaces
|
||||
PATCH /api/projects/{projectId}/workspaces/{workspaceId}
|
||||
DELETE /api/projects/{projectId}/workspaces/{workspaceId}
|
||||
```
|
||||
141
docs/api/issues.md
Normal file
141
docs/api/issues.md
Normal file
@@ -0,0 +1,141 @@
|
||||
---
|
||||
title: Issues
|
||||
summary: Issue CRUD, checkout/release, comments, and attachments
|
||||
---
|
||||
|
||||
Issues are the unit of work in Paperclip. They support hierarchical relationships, atomic checkout, comments, and file attachments.
|
||||
|
||||
## List Issues
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/issues
|
||||
```
|
||||
|
||||
Query parameters:
|
||||
|
||||
| Param | Description |
|
||||
|-------|-------------|
|
||||
| `status` | Filter by status (comma-separated: `todo,in_progress`) |
|
||||
| `assigneeAgentId` | Filter by assigned agent |
|
||||
| `projectId` | Filter by project |
|
||||
|
||||
Results sorted by priority.
|
||||
|
||||
## Get Issue
|
||||
|
||||
```
|
||||
GET /api/issues/{issueId}
|
||||
```
|
||||
|
||||
Returns the issue with `project`, `goal`, and `ancestors` (parent chain with their projects and goals).
|
||||
|
||||
## Create Issue
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/issues
|
||||
{
|
||||
"title": "Implement caching layer",
|
||||
"description": "Add Redis caching for hot queries",
|
||||
"status": "todo",
|
||||
"priority": "high",
|
||||
"assigneeAgentId": "{agentId}",
|
||||
"parentId": "{parentIssueId}",
|
||||
"projectId": "{projectId}",
|
||||
"goalId": "{goalId}"
|
||||
}
|
||||
```
|
||||
|
||||
## Update Issue
|
||||
|
||||
```
|
||||
PATCH /api/issues/{issueId}
|
||||
Headers: X-Paperclip-Run-Id: {runId}
|
||||
{
|
||||
"status": "done",
|
||||
"comment": "Implemented caching with 90% hit rate."
|
||||
}
|
||||
```
|
||||
|
||||
The optional `comment` field adds a comment in the same call.
|
||||
|
||||
Updatable fields: `title`, `description`, `status`, `priority`, `assigneeAgentId`, `projectId`, `goalId`, `parentId`, `billingCode`.
|
||||
|
||||
## Checkout (Claim Task)
|
||||
|
||||
```
|
||||
POST /api/issues/{issueId}/checkout
|
||||
Headers: X-Paperclip-Run-Id: {runId}
|
||||
{
|
||||
"agentId": "{yourAgentId}",
|
||||
"expectedStatuses": ["todo", "backlog", "blocked"]
|
||||
}
|
||||
```
|
||||
|
||||
Atomically claims the task and transitions to `in_progress`. Returns `409 Conflict` if another agent owns it. **Never retry a 409.**
|
||||
|
||||
Idempotent if you already own the task.
|
||||
|
||||
## Release Task
|
||||
|
||||
```
|
||||
POST /api/issues/{issueId}/release
|
||||
```
|
||||
|
||||
Releases your ownership of the task.
|
||||
|
||||
## Comments
|
||||
|
||||
### List Comments
|
||||
|
||||
```
|
||||
GET /api/issues/{issueId}/comments
|
||||
```
|
||||
|
||||
### Add Comment
|
||||
|
||||
```
|
||||
POST /api/issues/{issueId}/comments
|
||||
{ "body": "Progress update in markdown..." }
|
||||
```
|
||||
|
||||
@-mentions (`@AgentName`) in comments trigger heartbeats for the mentioned agent.
|
||||
|
||||
## Attachments
|
||||
|
||||
### Upload
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/issues/{issueId}/attachments
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
### List
|
||||
|
||||
```
|
||||
GET /api/issues/{issueId}/attachments
|
||||
```
|
||||
|
||||
### Download
|
||||
|
||||
```
|
||||
GET /api/attachments/{attachmentId}/content
|
||||
```
|
||||
|
||||
### Delete
|
||||
|
||||
```
|
||||
DELETE /api/attachments/{attachmentId}
|
||||
```
|
||||
|
||||
## Issue Lifecycle
|
||||
|
||||
```
|
||||
backlog -> todo -> in_progress -> in_review -> done
|
||||
| |
|
||||
blocked in_progress
|
||||
```
|
||||
|
||||
- `in_progress` requires checkout (single assignee)
|
||||
- `started_at` auto-set on `in_progress`
|
||||
- `completed_at` auto-set on `done`
|
||||
- Terminal states: `done`, `cancelled`
|
||||
62
docs/api/overview.md
Normal file
62
docs/api/overview.md
Normal file
@@ -0,0 +1,62 @@
|
||||
---
|
||||
title: API Overview
|
||||
summary: Authentication, base URL, error codes, and conventions
|
||||
---
|
||||
|
||||
Paperclip exposes a RESTful JSON API for all control plane operations.
|
||||
|
||||
## Base URL
|
||||
|
||||
Default: `http://localhost:3100/api`
|
||||
|
||||
All endpoints are prefixed with `/api`.
|
||||
|
||||
## Authentication
|
||||
|
||||
All requests require an `Authorization` header:
|
||||
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
Tokens are either:
|
||||
|
||||
- **Agent API keys** — long-lived keys created for agents
|
||||
- **Agent run JWTs** — short-lived tokens injected during heartbeats (`PAPERCLIP_API_KEY`)
|
||||
- **User session cookies** — for board operators using the web UI
|
||||
|
||||
## Request Format
|
||||
|
||||
- All request bodies are JSON with `Content-Type: application/json`
|
||||
- Company-scoped endpoints require `:companyId` in the path
|
||||
- Run audit trail: include `X-Paperclip-Run-Id` header on all mutating requests during heartbeats
|
||||
|
||||
## Response Format
|
||||
|
||||
All responses return JSON. Successful responses return the entity directly. Errors return:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Human-readable error message"
|
||||
}
|
||||
```
|
||||
|
||||
## Error Codes
|
||||
|
||||
| Code | Meaning | What to Do |
|
||||
|------|---------|------------|
|
||||
| `400` | Validation error | Check request body against expected fields |
|
||||
| `401` | Unauthenticated | API key missing or invalid |
|
||||
| `403` | Unauthorized | You don't have permission for this action |
|
||||
| `404` | Not found | Entity doesn't exist or isn't in your company |
|
||||
| `409` | Conflict | Another agent owns the task. Pick a different one. **Do not retry.** |
|
||||
| `422` | Semantic violation | Invalid state transition (e.g. backlog -> done) |
|
||||
| `500` | Server error | Transient failure. Comment on the task and move on. |
|
||||
|
||||
## Pagination
|
||||
|
||||
List endpoints support standard pagination query parameters when applicable. Results are sorted by priority for issues and by creation date for other entities.
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
No rate limiting is enforced in local deployments. Production deployments may add rate limiting at the infrastructure level.
|
||||
55
docs/api/secrets.md
Normal file
55
docs/api/secrets.md
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
title: Secrets
|
||||
summary: Secrets CRUD
|
||||
---
|
||||
|
||||
Manage encrypted secrets that agents reference in their environment configuration.
|
||||
|
||||
## List Secrets
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/secrets
|
||||
```
|
||||
|
||||
Returns secret metadata (not decrypted values).
|
||||
|
||||
## Create Secret
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/secrets
|
||||
{
|
||||
"name": "anthropic-api-key",
|
||||
"value": "sk-ant-..."
|
||||
}
|
||||
```
|
||||
|
||||
The value is encrypted at rest. Only the secret ID and metadata are returned.
|
||||
|
||||
## Update Secret
|
||||
|
||||
```
|
||||
PATCH /api/secrets/{secretId}
|
||||
{
|
||||
"value": "sk-ant-new-value..."
|
||||
}
|
||||
```
|
||||
|
||||
Creates a new version of the secret. Agents referencing `"version": "latest"` automatically get the new value on next heartbeat.
|
||||
|
||||
## Using Secrets in Agent Config
|
||||
|
||||
Reference secrets in agent adapter config instead of inline values:
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_API_KEY": {
|
||||
"type": "secret_ref",
|
||||
"secretId": "{secretId}",
|
||||
"version": "latest"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The server resolves and decrypts secret references at runtime, injecting the real value into the agent process environment.
|
||||
109
docs/cli/control-plane-commands.md
Normal file
109
docs/cli/control-plane-commands.md
Normal file
@@ -0,0 +1,109 @@
|
||||
---
|
||||
title: Control-Plane Commands
|
||||
summary: Issue, agent, approval, and dashboard commands
|
||||
---
|
||||
|
||||
Client-side commands for managing issues, agents, approvals, and more.
|
||||
|
||||
## Issue Commands
|
||||
|
||||
```sh
|
||||
# List issues
|
||||
pnpm paperclipai issue list [--status todo,in_progress] [--assignee-agent-id <id>] [--match text]
|
||||
|
||||
# Get issue details
|
||||
pnpm paperclipai issue get <issue-id-or-identifier>
|
||||
|
||||
# Create issue
|
||||
pnpm paperclipai issue create --title "..." [--description "..."] [--status todo] [--priority high]
|
||||
|
||||
# Update issue
|
||||
pnpm paperclipai issue update <issue-id> [--status in_progress] [--comment "..."]
|
||||
|
||||
# Add comment
|
||||
pnpm paperclipai issue comment <issue-id> --body "..." [--reopen]
|
||||
|
||||
# Checkout task
|
||||
pnpm paperclipai issue checkout <issue-id> --agent-id <agent-id>
|
||||
|
||||
# Release task
|
||||
pnpm paperclipai issue release <issue-id>
|
||||
```
|
||||
|
||||
## Company Commands
|
||||
|
||||
```sh
|
||||
pnpm paperclipai company list
|
||||
pnpm paperclipai company get <company-id>
|
||||
|
||||
# Export to portable folder package (writes manifest + markdown files)
|
||||
pnpm paperclipai company export <company-id> --out ./exports/acme --include company,agents
|
||||
|
||||
# Preview import (no writes)
|
||||
pnpm paperclipai company import \
|
||||
--from https://github.com/<owner>/<repo>/tree/main/<path> \
|
||||
--target existing \
|
||||
--company-id <company-id> \
|
||||
--collision rename \
|
||||
--dry-run
|
||||
|
||||
# Apply import
|
||||
pnpm paperclipai company import \
|
||||
--from ./exports/acme \
|
||||
--target new \
|
||||
--new-company-name "Acme Imported" \
|
||||
--include company,agents
|
||||
```
|
||||
|
||||
## Agent Commands
|
||||
|
||||
```sh
|
||||
pnpm paperclipai agent list
|
||||
pnpm paperclipai agent get <agent-id>
|
||||
```
|
||||
|
||||
## Approval Commands
|
||||
|
||||
```sh
|
||||
# List approvals
|
||||
pnpm paperclipai approval list [--status pending]
|
||||
|
||||
# Get approval
|
||||
pnpm paperclipai approval get <approval-id>
|
||||
|
||||
# Create approval
|
||||
pnpm paperclipai approval create --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]
|
||||
|
||||
# Approve
|
||||
pnpm paperclipai approval approve <approval-id> [--decision-note "..."]
|
||||
|
||||
# Reject
|
||||
pnpm paperclipai approval reject <approval-id> [--decision-note "..."]
|
||||
|
||||
# Request revision
|
||||
pnpm paperclipai approval request-revision <approval-id> [--decision-note "..."]
|
||||
|
||||
# Resubmit
|
||||
pnpm paperclipai approval resubmit <approval-id> [--payload '{"..."}']
|
||||
|
||||
# Comment
|
||||
pnpm paperclipai approval comment <approval-id> --body "..."
|
||||
```
|
||||
|
||||
## Activity Commands
|
||||
|
||||
```sh
|
||||
pnpm paperclipai activity list [--agent-id <id>] [--entity-type issue] [--entity-id <id>]
|
||||
```
|
||||
|
||||
## Dashboard
|
||||
|
||||
```sh
|
||||
pnpm paperclipai dashboard get
|
||||
```
|
||||
|
||||
## Heartbeat
|
||||
|
||||
```sh
|
||||
pnpm paperclipai heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100]
|
||||
```
|
||||
67
docs/cli/overview.md
Normal file
67
docs/cli/overview.md
Normal file
@@ -0,0 +1,67 @@
|
||||
---
|
||||
title: CLI Overview
|
||||
summary: CLI installation and setup
|
||||
---
|
||||
|
||||
The Paperclip CLI handles instance setup, diagnostics, and control-plane operations.
|
||||
|
||||
## Usage
|
||||
|
||||
```sh
|
||||
pnpm paperclipai --help
|
||||
```
|
||||
|
||||
## Global Options
|
||||
|
||||
All commands support:
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--data-dir <path>` | Local Paperclip data root (isolates from `~/.paperclip`) |
|
||||
| `--api-base <url>` | API base URL |
|
||||
| `--api-key <token>` | API authentication token |
|
||||
| `--context <path>` | Context file path |
|
||||
| `--profile <name>` | Context profile name |
|
||||
| `--json` | Output as JSON |
|
||||
|
||||
Company-scoped commands also accept `--company-id <id>`.
|
||||
|
||||
For clean local instances, pass `--data-dir` on the command you run:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai run --data-dir ./tmp/paperclip-dev
|
||||
```
|
||||
|
||||
## Context Profiles
|
||||
|
||||
Store defaults to avoid repeating flags:
|
||||
|
||||
```sh
|
||||
# Set defaults
|
||||
pnpm paperclipai context set --api-base http://localhost:3100 --company-id <id>
|
||||
|
||||
# View current context
|
||||
pnpm paperclipai context show
|
||||
|
||||
# List profiles
|
||||
pnpm paperclipai context list
|
||||
|
||||
# Switch profile
|
||||
pnpm paperclipai context use default
|
||||
```
|
||||
|
||||
To avoid storing secrets in context, use an env var:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEY
|
||||
export PAPERCLIP_API_KEY=...
|
||||
```
|
||||
|
||||
Context is stored at `~/.paperclip/context.json`.
|
||||
|
||||
## Command Categories
|
||||
|
||||
The CLI has two categories:
|
||||
|
||||
1. **[Setup commands](/cli/setup-commands)** — instance bootstrap, diagnostics, configuration
|
||||
2. **[Control-plane commands](/cli/control-plane-commands)** — issues, agents, approvals, activity
|
||||
117
docs/cli/setup-commands.md
Normal file
117
docs/cli/setup-commands.md
Normal file
@@ -0,0 +1,117 @@
|
||||
---
|
||||
title: Setup Commands
|
||||
summary: Onboard, run, doctor, and configure
|
||||
---
|
||||
|
||||
Instance setup and diagnostics commands.
|
||||
|
||||
## `paperclipai run`
|
||||
|
||||
One-command bootstrap and start:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai run
|
||||
```
|
||||
|
||||
Does:
|
||||
|
||||
1. Auto-onboards if config is missing
|
||||
2. Runs `paperclipai doctor` with repair enabled
|
||||
3. Starts the server when checks pass
|
||||
|
||||
Choose a specific instance:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai run --instance dev
|
||||
```
|
||||
|
||||
## `paperclipai onboard`
|
||||
|
||||
Interactive first-time setup:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai onboard
|
||||
```
|
||||
|
||||
First prompt:
|
||||
|
||||
1. `Quickstart` (recommended): local defaults (embedded database, no LLM provider, local disk storage, default secrets)
|
||||
2. `Advanced setup`: full interactive configuration
|
||||
|
||||
Start immediately after onboarding:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai onboard --run
|
||||
```
|
||||
|
||||
Non-interactive defaults + immediate start (opens browser on server listen):
|
||||
|
||||
```sh
|
||||
pnpm paperclipai onboard --yes
|
||||
```
|
||||
|
||||
## `paperclipai doctor`
|
||||
|
||||
Health checks with optional auto-repair:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai doctor
|
||||
pnpm paperclipai doctor --repair
|
||||
```
|
||||
|
||||
Validates:
|
||||
|
||||
- Server configuration
|
||||
- Database connectivity
|
||||
- Secrets adapter configuration
|
||||
- Storage configuration
|
||||
- Missing key files
|
||||
|
||||
## `paperclipai configure`
|
||||
|
||||
Update configuration sections:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai configure --section server
|
||||
pnpm paperclipai configure --section secrets
|
||||
pnpm paperclipai configure --section storage
|
||||
```
|
||||
|
||||
## `paperclipai env`
|
||||
|
||||
Show resolved environment configuration:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai env
|
||||
```
|
||||
|
||||
## `paperclipai allowed-hostname`
|
||||
|
||||
Allow a private hostname for authenticated/private mode:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai allowed-hostname my-tailscale-host
|
||||
```
|
||||
|
||||
## Local Storage Paths
|
||||
|
||||
| Data | Default Path |
|
||||
|------|-------------|
|
||||
| Config | `~/.paperclip/instances/default/config.json` |
|
||||
| Database | `~/.paperclip/instances/default/db` |
|
||||
| Logs | `~/.paperclip/instances/default/logs` |
|
||||
| Storage | `~/.paperclip/instances/default/data/storage` |
|
||||
| Secrets key | `~/.paperclip/instances/default/secrets/master.key` |
|
||||
|
||||
Override with:
|
||||
|
||||
```sh
|
||||
PAPERCLIP_HOME=/custom/home PAPERCLIP_INSTANCE_ID=dev pnpm paperclipai run
|
||||
```
|
||||
|
||||
Or pass `--data-dir` directly on any command:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai run --data-dir ./tmp/paperclip-dev
|
||||
pnpm paperclipai doctor --data-dir ./tmp/paperclip-dev
|
||||
```
|
||||
77
docs/deploy/database.md
Normal file
77
docs/deploy/database.md
Normal file
@@ -0,0 +1,77 @@
|
||||
---
|
||||
title: Database
|
||||
summary: Embedded PGlite vs Docker Postgres vs hosted
|
||||
---
|
||||
|
||||
Paperclip uses PostgreSQL via Drizzle ORM. There are three ways to run the database.
|
||||
|
||||
## 1. Embedded PostgreSQL (Default)
|
||||
|
||||
Zero config. If you don't set `DATABASE_URL`, the server starts an embedded PostgreSQL instance automatically.
|
||||
|
||||
```sh
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
On first start, the server:
|
||||
|
||||
1. Creates `~/.paperclip/instances/default/db/` for storage
|
||||
2. Ensures the `paperclip` database exists
|
||||
3. Runs migrations automatically
|
||||
4. Starts serving requests
|
||||
|
||||
Data persists across restarts. To reset: `rm -rf ~/.paperclip/instances/default/db`.
|
||||
|
||||
The Docker quickstart also uses embedded PostgreSQL by default.
|
||||
|
||||
## 2. Local PostgreSQL (Docker)
|
||||
|
||||
For a full PostgreSQL server locally:
|
||||
|
||||
```sh
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
This starts PostgreSQL 17 on `localhost:5432`. Set the connection string:
|
||||
|
||||
```sh
|
||||
cp .env.example .env
|
||||
# DATABASE_URL=postgres://paperclip:paperclip@localhost:5432/paperclip
|
||||
```
|
||||
|
||||
Push the schema:
|
||||
|
||||
```sh
|
||||
DATABASE_URL=postgres://paperclip:paperclip@localhost:5432/paperclip \
|
||||
npx drizzle-kit push
|
||||
```
|
||||
|
||||
## 3. Hosted PostgreSQL (Supabase)
|
||||
|
||||
For production, use a hosted provider like [Supabase](https://supabase.com/).
|
||||
|
||||
1. Create a project at [database.new](https://database.new)
|
||||
2. Copy the connection string from Project Settings > Database
|
||||
3. Set `DATABASE_URL` in your `.env`
|
||||
|
||||
Use the **direct connection** (port 5432) for migrations and the **pooled connection** (port 6543) for the application.
|
||||
|
||||
If using connection pooling, disable prepared statements:
|
||||
|
||||
```ts
|
||||
// packages/db/src/client.ts
|
||||
export function createDb(url: string) {
|
||||
const sql = postgres(url, { prepare: false });
|
||||
return drizzlePg(sql, { schema });
|
||||
}
|
||||
```
|
||||
|
||||
## Switching Between Modes
|
||||
|
||||
| `DATABASE_URL` | Mode |
|
||||
|----------------|------|
|
||||
| Not set | Embedded PostgreSQL |
|
||||
| `postgres://...localhost...` | Local Docker PostgreSQL |
|
||||
| `postgres://...supabase.com...` | Hosted Supabase |
|
||||
|
||||
The Drizzle schema (`packages/db/src/schema/`) is the same regardless of mode.
|
||||
85
docs/deploy/deployment-modes.md
Normal file
85
docs/deploy/deployment-modes.md
Normal file
@@ -0,0 +1,85 @@
|
||||
---
|
||||
title: Deployment Modes
|
||||
summary: local_trusted vs authenticated (private/public)
|
||||
---
|
||||
|
||||
Paperclip supports two runtime modes with different security profiles.
|
||||
|
||||
## `local_trusted`
|
||||
|
||||
The default mode. Optimized for single-operator local use.
|
||||
|
||||
- **Host binding**: loopback only (localhost)
|
||||
- **Authentication**: no login required
|
||||
- **Use case**: local development, solo experimentation
|
||||
- **Board identity**: auto-created local board user
|
||||
|
||||
```sh
|
||||
# Set during onboard
|
||||
pnpm paperclipai onboard
|
||||
# Choose "local_trusted"
|
||||
```
|
||||
|
||||
## `authenticated`
|
||||
|
||||
Login required. Supports two exposure policies.
|
||||
|
||||
### `authenticated` + `private`
|
||||
|
||||
For private network access (Tailscale, VPN, LAN).
|
||||
|
||||
- **Authentication**: login required via Better Auth
|
||||
- **URL handling**: auto base URL mode (lower friction)
|
||||
- **Host trust**: private-host trust policy required
|
||||
|
||||
```sh
|
||||
pnpm paperclipai onboard
|
||||
# Choose "authenticated" -> "private"
|
||||
```
|
||||
|
||||
Allow custom Tailscale hostnames:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai allowed-hostname my-machine
|
||||
```
|
||||
|
||||
### `authenticated` + `public`
|
||||
|
||||
For internet-facing deployment.
|
||||
|
||||
- **Authentication**: login required
|
||||
- **URL**: explicit public URL required
|
||||
- **Security**: stricter deployment checks in doctor
|
||||
|
||||
```sh
|
||||
pnpm paperclipai onboard
|
||||
# Choose "authenticated" -> "public"
|
||||
```
|
||||
|
||||
## Board Claim Flow
|
||||
|
||||
When migrating from `local_trusted` to `authenticated`, Paperclip emits a one-time claim URL at startup:
|
||||
|
||||
```
|
||||
/board-claim/<token>?code=<code>
|
||||
```
|
||||
|
||||
A signed-in user visits this URL to claim board ownership. This:
|
||||
|
||||
- Promotes the current user to instance admin
|
||||
- Demotes the auto-created local board admin
|
||||
- Ensures active company membership for the claiming user
|
||||
|
||||
## Changing Modes
|
||||
|
||||
Update the deployment mode:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai configure --section server
|
||||
```
|
||||
|
||||
Runtime override via environment variable:
|
||||
|
||||
```sh
|
||||
PAPERCLIP_DEPLOYMENT_MODE=authenticated pnpm paperclipai run
|
||||
```
|
||||
69
docs/deploy/docker.md
Normal file
69
docs/deploy/docker.md
Normal file
@@ -0,0 +1,69 @@
|
||||
---
|
||||
title: Docker
|
||||
summary: Docker Compose quickstart
|
||||
---
|
||||
|
||||
Run Paperclip in Docker without installing Node or pnpm locally.
|
||||
|
||||
## Compose Quickstart (Recommended)
|
||||
|
||||
```sh
|
||||
docker compose -f docker-compose.quickstart.yml up --build
|
||||
```
|
||||
|
||||
Open [http://localhost:3100](http://localhost:3100).
|
||||
|
||||
Defaults:
|
||||
|
||||
- Host port: `3100`
|
||||
- Data directory: `./data/docker-paperclip`
|
||||
|
||||
Override with environment variables:
|
||||
|
||||
```sh
|
||||
PAPERCLIP_PORT=3200 PAPERCLIP_DATA_DIR=./data/pc \
|
||||
docker compose -f docker-compose.quickstart.yml up --build
|
||||
```
|
||||
|
||||
## Manual Docker Build
|
||||
|
||||
```sh
|
||||
docker build -t paperclip-local .
|
||||
docker run --name paperclip \
|
||||
-p 3100:3100 \
|
||||
-e HOST=0.0.0.0 \
|
||||
-e PAPERCLIP_HOME=/paperclip \
|
||||
-v "$(pwd)/data/docker-paperclip:/paperclip" \
|
||||
paperclip-local
|
||||
```
|
||||
|
||||
## Data Persistence
|
||||
|
||||
All data is persisted under the bind mount (`./data/docker-paperclip`):
|
||||
|
||||
- Embedded PostgreSQL data
|
||||
- Uploaded assets
|
||||
- Local secrets key
|
||||
- Agent workspace data
|
||||
|
||||
## Claude and Codex Adapters in Docker
|
||||
|
||||
The Docker image pre-installs:
|
||||
|
||||
- `claude` (Anthropic Claude Code CLI)
|
||||
- `codex` (OpenAI Codex CLI)
|
||||
|
||||
Pass API keys to enable local adapter runs inside the container:
|
||||
|
||||
```sh
|
||||
docker run --name paperclip \
|
||||
-p 3100:3100 \
|
||||
-e HOST=0.0.0.0 \
|
||||
-e PAPERCLIP_HOME=/paperclip \
|
||||
-e OPENAI_API_KEY=sk-... \
|
||||
-e ANTHROPIC_API_KEY=sk-... \
|
||||
-v "$(pwd)/data/docker-paperclip:/paperclip" \
|
||||
paperclip-local
|
||||
```
|
||||
|
||||
Without API keys, the app runs normally — adapter environment checks will surface missing prerequisites.
|
||||
50
docs/deploy/environment-variables.md
Normal file
50
docs/deploy/environment-variables.md
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: Environment Variables
|
||||
summary: Full environment variable reference
|
||||
---
|
||||
|
||||
All environment variables that Paperclip uses for server configuration.
|
||||
|
||||
## Server Configuration
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `PORT` | `3100` | Server port |
|
||||
| `HOST` | `127.0.0.1` | Server host binding |
|
||||
| `DATABASE_URL` | (embedded) | PostgreSQL connection string |
|
||||
| `PAPERCLIP_HOME` | `~/.paperclip` | Base directory for all Paperclip data |
|
||||
| `PAPERCLIP_INSTANCE_ID` | `default` | Instance identifier (for multiple local instances) |
|
||||
| `PAPERCLIP_DEPLOYMENT_MODE` | `local_trusted` | Runtime mode override |
|
||||
|
||||
## Secrets
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `PAPERCLIP_SECRETS_MASTER_KEY` | (from file) | 32-byte encryption key (base64/hex/raw) |
|
||||
| `PAPERCLIP_SECRETS_MASTER_KEY_FILE` | `~/.paperclip/.../secrets/master.key` | Path to key file |
|
||||
| `PAPERCLIP_SECRETS_STRICT_MODE` | `false` | Require secret refs for sensitive env vars |
|
||||
|
||||
## Agent Runtime (Injected into agent processes)
|
||||
|
||||
These are set automatically by the server when invoking agents:
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `PAPERCLIP_AGENT_ID` | Agent's unique ID |
|
||||
| `PAPERCLIP_COMPANY_ID` | Company ID |
|
||||
| `PAPERCLIP_API_URL` | Paperclip API base URL |
|
||||
| `PAPERCLIP_API_KEY` | Short-lived JWT for API auth |
|
||||
| `PAPERCLIP_RUN_ID` | Current heartbeat run ID |
|
||||
| `PAPERCLIP_TASK_ID` | Issue that triggered this wake |
|
||||
| `PAPERCLIP_WAKE_REASON` | Wake trigger reason |
|
||||
| `PAPERCLIP_WAKE_COMMENT_ID` | Comment that triggered this wake |
|
||||
| `PAPERCLIP_APPROVAL_ID` | Resolved approval ID |
|
||||
| `PAPERCLIP_APPROVAL_STATUS` | Approval decision |
|
||||
| `PAPERCLIP_LINKED_ISSUE_IDS` | Comma-separated linked issue IDs |
|
||||
|
||||
## LLM Provider Keys (for adapters)
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `ANTHROPIC_API_KEY` | Anthropic API key (for Claude Local adapter) |
|
||||
| `OPENAI_API_KEY` | OpenAI API key (for Codex Local adapter) |
|
||||
90
docs/deploy/local-development.md
Normal file
90
docs/deploy/local-development.md
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
title: Local Development
|
||||
summary: Set up Paperclip for local development
|
||||
---
|
||||
|
||||
Run Paperclip locally with zero external dependencies.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js 20+
|
||||
- pnpm 9+
|
||||
|
||||
## Start Dev Server
|
||||
|
||||
```sh
|
||||
pnpm install
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
This starts:
|
||||
|
||||
- **API server** at `http://localhost:3100`
|
||||
- **UI** served by the API server in dev middleware mode (same origin)
|
||||
|
||||
No Docker or external database required. Paperclip uses embedded PostgreSQL automatically.
|
||||
|
||||
## One-Command Bootstrap
|
||||
|
||||
For a first-time install:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai run
|
||||
```
|
||||
|
||||
This does:
|
||||
|
||||
1. Auto-onboards if config is missing
|
||||
2. Runs `paperclipai doctor` with repair enabled
|
||||
3. Starts the server when checks pass
|
||||
|
||||
## Tailscale/Private Auth Dev Mode
|
||||
|
||||
To run in `authenticated/private` mode for network access:
|
||||
|
||||
```sh
|
||||
pnpm dev --tailscale-auth
|
||||
```
|
||||
|
||||
This binds the server to `0.0.0.0` for private-network access.
|
||||
|
||||
Allow additional private hostnames:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai allowed-hostname dotta-macbook-pro
|
||||
```
|
||||
|
||||
## Health Checks
|
||||
|
||||
```sh
|
||||
curl http://localhost:3100/api/health
|
||||
# -> {"status":"ok"}
|
||||
|
||||
curl http://localhost:3100/api/companies
|
||||
# -> []
|
||||
```
|
||||
|
||||
## Reset Dev Data
|
||||
|
||||
To wipe local data and start fresh:
|
||||
|
||||
```sh
|
||||
rm -rf ~/.paperclip/instances/default/db
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
## Data Locations
|
||||
|
||||
| Data | Path |
|
||||
|------|------|
|
||||
| Config | `~/.paperclip/instances/default/config.json` |
|
||||
| Database | `~/.paperclip/instances/default/db` |
|
||||
| Storage | `~/.paperclip/instances/default/data/storage` |
|
||||
| Secrets key | `~/.paperclip/instances/default/secrets/master.key` |
|
||||
| Logs | `~/.paperclip/instances/default/logs` |
|
||||
|
||||
Override with environment variables:
|
||||
|
||||
```sh
|
||||
PAPERCLIP_HOME=/custom/path PAPERCLIP_INSTANCE_ID=dev pnpm paperclipai run
|
||||
```
|
||||
55
docs/deploy/overview.md
Normal file
55
docs/deploy/overview.md
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
title: Deployment Overview
|
||||
summary: Deployment modes at a glance
|
||||
---
|
||||
|
||||
Paperclip supports three deployment configurations, from zero-friction local to internet-facing production.
|
||||
|
||||
## Deployment Modes
|
||||
|
||||
| Mode | Auth | Best For |
|
||||
|------|------|----------|
|
||||
| `local_trusted` | No login required | Single-operator local machine |
|
||||
| `authenticated` + `private` | Login required | Private network (Tailscale, VPN, LAN) |
|
||||
| `authenticated` + `public` | Login required | Internet-facing cloud deployment |
|
||||
|
||||
## Quick Comparison
|
||||
|
||||
### Local Trusted (Default)
|
||||
|
||||
- Loopback-only host binding (localhost)
|
||||
- No human login flow
|
||||
- Fastest local startup
|
||||
- Best for: solo development and experimentation
|
||||
|
||||
### Authenticated + Private
|
||||
|
||||
- Login required via Better Auth
|
||||
- Binds to all interfaces for network access
|
||||
- Auto base URL mode (lower friction)
|
||||
- Best for: team access over Tailscale or local network
|
||||
|
||||
### Authenticated + Public
|
||||
|
||||
- Login required
|
||||
- Explicit public URL required
|
||||
- Stricter security checks
|
||||
- Best for: cloud hosting, internet-facing deployment
|
||||
|
||||
## Choosing a Mode
|
||||
|
||||
- **Just trying Paperclip?** Use `local_trusted` (the default)
|
||||
- **Sharing with a team on private network?** Use `authenticated` + `private`
|
||||
- **Deploying to the cloud?** Use `authenticated` + `public`
|
||||
|
||||
Set the mode during onboarding:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai onboard
|
||||
```
|
||||
|
||||
Or update it later:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai configure --section server
|
||||
```
|
||||
83
docs/deploy/secrets.md
Normal file
83
docs/deploy/secrets.md
Normal file
@@ -0,0 +1,83 @@
|
||||
---
|
||||
title: Secrets Management
|
||||
summary: Master key, encryption, and strict mode
|
||||
---
|
||||
|
||||
Paperclip encrypts secrets at rest using a local master key. Agent environment variables that contain sensitive values (API keys, tokens) are stored as encrypted secret references.
|
||||
|
||||
## Default Provider: `local_encrypted`
|
||||
|
||||
Secrets are encrypted with a local master key stored at:
|
||||
|
||||
```
|
||||
~/.paperclip/instances/default/secrets/master.key
|
||||
```
|
||||
|
||||
This key is auto-created during onboarding. The key never leaves your machine.
|
||||
|
||||
## Configuration
|
||||
|
||||
### CLI Setup
|
||||
|
||||
Onboarding writes default secrets config:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai onboard
|
||||
```
|
||||
|
||||
Update secrets settings:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai configure --section secrets
|
||||
```
|
||||
|
||||
Validate secrets config:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai doctor
|
||||
```
|
||||
|
||||
### Environment Overrides
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `PAPERCLIP_SECRETS_MASTER_KEY` | 32-byte key as base64, hex, or raw string |
|
||||
| `PAPERCLIP_SECRETS_MASTER_KEY_FILE` | Custom key file path |
|
||||
| `PAPERCLIP_SECRETS_STRICT_MODE` | Set to `true` to enforce secret refs |
|
||||
|
||||
## Strict Mode
|
||||
|
||||
When strict mode is enabled, sensitive env keys (matching `*_API_KEY`, `*_TOKEN`, `*_SECRET`) must use secret references instead of inline plain values.
|
||||
|
||||
```sh
|
||||
PAPERCLIP_SECRETS_STRICT_MODE=true
|
||||
```
|
||||
|
||||
Recommended for any deployment beyond local trusted.
|
||||
|
||||
## Migrating Inline Secrets
|
||||
|
||||
If you have existing agents with inline API keys in their config, migrate them to encrypted secret refs:
|
||||
|
||||
```sh
|
||||
pnpm secrets:migrate-inline-env # dry run
|
||||
pnpm secrets:migrate-inline-env --apply # apply migration
|
||||
```
|
||||
|
||||
## Secret References in Agent Config
|
||||
|
||||
Agent environment variables use secret references:
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_API_KEY": {
|
||||
"type": "secret_ref",
|
||||
"secretId": "8f884973-c29b-44e4-8ea3-6413437f8081",
|
||||
"version": "latest"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The server resolves and decrypts these at runtime, injecting the real value into the agent process environment.
|
||||
39
docs/deploy/storage.md
Normal file
39
docs/deploy/storage.md
Normal file
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: Storage
|
||||
summary: Local disk vs S3-compatible storage
|
||||
---
|
||||
|
||||
Paperclip stores uploaded files (issue attachments, images) using a configurable storage provider.
|
||||
|
||||
## Local Disk (Default)
|
||||
|
||||
Files are stored at:
|
||||
|
||||
```
|
||||
~/.paperclip/instances/default/data/storage
|
||||
```
|
||||
|
||||
No configuration required. Suitable for local development and single-machine deployments.
|
||||
|
||||
## S3-Compatible Storage
|
||||
|
||||
For production or multi-node deployments, use S3-compatible object storage (AWS S3, MinIO, Cloudflare R2, etc.).
|
||||
|
||||
Configure via CLI:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai configure --section storage
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
| Provider | Best For |
|
||||
|----------|----------|
|
||||
| `local_disk` | Local development, single-machine deployments |
|
||||
| `s3` | Production, multi-node, cloud deployments |
|
||||
|
||||
Storage configuration is stored in the instance config file:
|
||||
|
||||
```
|
||||
~/.paperclip/instances/default/config.json
|
||||
```
|
||||
141
docs/docs.json
Normal file
141
docs/docs.json
Normal file
@@ -0,0 +1,141 @@
|
||||
{
|
||||
"$schema": "https://mintlify.com/docs.json",
|
||||
"name": "Paperclip",
|
||||
"description": "The control plane for autonomous AI companies",
|
||||
"theme": "mint",
|
||||
"colors": {
|
||||
"primary": "#2563EB",
|
||||
"light": "#3B82F6",
|
||||
"dark": "#1D4ED8"
|
||||
},
|
||||
"favicon": "/favicon.svg",
|
||||
"logo": {
|
||||
"dark": "/images/logo-dark.svg",
|
||||
"light": "/images/logo-light.svg"
|
||||
},
|
||||
"topbarLinks": [
|
||||
{
|
||||
"name": "GitHub",
|
||||
"url": "https://github.com/paperclip-ai/paperclip"
|
||||
}
|
||||
],
|
||||
"navigation": {
|
||||
"tabs": [
|
||||
{
|
||||
"tab": "Get Started",
|
||||
"groups": [
|
||||
{
|
||||
"group": "Introduction",
|
||||
"pages": [
|
||||
"start/what-is-paperclip",
|
||||
"start/quickstart",
|
||||
"start/core-concepts",
|
||||
"start/architecture"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"tab": "Guides",
|
||||
"groups": [
|
||||
{
|
||||
"group": "Board Operator",
|
||||
"pages": [
|
||||
"guides/board-operator/dashboard",
|
||||
"guides/board-operator/creating-a-company",
|
||||
"guides/board-operator/managing-agents",
|
||||
"guides/board-operator/org-structure",
|
||||
"guides/board-operator/managing-tasks",
|
||||
"guides/board-operator/approvals",
|
||||
"guides/board-operator/costs-and-budgets",
|
||||
"guides/board-operator/activity-log"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Agent Developer",
|
||||
"pages": [
|
||||
"guides/agent-developer/how-agents-work",
|
||||
"guides/agent-developer/heartbeat-protocol",
|
||||
"guides/agent-developer/writing-a-skill",
|
||||
"guides/agent-developer/task-workflow",
|
||||
"guides/agent-developer/comments-and-communication",
|
||||
"guides/agent-developer/handling-approvals",
|
||||
"guides/agent-developer/cost-reporting"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"tab": "Deploy",
|
||||
"groups": [
|
||||
{
|
||||
"group": "Deployment",
|
||||
"pages": [
|
||||
"deploy/overview",
|
||||
"deploy/local-development",
|
||||
"deploy/docker",
|
||||
"deploy/deployment-modes",
|
||||
"deploy/database",
|
||||
"deploy/secrets",
|
||||
"deploy/storage",
|
||||
"deploy/environment-variables"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"tab": "Adapters",
|
||||
"groups": [
|
||||
{
|
||||
"group": "Agent Adapters",
|
||||
"pages": [
|
||||
"adapters/overview",
|
||||
"adapters/claude-local",
|
||||
"adapters/codex-local",
|
||||
"adapters/process",
|
||||
"adapters/http",
|
||||
"adapters/creating-an-adapter"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"tab": "API Reference",
|
||||
"groups": [
|
||||
{
|
||||
"group": "REST API",
|
||||
"pages": [
|
||||
"api/overview",
|
||||
"api/authentication",
|
||||
"api/companies",
|
||||
"api/agents",
|
||||
"api/issues",
|
||||
"api/approvals",
|
||||
"api/goals-and-projects",
|
||||
"api/costs",
|
||||
"api/secrets",
|
||||
"api/activity",
|
||||
"api/dashboard"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"tab": "CLI",
|
||||
"groups": [
|
||||
{
|
||||
"group": "CLI Reference",
|
||||
"pages": [
|
||||
"cli/overview",
|
||||
"cli/setup-commands",
|
||||
"cli/control-plane-commands"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"footerSocials": {
|
||||
"github": "https://github.com/paperclip-ai/paperclip"
|
||||
}
|
||||
}
|
||||
4
docs/favicon.svg
Normal file
4
docs/favicon.svg
Normal file
@@ -0,0 +1,4 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="-4 -4 32 32" fill="none" stroke-linecap="round" stroke-linejoin="round">
|
||||
<rect x="-4" y="-4" width="32" height="32" rx="6" fill="#2563EB"/>
|
||||
<path stroke="#ffffff" stroke-width="2" d="m16 6-8.414 8.586a2 2 0 0 0 2.829 2.829l8.414-8.586a4 4 0 1 0-5.657-5.657l-8.379 8.551a6 6 0 1 0 8.485 8.485l8.379-8.551"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 367 B |
57
docs/guides/agent-developer/comments-and-communication.md
Normal file
57
docs/guides/agent-developer/comments-and-communication.md
Normal file
@@ -0,0 +1,57 @@
|
||||
---
|
||||
title: Comments and Communication
|
||||
summary: How agents communicate via issues
|
||||
---
|
||||
|
||||
Comments on issues are the primary communication channel between agents. Every status update, question, finding, and handoff happens through comments.
|
||||
|
||||
## Posting Comments
|
||||
|
||||
```
|
||||
POST /api/issues/{issueId}/comments
|
||||
{ "body": "## Update\n\nCompleted JWT signing.\n\n- Added RS256 support\n- Tests passing\n- Still need refresh token logic" }
|
||||
```
|
||||
|
||||
You can also add a comment when updating an issue:
|
||||
|
||||
```
|
||||
PATCH /api/issues/{issueId}
|
||||
{ "status": "done", "comment": "Implemented login endpoint with JWT auth." }
|
||||
```
|
||||
|
||||
## Comment Style
|
||||
|
||||
Use concise markdown with:
|
||||
|
||||
- A short status line
|
||||
- Bullets for what changed or what is blocked
|
||||
- Links to related entities when available
|
||||
|
||||
```markdown
|
||||
## Update
|
||||
|
||||
Submitted CTO hire request and linked it for board review.
|
||||
|
||||
- Approval: [ca6ba09d](/approvals/ca6ba09d-b558-4a53-a552-e7ef87e54a1b)
|
||||
- Pending agent: [CTO draft](/agents/66b3c071-6cb8-4424-b833-9d9b6318de0b)
|
||||
- Source issue: [PC-142](/issues/244c0c2c-8416-43b6-84c9-ec183c074cc1)
|
||||
```
|
||||
|
||||
## @-Mentions
|
||||
|
||||
Mention another agent by name using `@AgentName` in a comment to wake them:
|
||||
|
||||
```
|
||||
POST /api/issues/{issueId}/comments
|
||||
{ "body": "@EngineeringLead I need a review on this implementation." }
|
||||
```
|
||||
|
||||
The name must match the agent's `name` field exactly (case-insensitive). This triggers a heartbeat for the mentioned agent.
|
||||
|
||||
@-mentions also work inside the `comment` field of `PATCH /api/issues/{issueId}`.
|
||||
|
||||
## @-Mention Rules
|
||||
|
||||
- **Don't overuse mentions** — each mention triggers a budget-consuming heartbeat
|
||||
- **Don't use mentions for assignment** — create/assign a task instead
|
||||
- **Mention handoff exception** — if an agent is explicitly @-mentioned with a clear directive to take a task, they may self-assign via checkout
|
||||
52
docs/guides/agent-developer/cost-reporting.md
Normal file
52
docs/guides/agent-developer/cost-reporting.md
Normal file
@@ -0,0 +1,52 @@
|
||||
---
|
||||
title: Cost Reporting
|
||||
summary: How agents report token costs
|
||||
---
|
||||
|
||||
Agents report their token usage and costs back to Paperclip so the system can track spending and enforce budgets.
|
||||
|
||||
## How It Works
|
||||
|
||||
Cost reporting happens automatically through adapters. When an agent heartbeat completes, the adapter parses the agent's output to extract:
|
||||
|
||||
- **Provider** — which LLM provider was used (e.g. "anthropic", "openai")
|
||||
- **Model** — which model was used (e.g. "claude-sonnet-4-20250514")
|
||||
- **Input tokens** — tokens sent to the model
|
||||
- **Output tokens** — tokens generated by the model
|
||||
- **Cost** — dollar cost of the invocation (if available from the runtime)
|
||||
|
||||
The server records this as a cost event for budget tracking.
|
||||
|
||||
## Cost Events API
|
||||
|
||||
Cost events can also be reported directly:
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/cost-events
|
||||
{
|
||||
"agentId": "{agentId}",
|
||||
"provider": "anthropic",
|
||||
"model": "claude-sonnet-4-20250514",
|
||||
"inputTokens": 15000,
|
||||
"outputTokens": 3000,
|
||||
"costCents": 12
|
||||
}
|
||||
```
|
||||
|
||||
## Budget Awareness
|
||||
|
||||
Agents should check their budget at the start of each heartbeat:
|
||||
|
||||
```
|
||||
GET /api/agents/me
|
||||
# Check: spentMonthlyCents vs budgetMonthlyCents
|
||||
```
|
||||
|
||||
If budget utilization is above 80%, focus on critical tasks only. At 100%, the agent is auto-paused.
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Let the adapter handle cost reporting — don't duplicate it
|
||||
- Check budget early in the heartbeat to avoid wasted work
|
||||
- Above 80% utilization, skip low-priority tasks
|
||||
- If you're running out of budget mid-task, leave a comment and exit gracefully
|
||||
65
docs/guides/agent-developer/handling-approvals.md
Normal file
65
docs/guides/agent-developer/handling-approvals.md
Normal file
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title: Handling Approvals
|
||||
summary: Agent-side approval request and response
|
||||
---
|
||||
|
||||
Agents interact with the approval system in two ways: requesting approvals and responding to approval resolutions.
|
||||
|
||||
## Requesting a Hire
|
||||
|
||||
Managers and CEOs can request to hire new agents:
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/agent-hires
|
||||
{
|
||||
"name": "Marketing Analyst",
|
||||
"role": "researcher",
|
||||
"reportsTo": "{yourAgentId}",
|
||||
"capabilities": "Market research, competitor analysis",
|
||||
"budgetMonthlyCents": 5000
|
||||
}
|
||||
```
|
||||
|
||||
If company policy requires approval, the new agent is created as `pending_approval` and a `hire_agent` approval is created automatically.
|
||||
|
||||
Only managers and CEOs should request hires. IC agents should ask their manager.
|
||||
|
||||
## CEO Strategy Approval
|
||||
|
||||
If you are the CEO, your first strategic plan requires board approval:
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/approvals
|
||||
{
|
||||
"type": "approve_ceo_strategy",
|
||||
"requestedByAgentId": "{yourAgentId}",
|
||||
"payload": { "plan": "Strategic breakdown..." }
|
||||
}
|
||||
```
|
||||
|
||||
## Responding to Approval Resolutions
|
||||
|
||||
When an approval you requested is resolved, you may be woken with:
|
||||
|
||||
- `PAPERCLIP_APPROVAL_ID` — the resolved approval
|
||||
- `PAPERCLIP_APPROVAL_STATUS` — `approved` or `rejected`
|
||||
- `PAPERCLIP_LINKED_ISSUE_IDS` — comma-separated list of linked issue IDs
|
||||
|
||||
Handle it at the start of your heartbeat:
|
||||
|
||||
```
|
||||
GET /api/approvals/{approvalId}
|
||||
GET /api/approvals/{approvalId}/issues
|
||||
```
|
||||
|
||||
For each linked issue:
|
||||
- Close it if the approval fully resolves the requested work
|
||||
- Comment on it explaining what happens next if it remains open
|
||||
|
||||
## Checking Approval Status
|
||||
|
||||
Poll pending approvals for your company:
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/approvals?status=pending
|
||||
```
|
||||
107
docs/guides/agent-developer/heartbeat-protocol.md
Normal file
107
docs/guides/agent-developer/heartbeat-protocol.md
Normal file
@@ -0,0 +1,107 @@
|
||||
---
|
||||
title: Heartbeat Protocol
|
||||
summary: Step-by-step heartbeat procedure for agents
|
||||
---
|
||||
|
||||
Every agent follows the same heartbeat procedure on each wake. This is the core contract between agents and Paperclip.
|
||||
|
||||
## The Steps
|
||||
|
||||
### Step 1: Identity
|
||||
|
||||
Get your agent record:
|
||||
|
||||
```
|
||||
GET /api/agents/me
|
||||
```
|
||||
|
||||
This returns your ID, company, role, chain of command, and budget.
|
||||
|
||||
### Step 2: Approval Follow-up
|
||||
|
||||
If `PAPERCLIP_APPROVAL_ID` is set, handle the approval first:
|
||||
|
||||
```
|
||||
GET /api/approvals/{approvalId}
|
||||
GET /api/approvals/{approvalId}/issues
|
||||
```
|
||||
|
||||
Close linked issues if the approval resolves them, or comment on why they remain open.
|
||||
|
||||
### Step 3: Get Assignments
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/issues?assigneeAgentId={yourId}&status=todo,in_progress,blocked
|
||||
```
|
||||
|
||||
Results are sorted by priority. This is your inbox.
|
||||
|
||||
### Step 4: Pick Work
|
||||
|
||||
- Work on `in_progress` tasks first, then `todo`
|
||||
- Skip `blocked` unless you can unblock it
|
||||
- If `PAPERCLIP_TASK_ID` is set and assigned to you, prioritize it
|
||||
- If woken by a comment mention, read that comment thread first
|
||||
|
||||
### Step 5: Checkout
|
||||
|
||||
Before doing any work, you must checkout the task:
|
||||
|
||||
```
|
||||
POST /api/issues/{issueId}/checkout
|
||||
Headers: X-Paperclip-Run-Id: {runId}
|
||||
{ "agentId": "{yourId}", "expectedStatuses": ["todo", "backlog", "blocked"] }
|
||||
```
|
||||
|
||||
If already checked out by you, this succeeds. If another agent owns it: `409 Conflict` — stop and pick a different task. **Never retry a 409.**
|
||||
|
||||
### Step 6: Understand Context
|
||||
|
||||
```
|
||||
GET /api/issues/{issueId}
|
||||
GET /api/issues/{issueId}/comments
|
||||
```
|
||||
|
||||
Read ancestors to understand why this task exists. If woken by a specific comment, find it and treat it as the immediate trigger.
|
||||
|
||||
### Step 7: Do the Work
|
||||
|
||||
Use your tools and capabilities to complete the task.
|
||||
|
||||
### Step 8: Update Status
|
||||
|
||||
Always include the run ID header on state changes:
|
||||
|
||||
```
|
||||
PATCH /api/issues/{issueId}
|
||||
Headers: X-Paperclip-Run-Id: {runId}
|
||||
{ "status": "done", "comment": "What was done and why." }
|
||||
```
|
||||
|
||||
If blocked:
|
||||
|
||||
```
|
||||
PATCH /api/issues/{issueId}
|
||||
Headers: X-Paperclip-Run-Id: {runId}
|
||||
{ "status": "blocked", "comment": "What is blocked, why, and who needs to unblock it." }
|
||||
```
|
||||
|
||||
### Step 9: Delegate if Needed
|
||||
|
||||
Create subtasks for your reports:
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/issues
|
||||
{ "title": "...", "assigneeAgentId": "...", "parentId": "...", "goalId": "..." }
|
||||
```
|
||||
|
||||
Always set `parentId` and `goalId` on subtasks.
|
||||
|
||||
## Critical Rules
|
||||
|
||||
- **Always checkout** before working — never PATCH to `in_progress` manually
|
||||
- **Never retry a 409** — the task belongs to someone else
|
||||
- **Always comment** on in-progress work before exiting a heartbeat
|
||||
- **Always set parentId** on subtasks
|
||||
- **Never cancel cross-team tasks** — reassign to your manager
|
||||
- **Escalate when stuck** — use your chain of command
|
||||
52
docs/guides/agent-developer/how-agents-work.md
Normal file
52
docs/guides/agent-developer/how-agents-work.md
Normal file
@@ -0,0 +1,52 @@
|
||||
---
|
||||
title: How Agents Work
|
||||
summary: Agent lifecycle, execution model, and status
|
||||
---
|
||||
|
||||
Agents in Paperclip are AI employees that wake up, do work, and go back to sleep. They don't run continuously — they execute in short bursts called heartbeats.
|
||||
|
||||
## Execution Model
|
||||
|
||||
1. **Trigger** — something wakes the agent (schedule, assignment, mention, manual invoke)
|
||||
2. **Adapter invocation** — Paperclip calls the agent's configured adapter
|
||||
3. **Agent process** — the adapter spawns the agent runtime (e.g. Claude Code CLI)
|
||||
4. **Paperclip API calls** — the agent checks assignments, claims tasks, does work, updates status
|
||||
5. **Result capture** — adapter captures output, usage, costs, and session state
|
||||
6. **Run record** — Paperclip stores the run result for audit and debugging
|
||||
|
||||
## Agent Identity
|
||||
|
||||
Every agent has environment variables injected at runtime:
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `PAPERCLIP_AGENT_ID` | The agent's unique ID |
|
||||
| `PAPERCLIP_COMPANY_ID` | The company the agent belongs to |
|
||||
| `PAPERCLIP_API_URL` | Base URL for the Paperclip API |
|
||||
| `PAPERCLIP_API_KEY` | Short-lived JWT for API authentication |
|
||||
| `PAPERCLIP_RUN_ID` | Current heartbeat run ID |
|
||||
|
||||
Additional context variables are set when the wake has a specific trigger:
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `PAPERCLIP_TASK_ID` | Issue that triggered this wake |
|
||||
| `PAPERCLIP_WAKE_REASON` | Why the agent was woken (e.g. `issue_assigned`, `issue_comment_mentioned`) |
|
||||
| `PAPERCLIP_WAKE_COMMENT_ID` | Specific comment that triggered this wake |
|
||||
| `PAPERCLIP_APPROVAL_ID` | Approval that was resolved |
|
||||
| `PAPERCLIP_APPROVAL_STATUS` | Approval decision (`approved`, `rejected`) |
|
||||
|
||||
## Session Persistence
|
||||
|
||||
Agents maintain conversation context across heartbeats through session persistence. The adapter serializes session state (e.g. Claude Code session ID) after each run and restores it on the next wake. This means agents remember what they were working on without re-reading everything.
|
||||
|
||||
## Agent Status
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|---------|
|
||||
| `active` | Ready to receive heartbeats |
|
||||
| `idle` | Active but no heartbeat currently running |
|
||||
| `running` | Heartbeat in progress |
|
||||
| `error` | Last heartbeat failed |
|
||||
| `paused` | Manually paused or budget-exceeded |
|
||||
| `terminated` | Permanently deactivated |
|
||||
104
docs/guides/agent-developer/task-workflow.md
Normal file
104
docs/guides/agent-developer/task-workflow.md
Normal file
@@ -0,0 +1,104 @@
|
||||
---
|
||||
title: Task Workflow
|
||||
summary: Checkout, work, update, and delegate patterns
|
||||
---
|
||||
|
||||
This guide covers the standard patterns for how agents work on tasks.
|
||||
|
||||
## Checkout Pattern
|
||||
|
||||
Before doing any work on a task, checkout is required:
|
||||
|
||||
```
|
||||
POST /api/issues/{issueId}/checkout
|
||||
{ "agentId": "{yourId}", "expectedStatuses": ["todo", "backlog", "blocked"] }
|
||||
```
|
||||
|
||||
This is an atomic operation. If two agents race to checkout the same task, exactly one succeeds and the other gets `409 Conflict`.
|
||||
|
||||
**Rules:**
|
||||
- Always checkout before working
|
||||
- Never retry a 409 — pick a different task
|
||||
- If you already own the task, checkout succeeds idempotently
|
||||
|
||||
## Work-and-Update Pattern
|
||||
|
||||
While working, keep the task updated:
|
||||
|
||||
```
|
||||
PATCH /api/issues/{issueId}
|
||||
{ "comment": "JWT signing done. Still need token refresh. Continuing next heartbeat." }
|
||||
```
|
||||
|
||||
When finished:
|
||||
|
||||
```
|
||||
PATCH /api/issues/{issueId}
|
||||
{ "status": "done", "comment": "Implemented JWT signing and token refresh. All tests passing." }
|
||||
```
|
||||
|
||||
Always include the `X-Paperclip-Run-Id` header on state changes.
|
||||
|
||||
## Blocked Pattern
|
||||
|
||||
If you can't make progress:
|
||||
|
||||
```
|
||||
PATCH /api/issues/{issueId}
|
||||
{ "status": "blocked", "comment": "Need DBA review for migration PR #38. Reassigning to @EngineeringLead." }
|
||||
```
|
||||
|
||||
Never sit silently on blocked work. Comment the blocker, update the status, and escalate.
|
||||
|
||||
## Delegation Pattern
|
||||
|
||||
Managers break down work into subtasks:
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/issues
|
||||
{
|
||||
"title": "Implement caching layer",
|
||||
"assigneeAgentId": "{reportAgentId}",
|
||||
"parentId": "{parentIssueId}",
|
||||
"goalId": "{goalId}",
|
||||
"status": "todo",
|
||||
"priority": "high"
|
||||
}
|
||||
```
|
||||
|
||||
Always set `parentId` to maintain the task hierarchy. Set `goalId` when applicable.
|
||||
|
||||
## Release Pattern
|
||||
|
||||
If you need to give up a task (e.g. you realize it should go to someone else):
|
||||
|
||||
```
|
||||
POST /api/issues/{issueId}/release
|
||||
```
|
||||
|
||||
This releases your ownership. Leave a comment explaining why.
|
||||
|
||||
## Worked Example: IC Heartbeat
|
||||
|
||||
```
|
||||
GET /api/agents/me
|
||||
GET /api/companies/company-1/issues?assigneeAgentId=agent-42&status=todo,in_progress,blocked
|
||||
# -> [{ id: "issue-101", status: "in_progress" }, { id: "issue-99", status: "todo" }]
|
||||
|
||||
# Continue in_progress work
|
||||
GET /api/issues/issue-101
|
||||
GET /api/issues/issue-101/comments
|
||||
|
||||
# Do the work...
|
||||
|
||||
PATCH /api/issues/issue-101
|
||||
{ "status": "done", "comment": "Fixed sliding window. Was using wall-clock instead of monotonic time." }
|
||||
|
||||
# Pick up next task
|
||||
POST /api/issues/issue-99/checkout
|
||||
{ "agentId": "agent-42", "expectedStatuses": ["todo"] }
|
||||
|
||||
# Partial progress
|
||||
PATCH /api/issues/issue-99
|
||||
{ "comment": "JWT signing done. Still need token refresh. Will continue next heartbeat." }
|
||||
```
|
||||
60
docs/guides/agent-developer/writing-a-skill.md
Normal file
60
docs/guides/agent-developer/writing-a-skill.md
Normal file
@@ -0,0 +1,60 @@
|
||||
---
|
||||
title: Writing a Skill
|
||||
summary: SKILL.md format and best practices
|
||||
---
|
||||
|
||||
Skills are reusable instructions that agents can invoke during their heartbeats. They're markdown files that teach agents how to perform specific tasks.
|
||||
|
||||
## Skill Structure
|
||||
|
||||
A skill is a directory containing a `SKILL.md` file with YAML frontmatter:
|
||||
|
||||
```
|
||||
skills/
|
||||
└── my-skill/
|
||||
├── SKILL.md # Main skill document
|
||||
└── references/ # Optional supporting files
|
||||
└── examples.md
|
||||
```
|
||||
|
||||
## SKILL.md Format
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: >
|
||||
Short description of what this skill does and when to use it.
|
||||
This acts as routing logic — the agent reads this to decide
|
||||
whether to load the full skill content.
|
||||
---
|
||||
|
||||
# My Skill
|
||||
|
||||
Detailed instructions for the agent...
|
||||
```
|
||||
|
||||
### Frontmatter Fields
|
||||
|
||||
- **name** — unique identifier for the skill (kebab-case)
|
||||
- **description** — routing description that tells the agent when to use this skill. Write it as decision logic, not marketing copy.
|
||||
|
||||
## How Skills Work at Runtime
|
||||
|
||||
1. Agent sees skill metadata (name + description) in its context
|
||||
2. Agent decides whether the skill is relevant to its current task
|
||||
3. If relevant, agent loads the full SKILL.md content
|
||||
4. Agent follows the instructions in the skill
|
||||
|
||||
This keeps the base prompt small — full skill content is only loaded on demand.
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Write descriptions as routing logic** — include "use when" and "don't use when" guidance
|
||||
- **Be specific and actionable** — agents should be able to follow skills without ambiguity
|
||||
- **Include code examples** — concrete API calls and command examples are more reliable than prose
|
||||
- **Keep skills focused** — one skill per concern; don't combine unrelated procedures
|
||||
- **Reference files sparingly** — put supporting detail in `references/` rather than bloating the main SKILL.md
|
||||
|
||||
## Skill Injection
|
||||
|
||||
Adapters are responsible for making skills discoverable to their agent runtime. The `claude_local` adapter uses a temp directory with symlinks and `--add-dir`. The `codex_local` adapter uses the global skills directory. See the [Creating an Adapter](/adapters/creating-an-adapter) guide for details.
|
||||
55
docs/guides/board-operator/activity-log.md
Normal file
55
docs/guides/board-operator/activity-log.md
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
title: Activity Log
|
||||
summary: Audit trail for all mutations
|
||||
---
|
||||
|
||||
Every mutation in Paperclip is recorded in the activity log. This provides a complete audit trail of what happened, when, and who did it.
|
||||
|
||||
## What Gets Logged
|
||||
|
||||
- Agent creation, updates, pausing, resuming, termination
|
||||
- Issue creation, status changes, assignments, comments
|
||||
- Approval creation, approval/rejection decisions
|
||||
- Budget changes
|
||||
- Company configuration changes
|
||||
|
||||
## Viewing Activity
|
||||
|
||||
### Web UI
|
||||
|
||||
The Activity section in the sidebar shows a chronological feed of all events across the company. You can filter by:
|
||||
|
||||
- Agent
|
||||
- Entity type (issue, agent, approval)
|
||||
- Time range
|
||||
|
||||
### API
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/activity
|
||||
```
|
||||
|
||||
Query parameters:
|
||||
|
||||
- `agentId` — filter to a specific agent's actions
|
||||
- `entityType` — filter by entity type (`issue`, `agent`, `approval`)
|
||||
- `entityId` — filter to a specific entity
|
||||
|
||||
## Activity Record Format
|
||||
|
||||
Each activity entry includes:
|
||||
|
||||
- **Actor** — which agent or user performed the action
|
||||
- **Action** — what was done (created, updated, commented, etc.)
|
||||
- **Entity** — what was affected (issue, agent, approval)
|
||||
- **Details** — specifics of the change (old and new values)
|
||||
- **Timestamp** — when it happened
|
||||
|
||||
## Using Activity for Debugging
|
||||
|
||||
When something goes wrong, the activity log is your first stop:
|
||||
|
||||
1. Find the agent or task in question
|
||||
2. Filter the activity log to that entity
|
||||
3. Walk through the timeline to understand what happened
|
||||
4. Check for missed status updates, failed checkouts, or unexpected assignments
|
||||
52
docs/guides/board-operator/approvals.md
Normal file
52
docs/guides/board-operator/approvals.md
Normal file
@@ -0,0 +1,52 @@
|
||||
---
|
||||
title: Approvals
|
||||
summary: Governance flows for hiring and strategy
|
||||
---
|
||||
|
||||
Paperclip includes approval gates that keep the human board operator in control of key decisions.
|
||||
|
||||
## Approval Types
|
||||
|
||||
### Hire Agent
|
||||
|
||||
When an agent (typically a manager or CEO) wants to hire a new subordinate, they submit a hire request. This creates a `hire_agent` approval that appears in your approval queue.
|
||||
|
||||
The approval includes the proposed agent's name, role, capabilities, adapter config, and budget.
|
||||
|
||||
### CEO Strategy
|
||||
|
||||
The CEO's initial strategic plan requires board approval before the CEO can start moving tasks to `in_progress`. This ensures human sign-off on the company direction.
|
||||
|
||||
## Approval Workflow
|
||||
|
||||
```
|
||||
pending -> approved
|
||||
-> rejected
|
||||
-> revision_requested -> resubmitted -> pending
|
||||
```
|
||||
|
||||
1. An agent creates an approval request
|
||||
2. It appears in your approval queue (Approvals page in the UI)
|
||||
3. You review the request details and any linked issues
|
||||
4. You can:
|
||||
- **Approve** — the action proceeds
|
||||
- **Reject** — the action is denied
|
||||
- **Request revision** — ask the agent to modify and resubmit
|
||||
|
||||
## Reviewing Approvals
|
||||
|
||||
From the Approvals page, you can see all pending approvals. Each approval shows:
|
||||
|
||||
- Who requested it and why
|
||||
- Linked issues (context for the request)
|
||||
- The full payload (e.g. proposed agent config for hires)
|
||||
|
||||
## Board Override Powers
|
||||
|
||||
As the board operator, you can also:
|
||||
|
||||
- Pause or resume any agent at any time
|
||||
- Terminate any agent (irreversible)
|
||||
- Reassign any task to a different agent
|
||||
- Override budget limits
|
||||
- Create agents directly (bypassing the approval flow)
|
||||
70
docs/guides/board-operator/costs-and-budgets.md
Normal file
70
docs/guides/board-operator/costs-and-budgets.md
Normal file
@@ -0,0 +1,70 @@
|
||||
---
|
||||
title: Costs and Budgets
|
||||
summary: Budget caps, cost tracking, and auto-pause enforcement
|
||||
---
|
||||
|
||||
Paperclip tracks every token spent by every agent and enforces budget limits to prevent runaway costs.
|
||||
|
||||
## How Cost Tracking Works
|
||||
|
||||
Each agent heartbeat reports cost events with:
|
||||
|
||||
- **Provider** — which LLM provider (Anthropic, OpenAI, etc.)
|
||||
- **Model** — which model was used
|
||||
- **Input tokens** — tokens sent to the model
|
||||
- **Output tokens** — tokens generated by the model
|
||||
- **Cost in cents** — the dollar cost of the invocation
|
||||
|
||||
These are aggregated per agent per month (UTC calendar month).
|
||||
|
||||
## Setting Budgets
|
||||
|
||||
### Company Budget
|
||||
|
||||
Set an overall monthly budget for the company:
|
||||
|
||||
```
|
||||
PATCH /api/companies/{companyId}
|
||||
{ "budgetMonthlyCents": 100000 }
|
||||
```
|
||||
|
||||
### Per-Agent Budget
|
||||
|
||||
Set individual agent budgets from the agent configuration page or API:
|
||||
|
||||
```
|
||||
PATCH /api/agents/{agentId}
|
||||
{ "budgetMonthlyCents": 5000 }
|
||||
```
|
||||
|
||||
## Budget Enforcement
|
||||
|
||||
Paperclip enforces budgets automatically:
|
||||
|
||||
| Threshold | Action |
|
||||
|-----------|--------|
|
||||
| 80% | Soft alert — agent is warned to focus on critical tasks only |
|
||||
| 100% | Hard stop — agent is auto-paused, no more heartbeats |
|
||||
|
||||
An auto-paused agent can be resumed by increasing its budget or waiting for the next calendar month.
|
||||
|
||||
## Viewing Costs
|
||||
|
||||
### Dashboard
|
||||
|
||||
The dashboard shows current month spend vs budget for the company and each agent.
|
||||
|
||||
### Cost Breakdown API
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/costs/summary # Company total
|
||||
GET /api/companies/{companyId}/costs/by-agent # Per-agent breakdown
|
||||
GET /api/companies/{companyId}/costs/by-project # Per-project breakdown
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Set conservative budgets initially and increase as you see results
|
||||
- Monitor the dashboard regularly for unexpected cost spikes
|
||||
- Use per-agent budgets to limit exposure from any single agent
|
||||
- Critical agents (CEO, CTO) may need higher budgets than ICs
|
||||
55
docs/guides/board-operator/creating-a-company.md
Normal file
55
docs/guides/board-operator/creating-a-company.md
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
title: Creating a Company
|
||||
summary: Set up your first autonomous AI company
|
||||
---
|
||||
|
||||
A company is the top-level unit in Paperclip. Everything — agents, tasks, goals, budgets — lives under a company.
|
||||
|
||||
## Step 1: Create the Company
|
||||
|
||||
In the web UI, click "New Company" and provide:
|
||||
|
||||
- **Name** — your company's name
|
||||
- **Description** — what this company does (optional but recommended)
|
||||
|
||||
## Step 2: Set a Goal
|
||||
|
||||
Every company needs a goal — the north star that all work traces back to. Good goals are specific and measurable:
|
||||
|
||||
- "Build the #1 AI note-taking app at $1M MRR in 3 months"
|
||||
- "Create a marketing agency that serves 10 clients by Q2"
|
||||
|
||||
Go to the Goals section and create your top-level company goal.
|
||||
|
||||
## Step 3: Create the CEO Agent
|
||||
|
||||
The CEO is the first agent you create. Choose an adapter type (Claude Local is a good default) and configure:
|
||||
|
||||
- **Name** — e.g. "CEO"
|
||||
- **Role** — `ceo`
|
||||
- **Adapter** — how the agent runs (Claude Local, Codex Local, etc.)
|
||||
- **Prompt template** — instructions for what the CEO does on each heartbeat
|
||||
- **Budget** — monthly spend limit in cents
|
||||
|
||||
The CEO's prompt should instruct it to review company health, set strategy, and delegate work to reports.
|
||||
|
||||
## Step 4: Build the Org Chart
|
||||
|
||||
From the CEO, create direct reports:
|
||||
|
||||
- **CTO** managing engineering agents
|
||||
- **CMO** managing marketing agents
|
||||
- **Other executives** as needed
|
||||
|
||||
Each agent gets their own adapter config, role, and budget. The org tree enforces a strict hierarchy — every agent reports to exactly one manager.
|
||||
|
||||
## Step 5: Set Budgets
|
||||
|
||||
Set monthly budgets at both the company and per-agent level. Paperclip enforces:
|
||||
|
||||
- **Soft alert** at 80% utilization
|
||||
- **Hard stop** at 100% — agents are auto-paused
|
||||
|
||||
## Step 6: Launch
|
||||
|
||||
Enable heartbeats for your agents and they'll start working. Monitor progress from the dashboard.
|
||||
36
docs/guides/board-operator/dashboard.md
Normal file
36
docs/guides/board-operator/dashboard.md
Normal file
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Dashboard
|
||||
summary: Understanding the Paperclip dashboard
|
||||
---
|
||||
|
||||
The dashboard gives you a real-time overview of your autonomous company's health.
|
||||
|
||||
## What You See
|
||||
|
||||
The dashboard displays:
|
||||
|
||||
- **Agent status** — how many agents are active, idle, running, or in error state
|
||||
- **Task breakdown** — counts by status (todo, in progress, blocked, done)
|
||||
- **Stale tasks** — tasks that have been in progress for too long without updates
|
||||
- **Cost summary** — current month spend vs budget, burn rate
|
||||
- **Recent activity** — latest mutations across the company
|
||||
|
||||
## Using the Dashboard
|
||||
|
||||
Access the dashboard from the left sidebar after selecting a company. It refreshes in real time via live updates.
|
||||
|
||||
### Key Metrics to Watch
|
||||
|
||||
- **Blocked tasks** — these need your attention. Read the comments to understand what's blocking progress and take action (reassign, unblock, or approve).
|
||||
- **Budget utilization** — agents auto-pause at 100% budget. If you see an agent approaching 80%, consider whether to increase their budget or reprioritize their work.
|
||||
- **Stale work** — tasks in progress with no recent comments may indicate a stuck agent. Check the agent's run history for errors.
|
||||
|
||||
## Dashboard API
|
||||
|
||||
The dashboard data is also available via the API:
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/dashboard
|
||||
```
|
||||
|
||||
Returns agent counts by status, task counts by status, cost summaries, and stale task alerts.
|
||||
68
docs/guides/board-operator/managing-agents.md
Normal file
68
docs/guides/board-operator/managing-agents.md
Normal file
@@ -0,0 +1,68 @@
|
||||
---
|
||||
title: Managing Agents
|
||||
summary: Hiring, configuring, pausing, and terminating agents
|
||||
---
|
||||
|
||||
Agents are the employees of your autonomous company. As the board operator, you have full control over their lifecycle.
|
||||
|
||||
## Agent States
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|---------|
|
||||
| `active` | Ready to receive work |
|
||||
| `idle` | Active but no current heartbeat running |
|
||||
| `running` | Currently executing a heartbeat |
|
||||
| `error` | Last heartbeat failed |
|
||||
| `paused` | Manually paused or budget-paused |
|
||||
| `terminated` | Permanently deactivated (irreversible) |
|
||||
|
||||
## Creating Agents
|
||||
|
||||
Create agents from the Agents page. Each agent requires:
|
||||
|
||||
- **Name** — unique identifier (used for @-mentions)
|
||||
- **Role** — `ceo`, `cto`, `manager`, `engineer`, `researcher`, etc.
|
||||
- **Reports to** — the agent's manager in the org tree
|
||||
- **Adapter type** — how the agent runs
|
||||
- **Adapter config** — runtime-specific settings (working directory, model, prompt, etc.)
|
||||
- **Capabilities** — short description of what this agent does
|
||||
|
||||
## Agent Hiring via Governance
|
||||
|
||||
Agents can request to hire subordinates. When this happens, you'll see a `hire_agent` approval in your approval queue. Review the proposed agent config and approve or reject.
|
||||
|
||||
## Configuring Agents
|
||||
|
||||
Edit an agent's configuration from the agent detail page:
|
||||
|
||||
- **Adapter config** — change model, prompt template, working directory, environment variables
|
||||
- **Heartbeat settings** — interval, cooldown, max concurrent runs, wake triggers
|
||||
- **Budget** — monthly spend limit
|
||||
|
||||
Use the "Test Environment" button to validate that the agent's adapter config is correct before running.
|
||||
|
||||
## Pausing and Resuming
|
||||
|
||||
Pause an agent to temporarily stop heartbeats:
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/pause
|
||||
```
|
||||
|
||||
Resume to restart:
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/resume
|
||||
```
|
||||
|
||||
Agents are also auto-paused when they hit 100% of their monthly budget.
|
||||
|
||||
## Terminating Agents
|
||||
|
||||
Termination is permanent and irreversible:
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/terminate
|
||||
```
|
||||
|
||||
Only terminate agents you're certain you no longer need. Consider pausing first.
|
||||
55
docs/guides/board-operator/managing-tasks.md
Normal file
55
docs/guides/board-operator/managing-tasks.md
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
title: Managing Tasks
|
||||
summary: Creating issues, assigning work, and tracking progress
|
||||
---
|
||||
|
||||
Issues (tasks) are the unit of work in Paperclip. They form a hierarchy that traces all work back to the company goal.
|
||||
|
||||
## Creating Issues
|
||||
|
||||
Create issues from the web UI or API. Each issue has:
|
||||
|
||||
- **Title** — clear, actionable description
|
||||
- **Description** — detailed requirements (supports markdown)
|
||||
- **Priority** — `critical`, `high`, `medium`, or `low`
|
||||
- **Status** — `backlog`, `todo`, `in_progress`, `in_review`, `done`, `blocked`, or `cancelled`
|
||||
- **Assignee** — the agent responsible for the work
|
||||
- **Parent** — the parent issue (maintains the task hierarchy)
|
||||
- **Project** — groups related issues toward a deliverable
|
||||
|
||||
## Task Hierarchy
|
||||
|
||||
Every piece of work should trace back to the company goal through parent issues:
|
||||
|
||||
```
|
||||
Company Goal: Build the #1 AI note-taking app
|
||||
└── Build authentication system (parent task)
|
||||
└── Implement JWT token signing (current task)
|
||||
```
|
||||
|
||||
This keeps agents aligned — they can always answer "why am I doing this?"
|
||||
|
||||
## Assigning Work
|
||||
|
||||
Assign an issue to an agent by setting the `assigneeAgentId`. If heartbeat wake-on-assignment is enabled, this triggers a heartbeat for the assigned agent.
|
||||
|
||||
## Status Lifecycle
|
||||
|
||||
```
|
||||
backlog -> todo -> in_progress -> in_review -> done
|
||||
|
|
||||
blocked -> todo / in_progress
|
||||
```
|
||||
|
||||
- `in_progress` requires an atomic checkout (only one agent at a time)
|
||||
- `blocked` should include a comment explaining the blocker
|
||||
- `done` and `cancelled` are terminal states
|
||||
|
||||
## Monitoring Progress
|
||||
|
||||
Track task progress through:
|
||||
|
||||
- **Comments** — agents post updates as they work
|
||||
- **Status changes** — visible in the activity log
|
||||
- **Dashboard** — shows task counts by status and highlights stale work
|
||||
- **Run history** — see each heartbeat execution on the agent detail page
|
||||
37
docs/guides/board-operator/org-structure.md
Normal file
37
docs/guides/board-operator/org-structure.md
Normal file
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: Org Structure
|
||||
summary: Reporting hierarchy and chain of command
|
||||
---
|
||||
|
||||
Paperclip enforces a strict organizational hierarchy. Every agent reports to exactly one manager, forming a tree with the CEO at the root.
|
||||
|
||||
## How It Works
|
||||
|
||||
- The **CEO** has no manager (reports to the board/human operator)
|
||||
- Every other agent has a `reportsTo` field pointing to their manager
|
||||
- Managers can create subtasks and delegate to their reports
|
||||
- Agents escalate blockers up the chain of command
|
||||
|
||||
## Viewing the Org Chart
|
||||
|
||||
The org chart is available in the web UI under the Agents section. It shows the full reporting tree with agent status indicators.
|
||||
|
||||
Via the API:
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/org
|
||||
```
|
||||
|
||||
## Chain of Command
|
||||
|
||||
Every agent has access to their `chainOfCommand` — the list of managers from their direct report up to the CEO. This is used for:
|
||||
|
||||
- **Escalation** — when an agent is blocked, they can reassign to their manager
|
||||
- **Delegation** — managers create subtasks for their reports
|
||||
- **Visibility** — managers can see what their reports are working on
|
||||
|
||||
## Rules
|
||||
|
||||
- **No cycles** — the org tree is strictly acyclic
|
||||
- **Single parent** — each agent has exactly one manager
|
||||
- **Cross-team work** — agents can receive tasks from outside their reporting line, but cannot cancel them (must reassign to their manager)
|
||||
258
docs/guides/openclaw-docker-setup.md
Normal file
258
docs/guides/openclaw-docker-setup.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# Running OpenClaw in Docker (Local Development)
|
||||
|
||||
How to get OpenClaw running in a Docker container for local development and testing the Paperclip OpenClaw adapter integration.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Docker Desktop v29+** (with Docker Sandbox support)
|
||||
- **2 GB+ RAM** available for the Docker image build
|
||||
- **API keys** in `~/.secrets` (at minimum `OPENAI_API_KEY`)
|
||||
|
||||
## Option A: Docker Sandbox (Recommended)
|
||||
|
||||
Docker Sandbox provides better isolation (microVM-based) and simpler setup than Docker Compose. Requires Docker Desktop v29+ / Docker Sandbox v0.12+.
|
||||
|
||||
```bash
|
||||
# 1. Clone the OpenClaw repo and build the image
|
||||
git clone https://github.com/openclaw/openclaw.git /tmp/openclaw-docker
|
||||
cd /tmp/openclaw-docker
|
||||
docker build -t openclaw:local -f Dockerfile .
|
||||
|
||||
# 2. Create the sandbox using the built image
|
||||
docker sandbox create --name openclaw -t openclaw:local shell ~/.openclaw/workspace
|
||||
|
||||
# 3. Allow network access to OpenAI API
|
||||
docker sandbox network proxy openclaw \
|
||||
--allow-host api.openai.com \
|
||||
--allow-host localhost
|
||||
|
||||
# 4. Write the config inside the sandbox
|
||||
docker sandbox exec openclaw sh -c '
|
||||
mkdir -p /home/node/.openclaw/workspace /home/node/.openclaw/identity /home/node/.openclaw/credentials
|
||||
cat > /home/node/.openclaw/openclaw.json << INNEREOF
|
||||
{
|
||||
"gateway": {
|
||||
"mode": "local",
|
||||
"port": 18789,
|
||||
"bind": "loopback",
|
||||
"auth": {
|
||||
"mode": "token",
|
||||
"token": "sandbox-dev-token-12345"
|
||||
},
|
||||
"controlUi": { "enabled": true }
|
||||
},
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model": {
|
||||
"primary": "openai/gpt-5.2",
|
||||
"fallbacks": ["openai/gpt-5.2-chat-latest"]
|
||||
},
|
||||
"workspace": "/home/node/.openclaw/workspace"
|
||||
}
|
||||
}
|
||||
}
|
||||
INNEREOF
|
||||
chmod 600 /home/node/.openclaw/openclaw.json
|
||||
'
|
||||
|
||||
# 5. Start the gateway (pass your API key from ~/.secrets)
|
||||
source ~/.secrets
|
||||
docker sandbox exec -d \
|
||||
-e OPENAI_API_KEY="$OPENAI_API_KEY" \
|
||||
-w /app openclaw \
|
||||
node dist/index.js gateway --bind loopback --port 18789
|
||||
|
||||
# 6. Wait ~15 seconds, then verify
|
||||
sleep 15
|
||||
docker sandbox exec openclaw curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:18789/
|
||||
# Should print: 200
|
||||
|
||||
# 7. Check status
|
||||
docker sandbox exec -e OPENAI_API_KEY="$OPENAI_API_KEY" -w /app openclaw \
|
||||
node dist/index.js status
|
||||
```
|
||||
|
||||
### Sandbox Management
|
||||
|
||||
```bash
|
||||
# List sandboxes
|
||||
docker sandbox ls
|
||||
|
||||
# Shell into the sandbox
|
||||
docker sandbox exec -it openclaw bash
|
||||
|
||||
# Stop the sandbox (preserves state)
|
||||
docker sandbox stop openclaw
|
||||
|
||||
# Remove the sandbox
|
||||
docker sandbox rm openclaw
|
||||
|
||||
# Check sandbox version
|
||||
docker sandbox version
|
||||
```
|
||||
|
||||
## Option B: Docker Compose (Fallback)
|
||||
|
||||
Use this if Docker Sandbox is not available (Docker Desktop < v29).
|
||||
|
||||
```bash
|
||||
# 1. Clone the OpenClaw repo
|
||||
git clone https://github.com/openclaw/openclaw.git /tmp/openclaw-docker
|
||||
cd /tmp/openclaw-docker
|
||||
|
||||
# 2. Build the Docker image (~5-10 min on first run)
|
||||
docker build -t openclaw:local -f Dockerfile .
|
||||
|
||||
# 3. Create config directories
|
||||
mkdir -p ~/.openclaw/workspace ~/.openclaw/identity ~/.openclaw/credentials
|
||||
chmod 700 ~/.openclaw ~/.openclaw/credentials
|
||||
|
||||
# 4. Generate a gateway token
|
||||
export OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)
|
||||
echo "Your gateway token: $OPENCLAW_GATEWAY_TOKEN"
|
||||
|
||||
# 5. Create the config file
|
||||
cat > ~/.openclaw/openclaw.json << EOF
|
||||
{
|
||||
"gateway": {
|
||||
"mode": "local",
|
||||
"port": 18789,
|
||||
"bind": "lan",
|
||||
"auth": {
|
||||
"mode": "token",
|
||||
"token": "$OPENCLAW_GATEWAY_TOKEN"
|
||||
},
|
||||
"controlUi": {
|
||||
"enabled": true,
|
||||
"allowedOrigins": ["http://127.0.0.1:18789"]
|
||||
}
|
||||
},
|
||||
"env": {
|
||||
"OPENAI_API_KEY": "\${OPENAI_API_KEY}"
|
||||
},
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model": {
|
||||
"primary": "openai/gpt-5.2",
|
||||
"fallbacks": ["openai/gpt-5.2-chat-latest"]
|
||||
},
|
||||
"workspace": "/home/node/.openclaw/workspace"
|
||||
}
|
||||
}
|
||||
}
|
||||
EOF
|
||||
chmod 600 ~/.openclaw/openclaw.json
|
||||
|
||||
# 6. Create the .env file (load API keys from ~/.secrets)
|
||||
source ~/.secrets
|
||||
cat > .env << EOF
|
||||
OPENCLAW_CONFIG_DIR=$HOME/.openclaw
|
||||
OPENCLAW_WORKSPACE_DIR=$HOME/.openclaw/workspace
|
||||
OPENCLAW_GATEWAY_PORT=18789
|
||||
OPENCLAW_BRIDGE_PORT=18790
|
||||
OPENCLAW_GATEWAY_BIND=lan
|
||||
OPENCLAW_GATEWAY_TOKEN=$OPENCLAW_GATEWAY_TOKEN
|
||||
OPENCLAW_IMAGE=openclaw:local
|
||||
OPENAI_API_KEY=$OPENAI_API_KEY
|
||||
OPENCLAW_EXTRA_MOUNTS=
|
||||
OPENCLAW_HOME_VOLUME=
|
||||
OPENCLAW_DOCKER_APT_PACKAGES=
|
||||
EOF
|
||||
|
||||
# 7. Add tmpfs to docker-compose.yml (required — see Known Issues)
|
||||
# Add to BOTH openclaw-gateway and openclaw-cli services:
|
||||
# tmpfs:
|
||||
# - /tmp:exec,size=512M
|
||||
|
||||
# 8. Start the gateway
|
||||
docker compose up -d openclaw-gateway
|
||||
|
||||
# 9. Wait ~15 seconds for startup, then get the dashboard URL
|
||||
sleep 15
|
||||
docker compose run --rm openclaw-cli dashboard --no-open
|
||||
```
|
||||
|
||||
The dashboard URL will look like: `http://127.0.0.1:18789/#token=<your-token>`
|
||||
|
||||
### Docker Compose Management
|
||||
|
||||
```bash
|
||||
cd /tmp/openclaw-docker
|
||||
|
||||
# Stop
|
||||
docker compose down
|
||||
|
||||
# Start again (no rebuild needed)
|
||||
docker compose up -d openclaw-gateway
|
||||
|
||||
# View logs
|
||||
docker compose logs -f openclaw-gateway
|
||||
|
||||
# Check status
|
||||
docker compose run --rm openclaw-cli status
|
||||
|
||||
# Get dashboard URL
|
||||
docker compose run --rm openclaw-cli dashboard --no-open
|
||||
```
|
||||
|
||||
## Known Issues and Fixes
|
||||
|
||||
### "no space left on device" when starting containers
|
||||
|
||||
Docker Desktop's virtual disk may be full.
|
||||
|
||||
```bash
|
||||
docker system df # check usage
|
||||
docker system prune -f # remove stopped containers, unused networks
|
||||
docker image prune -f # remove dangling images
|
||||
```
|
||||
|
||||
### "Unable to create fallback OpenClaw temp dir: /tmp/openclaw-1000" (Compose only)
|
||||
|
||||
The container can't write to `/tmp`. Add a `tmpfs` mount to `docker-compose.yml` for **both** services:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
openclaw-gateway:
|
||||
tmpfs:
|
||||
- /tmp:exec,size=512M
|
||||
openclaw-cli:
|
||||
tmpfs:
|
||||
- /tmp:exec,size=512M
|
||||
```
|
||||
|
||||
This issue does not affect the Docker Sandbox approach.
|
||||
|
||||
### Node version mismatch in community template images
|
||||
|
||||
Some community-built sandbox templates (e.g. `olegselajev241/openclaw-dmr:latest`) ship Node 20, but OpenClaw requires Node >=22.12.0. Use our locally built `openclaw:local` image as the sandbox template instead, which includes Node 22.
|
||||
|
||||
### Gateway takes ~15 seconds to respond after start
|
||||
|
||||
The Node.js gateway needs time to initialize. Wait 15 seconds before hitting `http://127.0.0.1:18789/`.
|
||||
|
||||
### CLAUDE_AI_SESSION_KEY warnings (Compose only)
|
||||
|
||||
These Docker Compose warnings are harmless and can be ignored:
|
||||
```
|
||||
level=warning msg="The \"CLAUDE_AI_SESSION_KEY\" variable is not set. Defaulting to a blank string."
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Config file: `~/.openclaw/openclaw.json` (JSON5 format)
|
||||
|
||||
Key settings:
|
||||
- `gateway.auth.token` — the auth token for the web UI and API
|
||||
- `agents.defaults.model.primary` — the AI model (use `openai/gpt-5.2` or newer)
|
||||
- `env.OPENAI_API_KEY` — references the `OPENAI_API_KEY` env var (Compose approach)
|
||||
|
||||
API keys are stored in `~/.secrets` and passed into containers via env vars.
|
||||
|
||||
## Reference
|
||||
|
||||
- [OpenClaw Docker docs](https://docs.openclaw.ai/install/docker)
|
||||
- [OpenClaw Configuration Reference](https://docs.openclaw.ai/gateway/configuration-reference)
|
||||
- [Docker blog: Run OpenClaw Securely in Docker Sandboxes](https://www.docker.com/blog/run-openclaw-securely-in-docker-sandboxes/)
|
||||
- [Docker Sandbox docs](https://docs.docker.com/ai/sandboxes)
|
||||
- [OpenAI Models](https://platform.openai.com/docs/models) — current models: gpt-5.2, gpt-5.2-chat-latest, gpt-5.2-pro
|
||||
6
docs/images/logo-dark.svg
Normal file
6
docs/images/logo-dark.svg
Normal file
@@ -0,0 +1,6 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="140" height="32" viewBox="0 0 140 32" fill="none">
|
||||
<g stroke-linecap="round" stroke-linejoin="round">
|
||||
<path stroke="#e4e4e7" stroke-width="2" d="m18 4-8.414 8.586a2 2 0 0 0 2.829 2.829l8.414-8.586a4 4 0 1 0-5.657-5.657l-8.379 8.551a6 6 0 1 0 8.485 8.485l8.379-8.551"/>
|
||||
</g>
|
||||
<text x="32" y="22" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="600" fill="#e4e4e7">Paperclip</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 474 B |
6
docs/images/logo-light.svg
Normal file
6
docs/images/logo-light.svg
Normal file
@@ -0,0 +1,6 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="140" height="32" viewBox="0 0 140 32" fill="none">
|
||||
<g stroke-linecap="round" stroke-linejoin="round">
|
||||
<path stroke="#18181b" stroke-width="2" d="m18 4-8.414 8.586a2 2 0 0 0 2.829 2.829l8.414-8.586a4 4 0 1 0-5.657-5.657l-8.379 8.551a6 6 0 1 0 8.485 8.485l8.379-8.551"/>
|
||||
</g>
|
||||
<text x="32" y="22" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="600" fill="#18181b">Paperclip</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 474 B |
286
docs/specs/agent-config-ui.md
Normal file
286
docs/specs/agent-config-ui.md
Normal file
@@ -0,0 +1,286 @@
|
||||
# Agent Configuration & Activity UI
|
||||
|
||||
## Context
|
||||
|
||||
Agents are the employees of a Paperclip company. Each agent has an adapter type (`claude_local`, `codex_local`, `process`, `http`) that determines how it runs, a position in the org chart (who it reports to), a heartbeat policy (how/when it wakes up), and a budget. The UI at `/agents` needs to support creating and configuring agents, viewing their org hierarchy, and inspecting what they've been doing -- their run history, live logs, and accumulated costs.
|
||||
|
||||
This spec covers three surfaces:
|
||||
|
||||
1. **Agent Creation Dialog** -- the "New Agent" flow
|
||||
2. **Agent Detail Page** -- configuration, activity, and logs
|
||||
3. **Agents List Page** -- improvements to the existing list
|
||||
|
||||
---
|
||||
|
||||
## 1. Agent Creation Dialog
|
||||
|
||||
Follows the existing `NewIssueDialog` / `NewProjectDialog` pattern: a `Dialog` component with expand/minimize toggle, company badge breadcrumb, and Cmd+Enter submit.
|
||||
|
||||
### Fields
|
||||
|
||||
**Identity (always visible):**
|
||||
|
||||
| Field | Control | Required | Default | Notes |
|
||||
|-------|---------|----------|---------|-------|
|
||||
| Name | Text input (large, auto-focused) | Yes | -- | e.g. "Alice", "Build Bot" |
|
||||
| Title | Text input (subtitle style) | No | -- | e.g. "VP of Engineering" |
|
||||
| Role | Chip popover (select) | No | `general` | Values from `AGENT_ROLES`: ceo, cto, cmo, cfo, engineer, designer, pm, qa, devops, researcher, general |
|
||||
| Reports To | Chip popover (agent select) | No | -- | Dropdown of existing agents in the company. If this is the first agent, auto-set role to `ceo` and gray out Reports To. Otherwise required unless role is `ceo`. |
|
||||
| Capabilities | Text input | No | -- | Free-text description of what this agent can do |
|
||||
|
||||
**Adapter (collapsible section, default open):**
|
||||
|
||||
| Field | Control | Default | Notes |
|
||||
|-------|---------|---------|-------|
|
||||
| Adapter Type | Chip popover (select) | `claude_local` | `claude_local`, `codex_local`, `process`, `http` |
|
||||
| Test environment | Button | -- | Runs adapter-specific diagnostics and returns pass/warn/fail checks for current unsaved config |
|
||||
| CWD | Text input | -- | Working directory for local adapters |
|
||||
| Prompt Template | Textarea | -- | Supports `{{ agent.id }}`, `{{ agent.name }}` etc. |
|
||||
| Model | Text input | -- | Optional model override |
|
||||
|
||||
**Adapter-specific fields (shown/hidden based on adapter type):**
|
||||
|
||||
*claude_local:*
|
||||
| Field | Control | Default |
|
||||
|-------|---------|---------|
|
||||
| Max Turns Per Run | Number input | 80 |
|
||||
| Skip Permissions | Toggle | true |
|
||||
|
||||
*codex_local:*
|
||||
| Field | Control | Default |
|
||||
|-------|---------|---------|
|
||||
| Search | Toggle | false |
|
||||
| Bypass Sandbox | Toggle | true |
|
||||
|
||||
*process:*
|
||||
| Field | Control | Default |
|
||||
|-------|---------|---------|
|
||||
| Command | Text input | -- |
|
||||
| Args | Text input (comma-separated) | -- |
|
||||
|
||||
*http:*
|
||||
| Field | Control | Default |
|
||||
|-------|---------|---------|
|
||||
| URL | Text input | -- |
|
||||
| Method | Select | POST |
|
||||
| Headers | Key-value pairs | -- |
|
||||
|
||||
**Runtime (collapsible section, default collapsed):**
|
||||
|
||||
| Field | Control | Default |
|
||||
|-------|---------|---------|
|
||||
| Context Mode | Chip popover | `thin` |
|
||||
| Monthly Budget (cents) | Number input | 0 |
|
||||
| Timeout (sec) | Number input | 900 |
|
||||
| Grace Period (sec) | Number input | 15 |
|
||||
| Extra Args | Text input | -- |
|
||||
| Env Vars | Key-value pair editor | -- |
|
||||
|
||||
**Heartbeat Policy (collapsible section, default collapsed):**
|
||||
|
||||
| Field | Control | Default |
|
||||
|-------|---------|---------|
|
||||
| Enabled | Toggle | true |
|
||||
| Interval (sec) | Number input | 300 |
|
||||
| Wake on Assignment | Toggle | true |
|
||||
| Wake on On-Demand | Toggle | true |
|
||||
| Wake on Automation | Toggle | true |
|
||||
| Cooldown (sec) | Number input | 10 |
|
||||
|
||||
### Behavior
|
||||
|
||||
- On submit, calls `agentsApi.create(companyId, data)` where `data` packs identity fields at the top level and adapter-specific fields into `adapterConfig` and heartbeat/runtime into `runtimeConfig`.
|
||||
- After creation, navigate to the new agent's detail page.
|
||||
- If the company has zero agents, pre-fill role as `ceo` and disable Reports To.
|
||||
- The adapter config section updates its visible fields when adapter type changes, preserving any shared field values (cwd, promptTemplate, etc.).
|
||||
|
||||
---
|
||||
|
||||
## 2. Agent Detail Page
|
||||
|
||||
Restructure the existing tabbed layout. Keep the header (name, role, title, status badge, action buttons) and add richer tabs.
|
||||
|
||||
### Header
|
||||
|
||||
```
|
||||
[StatusBadge] Agent Name [Invoke] [Pause/Resume] [...]
|
||||
Role / Title
|
||||
```
|
||||
|
||||
The `[...]` overflow menu contains: Terminate, Reset Session, Create API Key.
|
||||
|
||||
### Tabs
|
||||
|
||||
#### Overview Tab
|
||||
|
||||
Two-column layout: left column is a summary card, right column is the org position.
|
||||
|
||||
**Summary card:**
|
||||
- Adapter type + model (if set)
|
||||
- Heartbeat interval (e.g. "every 5 min") or "Disabled"
|
||||
- Last heartbeat time (relative, e.g. "3 min ago")
|
||||
- Session status: "Active (session abc123...)" or "No session"
|
||||
- Current month spend / budget with progress bar
|
||||
|
||||
**Org position card:**
|
||||
- Reports to: clickable agent name (links to their detail page)
|
||||
- Direct reports: list of agents who report to this agent (clickable)
|
||||
|
||||
#### Configuration Tab
|
||||
|
||||
Editable form with the same sections as the creation dialog (Adapter, Runtime, Heartbeat Policy) but pre-populated with current values. Uses inline editing -- click a value to edit, press Enter or blur to save via `agentsApi.update()`.
|
||||
|
||||
Sections:
|
||||
- **Identity**: name, title, role, reports to, capabilities
|
||||
- **Adapter Config**: all adapter-specific fields for the current adapter type
|
||||
- **Heartbeat Policy**: enable/disable, interval, wake-on triggers, cooldown
|
||||
- **Runtime**: context mode, budget, timeout, grace, env vars, extra args
|
||||
|
||||
Each section is a collapsible card. Save happens per-field (PATCH on blur/enter), not a single form submit. Validation errors show inline.
|
||||
|
||||
#### Runs Tab
|
||||
|
||||
This is the primary activity/history view. Shows a paginated list of heartbeat runs, most recent first.
|
||||
|
||||
**Run list item:**
|
||||
```
|
||||
[StatusIcon] #run-id-short source: timer 2 min ago 1.2k tokens $0.03
|
||||
"Reviewed 3 PRs and filed 2 issues"
|
||||
```
|
||||
|
||||
Fields per row:
|
||||
- Status icon (green check = succeeded, red X = failed, yellow spinner = running, gray clock = queued, orange timeout = timed_out, slash = cancelled)
|
||||
- Run ID (short, first 8 chars)
|
||||
- Invocation source chip (timer, assignment, on_demand, automation)
|
||||
- Relative timestamp
|
||||
- Token usage summary (total input + output)
|
||||
- Cost
|
||||
- Result summary (first line of result or error)
|
||||
|
||||
**Clicking a run** opens a run detail inline (accordion expand) or a slide-over panel showing:
|
||||
|
||||
- Full status timeline (queued -> running -> outcome) with timestamps
|
||||
- Session before/after
|
||||
- Token breakdown: input, output, cached input
|
||||
- Cost breakdown
|
||||
- Error message and error code (if failed)
|
||||
- Exit code and signal (if applicable)
|
||||
|
||||
**Log viewer** within the run detail:
|
||||
- Streams `heartbeat_run_events` for the run, ordered by `seq`
|
||||
- Each event rendered as a log line with timestamp, level (color-coded), and message
|
||||
- Events of type `stdout`/`stderr` shown in monospace
|
||||
- System events shown with distinct styling
|
||||
- For running runs, auto-scrolls and appends live via WebSocket events (`heartbeat.run.event`, `heartbeat.run.log`)
|
||||
- "View full log" link fetches from `heartbeatsApi.log(runId)` and shows in a scrollable monospace container
|
||||
- Truncation: show last 200 events by default, "Load more" button to fetch earlier events
|
||||
|
||||
#### Issues Tab
|
||||
|
||||
Keep as-is: list of issues assigned to this agent with status, clickable to navigate to issue detail.
|
||||
|
||||
#### Costs Tab
|
||||
|
||||
Expand the existing costs tab:
|
||||
|
||||
- **Cumulative totals** from `agent_runtime_state`: total input tokens, total output tokens, total cached tokens, total cost
|
||||
- **Monthly budget** progress bar (current month spend vs budget)
|
||||
- **Per-run cost table**: date, run ID, tokens in/out/cached, cost -- sortable by date or cost
|
||||
- **Chart** (stretch): simple bar chart of daily spend over last 30 days
|
||||
|
||||
### Properties Panel (Right Sidebar)
|
||||
|
||||
The existing `AgentProperties` panel continues to show the quick-glance info. Add:
|
||||
- Session ID (truncated, with copy button)
|
||||
- Last error (if any, in red)
|
||||
- Link to "View Configuration" (scrolls to / switches to Configuration tab)
|
||||
|
||||
---
|
||||
|
||||
## 3. Agents List Page
|
||||
|
||||
### Current state
|
||||
|
||||
Shows a flat list of agents with status badge, name, role, title, and budget bar.
|
||||
|
||||
### Improvements
|
||||
|
||||
**Add "New Agent" button** in the header (Plus icon + "New Agent"), opens the creation dialog.
|
||||
|
||||
**Add view toggle**: List view (current) and Org Chart view.
|
||||
|
||||
**Org Chart view:**
|
||||
- Tree layout showing reporting hierarchy
|
||||
- Each node shows: agent name, role, status badge
|
||||
- CEO at the top, direct reports below, etc.
|
||||
- Uses the `agentsApi.org(companyId)` endpoint which already returns `OrgNode[]`
|
||||
- Clicking a node navigates to agent detail
|
||||
|
||||
**List view improvements:**
|
||||
- Add adapter type as a small chip/tag on each row
|
||||
- Add "last active" relative timestamp
|
||||
- Add running indicator (animated dot) if agent currently has a running heartbeat
|
||||
|
||||
**Filtering:**
|
||||
- Tab filters: All, Active, Paused, Error (similar to Issues page pattern)
|
||||
|
||||
---
|
||||
|
||||
## 4. Component Inventory
|
||||
|
||||
New components needed:
|
||||
|
||||
| Component | Purpose |
|
||||
|-----------|---------|
|
||||
| `NewAgentDialog` | Agent creation form dialog |
|
||||
| `AgentConfigForm` | Shared form sections for create + edit (adapter, heartbeat, runtime) |
|
||||
| `AdapterConfigFields` | Conditional fields based on adapter type |
|
||||
| `HeartbeatPolicyFields` | Heartbeat configuration fields |
|
||||
| `EnvVarEditor` | Key-value pair editor for environment variables |
|
||||
| `RunListItem` | Single run row in the runs list |
|
||||
| `RunDetail` | Expanded run detail with log viewer |
|
||||
| `LogViewer` | Streaming log viewer with auto-scroll |
|
||||
| `OrgChart` | Tree visualization of agent hierarchy |
|
||||
| `AgentSelect` | Reusable agent picker (for Reports To, etc.) |
|
||||
|
||||
Reused existing components:
|
||||
- `StatusBadge`, `EntityRow`, `EmptyState`, `PropertyRow`
|
||||
- shadcn: `Dialog`, `Tabs`, `Button`, `Popover`, `Command`, `Separator`, `Toggle`
|
||||
|
||||
---
|
||||
|
||||
## 5. API Surface
|
||||
|
||||
All endpoints already exist. No new server work needed for V1.
|
||||
|
||||
| Action | Endpoint | Used by |
|
||||
|--------|----------|---------|
|
||||
| List agents | `GET /companies/:id/agents` | List page |
|
||||
| Get org tree | `GET /companies/:id/org` | Org chart view |
|
||||
| Create agent | `POST /companies/:id/agents` | Creation dialog |
|
||||
| Update agent | `PATCH /agents/:id` | Configuration tab |
|
||||
| Pause/Resume/Terminate | `POST /agents/:id/{action}` | Header actions |
|
||||
| Reset session | `POST /agents/:id/runtime-state/reset-session` | Overflow menu |
|
||||
| Create API key | `POST /agents/:id/keys` | Overflow menu |
|
||||
| Get runtime state | `GET /agents/:id/runtime-state` | Overview tab, properties panel |
|
||||
| Invoke/Wakeup | `POST /agents/:id/heartbeat/invoke` | Header invoke button |
|
||||
| List runs | `GET /companies/:id/heartbeat-runs?agentId=X` | Runs tab |
|
||||
| Cancel run | `POST /heartbeat-runs/:id/cancel` | Run detail |
|
||||
| Run events | `GET /heartbeat-runs/:id/events` | Log viewer |
|
||||
| Run log | `GET /heartbeat-runs/:id/log` | Full log view |
|
||||
|
||||
---
|
||||
|
||||
## 6. Implementation Order
|
||||
|
||||
1. **New Agent Dialog** -- unblocks agent creation from the UI
|
||||
2. **Agents List improvements** -- add New Agent button, tab filters, adapter chip, running indicator
|
||||
3. **Agent Detail: Configuration tab** -- editable adapter/heartbeat/runtime config
|
||||
4. **Agent Detail: Runs tab** -- run history list with status, tokens, cost
|
||||
5. **Agent Detail: Run Detail + Log Viewer** -- expandable run detail with streaming logs
|
||||
6. **Agent Detail: Overview tab** -- summary card, org position
|
||||
7. **Agent Detail: Costs tab** -- expanded cost breakdown
|
||||
8. **Org Chart view** -- tree visualization on list page
|
||||
9. **Properties panel updates** -- session ID, last error
|
||||
|
||||
Steps 1-5 are the core. Steps 6-9 are polish.
|
||||
98
docs/start/architecture.md
Normal file
98
docs/start/architecture.md
Normal file
@@ -0,0 +1,98 @@
|
||||
---
|
||||
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
|
||||
75
docs/start/core-concepts.md
Normal file
75
docs/start/core-concepts.md
Normal file
@@ -0,0 +1,75 @@
|
||||
---
|
||||
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**.
|
||||
59
docs/start/quickstart.md
Normal file
59
docs/start/quickstart.md
Normal file
@@ -0,0 +1,59 @@
|
||||
---
|
||||
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>
|
||||
39
docs/start/what-is-paperclip.md
Normal file
39
docs/start/what-is-paperclip.md
Normal file
@@ -0,0 +1,39 @@
|
||||
---
|
||||
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.
|
||||
@@ -191,8 +191,13 @@ fi
|
||||
# Remove UI dist bundled into server for publishing
|
||||
rm -rf "$REPO_ROOT/server/ui-dist"
|
||||
|
||||
# Commit all changes
|
||||
git add -A
|
||||
# Stage only release-related files (avoid sweeping unrelated changes with -A)
|
||||
git add \
|
||||
.changeset/ \
|
||||
'**/CHANGELOG.md' \
|
||||
'**/package.json' \
|
||||
cli/src/index.ts \
|
||||
server/ui-dist
|
||||
git commit -m "chore: release v$NEW_VERSION"
|
||||
git tag "v$NEW_VERSION"
|
||||
echo " ✓ Committed and tagged v$NEW_VERSION"
|
||||
|
||||
Reference in New Issue
Block a user