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)

npm install -g paperclip-cli

Via npx (no install)

npx paperclip-cli issues

Via skills.sh

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

From source

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

Configuration

Set these environment variables:

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

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

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

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

Update issue

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

Comments

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

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

paperclip status                                    # Company overview

List agents

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

paperclip goals

List projects

paperclip projects

JSON output

All commands support --json for raw JSON:

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

API Direct Access

If the CLI is not available, use curl directly:

# 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:

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.