Claude-skills 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.

install

source · Clone the upstream repo

git clone https://github.com/ckorhonen/claude-skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/ckorhonen/claude-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/paperclip" ~/.claude/skills/ckorhonen-claude-skills-paperclip && rm -rf "$T"

manifest: skills/paperclip/SKILL.md

source content

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

~/.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.