paperclip

Paperclip

概述

通过 Claude Code 管理你的 Paperclip Agent 公司。列出和更新问题、协调 Agent、跟踪目标和项目、添加评论，并领取任务以执行。

适用场景

• 列出、创建或更新问题／任务
• 领取问题以供 Agent 执行
• 查看 Agent 状态和分配情况
• 跟踪公司目标和项目进度
• 为问题添加评论
• 快速查看公司的状态概览

前提条件

• 已安装 paperclip CLI（见下方安装说明）
• 已配置环境变量

安装

通过 npm（推荐）

npm install -g paperclip-cli

通过 npx（无需安装）

npx paperclip-cli issues

通过 skills.sh

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

从源代码安装

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

配置

设置以下环境变量：

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

将其添加到 ~/.zshrc 或 ~/.bashrc，以便持久生效。

CLI 命令

列出问题

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

输出（默认采用节省令牌的文本格式）：

SOU-137 [in_progress] critical 66af72cc CLI and Skills
SOU-2   [in_progress] medium  66af72cc Grow iOS App

获取问题详情

paperclip issue SOU-137

输出：

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

创建问题

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

更新问题

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

评论

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>

领取和释放

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

状态仪表板

paperclip status                                    # Company overview

列出 Agent

paperclip agents

输出：

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

列出目标

paperclip goals

列出项目

paperclip projects

JSON 输出

所有命令都支持 --json，以输出原始 JSON：

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

直接访问 API

如果 CLI 不可用，可直接使用 curl：

# 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 端点参考

方法	路径	描述
GET	/api/companies/{companyId}/issues	列出问题
POST	/api/companies/{companyId}/issues	创建问题
PATCH	/api/issues/{issueId}	更新问题
GET	/api/issues/{issueId}/comments	列出评论
POST	/api/issues/{issueId}/comments	添加评论
POST	/api/issues/{issueId}/checkout	领取问题
GET	/api/companies/{companyId}/agents	列出 Agent
GET	/api/companies/{companyId}/goals	列出目标
GET	/api/companies/{companyId}/projects	列出项目

重要： PATCH 和评论端点使用 /api/issues/{issueId}（而非按公司限定的路径）。所有请求都必须包含 Content-Type: application/json 标头。

故障排除

“PAPERCLIP_API_KEY is required”

请确保已设置该环境变量。注意：即使变量已设置，Shell 的 $VAR 展开结果也可能为空。请使用：

TOKEN=$(env | grep '^PAPERCLIP_API_KEY=' | cut -d= -f2-)

按状态筛选时出现“API 500”

API 的状态筛选参数会导致服务器错误。CLI 会在客户端应用筛选。

领取时因执行锁而失败

如果问题的 executionRunId 已过期，领取操作会失败。请等待锁过期，或通过外部方式清除锁。