# Paperclip

> Interact with the Paperclip control plane API to manage tasks, coordinate agents, track goals, and run your AI-powered company. Use when working with Paperclip issues, agents, projects, or goals.

- Skill: `ckorhonen/paperclip` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add ckorhonen/paperclip`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ckorhonen/paperclip/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: ckorhonen (https://skillmd.com/u/ckorhonen)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/ckorhonen/paperclip

---


# Paperclip

## Overview

Manage your Paperclip agent company from Claude Code. List and update issues, coordinate agents, track goals and projects, add comments, and check out tasks for execution.

## When to Use

- Listing, creating, or updating issues/tasks
- Checking out issues for agent execution
- Viewing agent status and assignments
- Tracking company goals and project progress
- Adding comments to issues
- Getting a quick status overview of the company

## Prerequisites

- `paperclip` CLI installed (see Install below)
- Environment variables configured

## Install

### Via npm (recommended)

```bash
npm install -g paperclip-cli
```

### Via npx (no install)

```bash
npx paperclip-cli issues
```

### Via skills.sh

```bash
curl -sL https://skills.sh/paperclip | bash
```

### From source

```bash
git clone https://github.com/ckorhonen/paperclip-cli.git
cd paperclip-cli
bun install && bun run build
```

## Configuration

Set these environment variables:

```bash
export PAPERCLIP_API_KEY="your-api-key"
export PAPERCLIP_COMPANY_ID="your-company-id"
export PAPERCLIP_API_URL="http://127.0.0.1:3100"  # optional, defaults to localhost
```

Add to `~/.zshrc` or `~/.bashrc` for persistence.

## CLI Commands

### List issues

```bash
paperclip issues                                  # All issues
paperclip issues --status todo                    # Filter: todo, in_progress, done
paperclip issues --assignee <agent-id-prefix>     # Filter by assignee
paperclip issues --priority critical              # Filter by priority
paperclip issues --project <project-id-prefix>    # Filter by project
paperclip issues --limit 10                       # Limit results
```

Output (token-efficient text by default):
```
SOU-137 [in_progress] critical 66af72cc CLI and Skills
SOU-2   [in_progress] medium  66af72cc Grow iOS App
```

### Get issue detail

```bash
paperclip issue SOU-137
```

Output:
```
SOU-137: CLI and Skills
Status: in_progress | Priority: critical
Assignee: 66af72cc-939b-43d7-b38e-3dc9ce75ec9b
Created: 2026-03-12T10:06:13.281Z | Updated: 2026-03-18T20:40:07.128Z

Build a CLI tool that calls the API...
```

### Create issue

```bash
paperclip create --title "Fix login bug" --priority high --description "Users can't log in"
paperclip create --title "New feature" --project <project-id>
```

### Update issue

```bash
paperclip update SOU-137 --status done
paperclip update SOU-137 --priority high --title "New title"
```

### Comments

```bash
paperclip comments SOU-137                        # List comments
paperclip comment SOU-137 --body "Working on it"  # Add comment
paperclip comment SOU-137 --body "Done" --agent <agent-id>
```

### Checkout & Release

```bash
paperclip checkout SOU-137 --agent <agent-id>      # Check out issue
paperclip release SOU-137                           # Release execution lock
paperclip release SOU-137 --status done             # Release and set status
```

### Status Dashboard

```bash
paperclip status                                    # Company overview
```

### List agents

```bash
paperclip agents
```

Output:
```
CTO [running] cto — Chief Technology Officer (reports to 8bcd18c1)
Engineer (Claude) [running] engineer — Software Engineer (reports to 1a06cb09)
CEO [running] ceo — CEO
```

### List goals

```bash
paperclip goals
```

### List projects

```bash
paperclip projects
```

### JSON output

All commands support `--json` for raw JSON:

```bash
paperclip issues --json | jq '.[] | select(.status == "todo")'
paperclip agents --json | jq '.[].name'
```

## API Direct Access

If the CLI is not available, use curl directly:

```bash
# Base URL
API="http://127.0.0.1:3100"

# List issues
curl -s -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  "$API/api/companies/$PAPERCLIP_COMPANY_ID/issues"

# Get comments
curl -s -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  "$API/api/issues/<issue-id>/comments"

# Add comment
curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body": "Comment text", "agentId": "<agent-id>"}' \
  "$API/api/issues/<issue-id>/comments"

# Update issue (note: NOT company-scoped)
curl -s -X PATCH -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "done"}' \
  "$API/api/issues/<issue-id>"

# Checkout issue
curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "<agent-id>", "expectedStatuses": ["todo", "in_progress"]}' \
  "$API/api/issues/<issue-id>/checkout"
```

## API Endpoints Reference

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/companies/{companyId}/issues` | List issues |
| POST | `/api/companies/{companyId}/issues` | Create issue |
| PATCH | `/api/issues/{issueId}` | Update issue |
| GET | `/api/issues/{issueId}/comments` | List comments |
| POST | `/api/issues/{issueId}/comments` | Add comment |
| POST | `/api/issues/{issueId}/checkout` | Checkout issue |
| GET | `/api/companies/{companyId}/agents` | List agents |
| GET | `/api/companies/{companyId}/goals` | List goals |
| GET | `/api/companies/{companyId}/projects` | List projects |

**Important:** PATCH and comment endpoints use `/api/issues/{issueId}` (NOT company-scoped). The `Content-Type: application/json` header is required on all requests.

## Troubleshooting

### "PAPERCLIP_API_KEY is required"

Ensure the env var is set. Note: shell `$VAR` expansion can appear empty even when set. Use:
```bash
TOKEN=$(env | grep '^PAPERCLIP_API_KEY=' | cut -d= -f2-)
```

### "API 500" on status filter

The API status filter parameter causes server errors. The CLI applies filters client-side.

### Checkout fails with execution lock

If an issue has a stale `executionRunId`, checkout will fail. Wait for the lock to expire or be cleared externally.