Agent skill

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.

View SKILL.md on GitHub Repository
Stars 2
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/ckorhonen/claude-skills/tree/main/skills/paperclip

SKILL.md

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.

Didn't find tool you were looking for?

Be as detailed as possible for better results