WoterClip

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

Get the persona starter pack → https://alexk1919.gumroad.com/l/woterclip-persona-pack

How It Works

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

1. Issues live on GitHub 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 GitHub 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
• GitHub CLI installed and authenticated:

  brew install gh   # or your platform's equivalent
  gh auth login
  

• A GitHub repository with Issues enabled
• Issues assigned to your GitHub account (the heartbeat queries --assignee @me)

No MCP server is required – all GitHub operations go through the gh CLI, so scheduled heartbeats work headlessly.

Note on notifications: the agent posts comments as whatever account gh is authenticated as, and GitHub never notifies a user of their own comments. If you authenticate gh with your personal account (the common setup), blocked-escalation @-mentions won't notify you – watch the repo or check /woterclip-status. A separate bot/machine account for gh auth gives you real mention notifications.

Quick Start

# 1. Initialize WoterClip in your repo (creates config + personas + GitHub 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 GitHub for assigned open issues, filter and sort
3. Pick issue – in-progress labeled first, then the rest, by priority label
4. Resolve persona – match issue label → persona directory, load SOUL.md + TOOLS.md
5. Validate tools – check required tools are available (gh auth status)
6. Lock issue – add agent-working label
7. Understand context – read issue, comments, parent, heartbeat counter
8. Do work – dispatch a persona subagent on the persona's configured model (inline fallback, disclosed in the report, when dispatch is unavailable)
9. Report – post structured comment with progress, commits, sub-issues
10. Update state – manage labels based on the returned outcome (completed / in progress / blocked / triaged / decomposed)
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