WoterClip

Linear-backed agent orchestration for Claude Code. A single Claude instance wears different "hats" (personas) based on Linear issue labels – an Orchestrator routes work, a CEO makes strategic calls, and worker personas execute.

How It Works

Linear Issues → /heartbeat → Persona Matching → Work → Report Back

1. Issues live in Linear with persona labels (backend, frontend, etc.)
2. Heartbeat picks the highest-priority issue and resolves which persona handles it
3. Personas (CEO, Backend, Frontend, ...) define identity, tools, and runtime config
4. Reports are structured comments on the Linear issue with progress, commits, and blockers
5. Schedule runs heartbeats automatically via Claude Code's /schedule

The human is the Board – the ultimate escalation target when the agent is blocked.

Install

In Claude Code, run /plugin → Add Marketplace → enter wotai-dev/woterclip, then install the plugin.

Or for local development:

git clone https://github.com/wotai-dev/woterclip.git
claude --plugin-dir /path/to/woterclip

Prerequisites

• Claude Code installed
• Linear MCP connected – add to your .mcp.json or global MCP config:

  {
    "mcpServers": {
      "linear": {
        "type": "url",
        "url": "https://mcp.linear.app/sse"
      }
    }
  }
  

• Linear workspace with at least one team
• Issues assigned to your Linear account (the heartbeat queries assignee: "me")

Quick Start

# 1. Initialize WoterClip in your repo (creates config + personas + Linear labels)
/woterclip-init

# 2. Run a single heartbeat cycle
/heartbeat

# 3. Or schedule recurring heartbeats
/schedule 30m /heartbeat

# 4. Check status
/woterclip-status

The Heartbeat Loop

Each /heartbeat runs an 11-step cycle:

1. Load config – read .woterclip/config.yaml, check lockfile
2. Check inbox – query Linear for assigned issues, filter and sort
3. Pick issue – highest priority In Progress, then Todo
4. Resolve persona – match issue label → persona directory, load SOUL.md + TOOLS.md
5. Validate tools – check required MCP tools are available
6. Lock issue – add agent-working label
7. Understand context – read issue, comments, parent, heartbeat counter
8. Do work – follow persona instructions (CEO triages, workers implement)
9. Report – post structured comment with progress, commits, sub-issues
10. Update state – manage labels based on outcome (done/blocked/continuing)
11. Next or exit – pick another issue or clean up and stop

Use --dry-run to see what would be picked without doing work. Use --persona backend to force a specific persona.

Personas

Each persona gets its own directory with three files:

Default Personas

Create custom personas with /persona-create or copy directories between repos.

Per-Repo Structure

After /woterclip-init, your repo gets:

.woterclip/
├── config.yaml              # Linear settings, heartbeat behavior, persona routing
├── heartbeat-log.jsonl      # Append-only heartbeat history (created at runtime)
└── personas/
    ├── orchestrator/
    │   ├── SOUL.md
    │   ├── TOOLS.md
    │   └── config.yaml
    ├── ceo/
    │   ├── SOUL.md
    │   ├── TOOLS.md
    │   └── config.yaml
    ├── backend/
    │   ├── SOUL.md
    │   ├── TOOLS.md
    │   └── config.yaml
    └── frontend/
        ├── SOUL.md
        ├── TOOLS.md
        └── config.yaml

Commands

Label System

WoterClip uses Linear labels for state management:

All labels live under a "WoterClip" parent group in Linear, created by /woterclip-init.

Schedule Cadences

Migrating from Paperclip

Use /persona-import to convert Paperclip agent directories into WoterClip personas. It maps SOUL.md, TOOLS.md, HEARTBEAT.md role-specific sections, and AGENTS.md safety rules into the WoterClip format. Budget tracking, PARA memory, and approval workflows are not imported (replaced by Claude Code built-in features or intentionally omitted from v1).

Background

WoterClip is inspired by Paperclip, an agent orchestration platform that uses a central API for task management, agent checkout, and chain-of-command routing. WoterClip takes the same core ideas – persona-based identity, structured heartbeats, hierarchical escalation – and rebuilds them as a Claude Code plugin backed by Linear instead of a custom API. The result is simpler (no server, no database, no separate processes) while keeping the parts that worked well: SOUL.md for agent identity, structured comments for audit trails, and a CEO/worker hierarchy for task decomposition.

Design

See docs/specs/2026-03-25-woterclip-design.md for the full design spec and docs/specs/2026-03-25-woterclip-implementation-plan.md for the build order.

License

MIT