Paperclip Bridge

Paperclip Bridge

Connect CC Commander workflows to Paperclip task management. Create issues from task-commander, track progress, auto-close tickets, and synchronize status bidirectionally between CC Commander sessions and Paperclip.

What Paperclip Is

Paperclip is a task management and agent coordination API running at localhost:3110. It manages issues, assignments, comments, and agent heartbeats across the OpenClaw fleet. All multi-step work routes through Neo (orchestrator) to Paperclip for tracking.

Core concepts:

• Issues — Tasks with status, priority, assignee, project, and comments
• Agents — AI workers that check out and execute issues via heartbeats
• Projects — Groupings for related issues (maps to CC Commander projects/workspaces)
• Heartbeats — Periodic wake cycles where agents check assignments and do work
• Comments — Threaded discussion on issues for progress tracking and handoffs

Status lifecycle: backlog -> todo -> in_progress -> in_review -> done (or blocked, cancelled)

1. Creating Issues from CC Commander Workflows

From task-commander

When CC Commander's task-commander skill creates a multi-step plan, bridge it to Paperclip:

curl -s -X POST http://localhost:3110/api/companies/${PAPERCLIP_COMPANY_ID}/issues \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${PAPERCLIP_API_KEY}" \
  -d '{
    "title": "Task from CC Commander: implement user auth",
    "description": "## Source\nCC Commander task-commander\n\n## Steps\n1. Design auth schema\n2. Implement JWT middleware\n3. Add login/register endpoints\n4. Write tests",
    "status": "todo",
    "priority": "high",
    "labels": ["bible-task", "task-commander"],
    "projectId": "'${PROJECT_ID}'",
    "assigneeAgentId": "'${AGENT_ID}'"
  }'

From spec-interviewer

When spec-interviewer produces a spec, create a parent issue with sub-tasks:

# 1. Create parent issue
PARENT=$(curl -s -X POST http://localhost:3110/api/companies/${PAPERCLIP_COMPANY_ID}/issues \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${PAPERCLIP_API_KEY}" \
  -d '{
    "title": "Spec: new billing system",
    "description": "From spec-interviewer. See tasks/spec-20260328.md",
    "status": "todo",
    "priority": "high",
    "labels": ["bible-spec", "spec-interviewer"]
  }' | jq -r '.id')

# 2. Create sub-tasks for each phase
curl -s -X POST http://localhost:3110/api/companies/${PAPERCLIP_COMPANY_ID}/issues \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${PAPERCLIP_API_KEY}" \
  -d '{
    "title": "Phase 1: Database schema migration",
    "parentId": "'$PARENT'",
    "status": "todo",
    "priority": "high",
    "labels": ["bible-spec"]
  }'

From mode-switcher

When switching CC Commander modes (e.g., entering saas mode for a feature sprint), optionally create a tracking issue:

curl -s -X POST http://localhost:3110/api/companies/${PAPERCLIP_COMPANY_ID}/issues \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${PAPERCLIP_API_KEY}" \
  -d '{
    "title": "CC Commander session: SaaS mode sprint",
    "description": "Mode: saas\nStarted: '$(date -u +%Y-%m-%dT%H:%M:%SZ)'\nGoal: Build subscription billing flow",
    "status": "in_progress",
    "priority": "medium",
    "labels": ["bible-session", "mode-saas"]
  }'

2. Priority Mapping

CC Commander workflows use informal priority language. Paperclip uses structured priority values.

Mapping from CC Commander Skills

3. Tracking Task Progress

Updating Issues from CC Commander Sessions

As you work through a task-commander plan, update the Paperclip issue:

# Mark as in-progress with a progress comment
curl -s -X PATCH http://localhost:3110/api/issues/${ISSUE_ID} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${PAPERCLIP_API_KEY}" \
  -d '{
    "status": "in_progress",
    "comment": "Step 2/4 complete: JWT middleware implemented and tested."
  }'

Progress Comment Format

When posting updates from CC Commander workflows, use this structure:

## CC Commander Progress Update

- **Skill:** task-commander
- **Step:** 2/4
- **Status:** In progress
- **Done:** JWT middleware implemented, unit tests passing
- **Next:** Login/register endpoints
- **Blockers:** None

Automated Progress via Hook

The openclaw-adapter.js hook can forward tool events to Paperclip. When KZ_PAPERCLIP_TRACKING is set to an issue ID, each significant tool call (file writes, test runs, git commits) appends a lightweight progress entry:

export KZ_PAPERCLIP_TRACKING="issue-uuid-here"

4. Auto-Closing Tickets

When CC Commander Tasks Complete

After task-commander marks all steps done, or after verification-loop passes:

curl -s -X PATCH http://localhost:3110/api/issues/${ISSUE_ID} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${PAPERCLIP_API_KEY}" \
  -d '{
    "status": "done",
    "comment": "## Completed\n\n- All steps executed\n- Tests passing (Vitest: 42/42)\n- No TypeScript errors\n- Committed: feat: add user auth (abc1234)"
  }'

Auto-Close Conditions

Guard: Never Auto-Close

• Issues with blocked status (requires human intervention)
• Issues with open sub-tasks (parent stays open)
• Issues assigned to a different agent (not yours to close)
• Issues in in_review status (waiting for human review)

5. Bidirectional Sync Patterns

CC Commander to Paperclip (Push)

Paperclip to CC Commander (Pull)

Sync Cadence

• Real-time push: Every significant CC Commander event fires immediately
• Periodic pull: Check assignments at session start and every 30 tool calls
• On-demand: User can run /paperclip to check status manually

6. REST API Quick Reference

All endpoints relative to http://localhost:3110. All requests use Authorization: Bearer $PAPERCLIP_API_KEY. All bodies are JSON.

Issues

Comments

Agents

Projects

Checkout / Release

Dashboard

Search

# Full-text search across titles, descriptions, comments
GET /api/companies/:companyId/issues?q=auth+middleware&status=todo,in_progress

7. Webhook Integration

Paperclip to CC Commander Notifications

Paperclip can send webhooks when issues change. Configure in Paperclip settings:

{
  "webhooks": [{
    "note": "Gateway has no HTTP webhook endpoints - use openclaw CLI instead",
    "events": ["issue.status_changed", "issue.assigned", "issue.commented"],
    "secret": "shared-secret-here"
  }]
}

Webhook Payload Format

{
  "event": "issue.status_changed",
  "timestamp": "2026-03-28T12:00:00.000Z",
  "issue": {
    "id": "uuid",
    "identifier": "PAP-142",
    "title": "Implement user auth",
    "status": "in_progress",
    "previousStatus": "todo",
    "priority": "high",
    "assigneeAgentId": "codex"
  }
}

Consuming Webhooks in CC Commander Hooks

The openclaw-adapter.js hook can optionally listen for Paperclip webhook events when forwarded through the OpenClaw gateway. Events with source: "paperclip" are logged but do not modify Claude Code behavior directly — they surface as informational stderr messages when KZ_OPENCLAW_DEBUG=1.

8. Labels and Categories

CC Commander Skill to Paperclip Label Mapping

Auto-Labeling Rules

When creating issues from CC Commander workflows, apply labels automatically:

1. Always add cc-task to any CC Commander-originated issue
2. Add the source skill label (e.g., bible-spec for spec-interviewer)
3. Add mode label if a mode is active (e.g., mode-saas)
4. Add bible-security for any security-related skill
5. Never exceed 5 labels per issue — prioritize specificity

9. Dashboard Integration

Paperclip Dashboard to CC Commander Status

The Paperclip dashboard at http://localhost:3110 shows all issues, agent activity, and project health. CC Commander-originated issues are identifiable by their cc-* labels.

CC Commander Dashboard Widget Data

Pull dashboard data for display in CC Commander status reports:

# Get dashboard summary
DASHBOARD=$(curl -s http://localhost:3110/api/companies/${PAPERCLIP_COMPANY_ID}/dashboard \
  -H "Authorization: Bearer ${PAPERCLIP_API_KEY}")

# Extract CC Commander-specific metrics
echo "$DASHBOARD" | jq '{
  total_bible_issues: [.issues[] | select(.labels[] | contains("bible"))] | length,
  open: [.issues[] | select(.labels[] | contains("bible")) | select(.status == "todo" or .status == "in_progress")] | length,
  done_today: [.issues[] | select(.labels[] | contains("bible")) | select(.status == "done")] | length,
  blocked: [.issues[] | select(.labels[] | contains("bible")) | select(.status == "blocked")] | length
}'

Status Report Format

## Paperclip CC Commander Status — YYYY-MM-DD

| Metric | Count |
|--------|-------|
| Open CC Commander issues | X |
| In progress | X |
| Blocked | X |
| Completed today | X |
| Total tracked | X |

### Active Issues
| ID | Title | Status | Priority | Agent |
|----|-------|--------|----------|-------|
| PAP-142 | User auth | in_progress | high | codex |

10. Setup

Prerequisites

• Paperclip running at localhost:3110
• PAPERCLIP_API_KEY and PAPERCLIP_COMPANY_ID environment variables set
• curl and jq available

Configuration

# Add to shell profile
export PAPERCLIP_API_URL="http://localhost:3110"
export PAPERCLIP_COMPANY_ID="your-company-id"
export PAPERCLIP_API_KEY="your-api-key"

# Optional: auto-track CC Commander sessions
export KZ_PAPERCLIP_TRACKING=""  # Set to issue ID to enable per-session tracking

Verify Connection

# Health check
curl -s http://localhost:3110/api/health

# Test authentication
curl -s http://localhost:3110/api/agents/me \
  -H "Authorization: Bearer ${PAPERCLIP_API_KEY}"

# List recent issues
curl -s "http://localhost:3110/api/companies/${PAPERCLIP_COMPANY_ID}/issues?limit=5" \
  -H "Authorization: Bearer ${PAPERCLIP_API_KEY}" | jq '.[] | {id, title, status}'

Troubleshooting

Connection Refused

Symptom: curl to localhost:3110 fails
Fix: Check PM2 — `pm2 list | grep paperclip`
     Restart if needed — `pm2 restart paperclip`
     Check logs — `pm2 logs paperclip --lines 20 --nostream`

Authentication Failures (401)

Symptom: API returns 401 Unauthorized
Fix: Verify PAPERCLIP_API_KEY is set and valid
     For heartbeat runs, check PAPERCLIP_RUN_ID header
     Regenerate key if expired — see Paperclip admin

Issue Creation Failures

Symptom: POST /api/issues returns 400
Common causes:
  - Missing required field (title)
  - Invalid status value (must be: backlog, todo, in_progress, in_review, done, blocked, cancelled)
  - Invalid priority value (must be: critical, high, medium, low)
  - Non-existent projectId or parentId
  - Non-existent assigneeAgentId

Stale Tracking Issue

Symptom: KZ_PAPERCLIP_TRACKING points to a closed/cancelled issue
Fix: Unset the variable — `unset KZ_PAPERCLIP_TRACKING`
     Or set to a new issue ID for the current session

Missing Labels

Symptom: CC Commander labels not appearing on issues
Fix: Labels are created on first use in Paperclip
     Ensure label names match exactly (case-sensitive)
     Check that label array in POST body is formatted correctly