WoterClip v0.2.0: GitHub Issues replaces Linear

Last updated: July 10, 2026

TL;DR

WoterClip v0.2.0 replaces its Linear backend with GitHub Issues. The plugin now talks to GitHub through the gh CLI – no MCP server, no external tracker, no separate subscription. Scheduled heartbeats run headless, your agent's inbox lives in the same repo as your code, and a v1 (Linear) config migrates by re-running /woterclip-init. The swap looked mechanical. The interesting part is where it wasn't: tracker concepts that don't map 1:1 fail silently, not loudly.

What changed in v0.2.0

WoterClip is a Claude Code plugin that turns an issue tracker into the control plane for your coding agent: issues carry persona labels, a /heartbeat picks up the highest-priority issue, the matching persona does the work, and a structured comment reports back. Since the original release, that tracker was Linear.

As of v0.2.0, it's GitHub Issues:

Everything else carries over: personas with SOUL.md identities, the CEO/Orchestrator split, the Board (you) as the final escalation target, and the 11-step heartbeat loop. The release also adopts GitHub Releases with label-categorized notes, so v0.2.0 onward reads as a proper changelog.

Why GitHub Issues

Three reasons, in order of how much they actually drove the decision.

Scheduled heartbeats can't depend on MCP. The whole point of WoterClip is /schedule 30m /heartbeat – the agent checks its inbox while you do something else. But Linear access ran through an MCP server that authenticates interactively, and an interactively-authenticated server may simply be absent in a headless, scheduled run – the agent loses its inbox exactly when nobody is watching. The gh CLI authenticates once with gh auth login and works in every context after that. Tool validation collapsed to a single check: gh auth status exits 0.

Issues belong next to the code. I've been moving issue tracking off Linear and onto GitHub Issues across my projects over the past month. When the agent's work item, the code it changes, the PR that ships it, and the comment trail all live in one system, Closes #42 in a commit body closes the loop – literally. One less tab, one less integration, one less subscription.

The gh CLI is the cleanest agent surface on any tracker. Every operation an agent needs – list, view, edit, comment, close, label, sub-issue – is a composable command with --json output. No SDK, no token juggling, no rate-limit dance through a third-party wrapper. If you're building agent workflows on GitHub, gh is the integration surface.

The mapping looked mechanical. The bugs were semantic

Every reviewer pass on the swap PR confirmed the same thing: most of this migration is find-and-replace. The bugs that survived into review all came from one root cause – concepts that don't map 1:1 between trackers fail silently, not loudly.

The biggest semantic gap is state. Linear has six workflow states. GitHub issues are open or closed, full stop. WoterClip collapses the difference into status labels:

The split that matters: agent-written labels (agent-working, agent-blocked, in-progress) are required infrastructure and get created unconditionally at init. Human-written ones (backlog, todo) are optional. Priority loses precision – Linear's four levels become priority:high / none / priority:low – and the mapping doc says so out loud instead of pretending otherwise.

One mapping actually improved. Linear label updates are a read-modify-write dance on a full array, which can clobber concurrent edits. GitHub's gh issue edit N --add-label X --remove-label Y is atomic per call. The state machine keeps its rules; the write primitive got safer.

Five gh facts that will bite your agent

These came out of the review on #1 and are now baked into WoterClip's reference docs. If you're wiring any agent to GitHub Issues, check your prompts against this list.

1. gh api -f sends strings; -F sends typed values. The sub-issues endpoint requires an integer sub_issue_id, so -f sub_issue_id=$id returns a 422. Every gh api write with a non-string parameter needs -F.
2. Sub-issues attach by issue ID, not issue number. Query --jq .id first, then attach. The two values diverge wildly on repos with history, so code that confuses them works on a toy repo and fails on a real one.
3. GitHub does not auto-assign issue creators. Any inbox built on --assignee @me must pass --assignee @me at creation, or decomposed sub-issues silently vanish from the agent's queue.
4. gh issue edit --add-label never creates labels. It errors on labels that don't exist. Every label an agent writes has to be created at init time.
5. GitHub never notifies you of your own comments. If gh is authenticated as you (the common setup), the agent's @-mention escalations won't ping you. Use a separate bot account for gh auth, or watch the repo.

The migration that almost blocked everything

The biggest catch of the review wasn't in the runtime code at all. A config-schema migration is not done when the config file migrates.

The v1-to-v2 migration originally carried persona directories over unchanged. But v1 persona configs pin required_tools: [mcp__claude_ai_Linear] – an MCP tool prefix that the new validation treats as an unavailable executable. The result would have been an apparently successful migration that auto-blocks every single issue on the next heartbeat.

The rule that came out of it: when a migration changes what a config value means (here, required_tools entries went from MCP prefixes to executables like gh), sweep every scaffolded file that carries such values, and add a post-migration check that greps for the old vocabulary. The full write-up lives in the repo's solutions doc.

Migrating a v1 config

If a repo has a version: 1 config with a linear: section, re-run /woterclip-init. It detects the old schema and migrates:

1. Your GitHub login replaces the Linear display name – it asks, because they're not the same string, and guessing wrong would @-mention a stranger.
2. The repo (owner/name) replaces the Linear team, derived from the checkout.
3. Labels are recreated on GitHub, flat (no label groups).
4. Persona required_tools swap from MCP prefixes to gh.

Linear issue data is not migrated – open issues stay in Linear, and you recreate the ones that still matter as GitHub issues. Treat that as a filter: an issue you wouldn't bother recreating by hand probably didn't deserve the agent's time either.

What didn't change

The parts of WoterClip that earn its keep are untouched. Personas are still directories with SOUL.md, TOOLS.md, and config.yaml. The Orchestrator still triages unlabeled issues on a cheap model before a worker persona touches them. Blockers still escalate to the Board instead of waiting for you to notice. And the plugin is still markdown and YAML all the way down – zero runtime code, zero infrastructure, and now zero external services beyond the place your code already lives.

The swap itself ran through the compound engineering pipeline as issue #1 in WoterClip's own repo: brainstorm, plan, safety-critical review, compound learnings doc. The plugin now dogfoods its own tracker.

Getting started

In Claude Code: /plugin → Add Marketplace → wotai-dev/woterclip, then install. You'll need the GitHub CLI installed and authenticated (gh auth login) and a repo with Issues enabled. Then:

/woterclip-init      # config + personas + GitHub labels
/heartbeat           # one cycle
/schedule 30m /heartbeat   # recurring

Frequently asked questions

What is WoterClip?

WoterClip is an open-source Claude Code plugin for agent orchestration. GitHub issues carry persona labels, a scheduled /heartbeat picks the highest-priority issue, the matching persona (CEO, backend, frontend) does the work, and a structured comment reports back. It's markdown and YAML – no server, no database.

Why did WoterClip switch from Linear to GitHub Issues?

Three reasons: scheduled heartbeats need to run headless and the gh CLI works where interactively-authenticated MCP servers don't; issues, code, PRs, and comments now live in one system; and dropping Linear removes the last external service dependency.

Does WoterClip still support Linear?

No. v0.2.0 replaces the Linear backend entirely. A version: 1 config migrates to the GitHub schema by re-running /woterclip-init. Linear issue data is not migrated – recreate the issues that still matter on GitHub.

Do I need the GitHub MCP server?

No. All GitHub operations go through the gh CLI, which is the point: scheduled, headless heartbeats work without any MCP server present. The only requirements are gh installed and gh auth status passing.

How does WoterClip represent Linear's workflow states on GitHub?

GitHub issues are only open or closed, so the six Linear states collapse to open/closed plus status labels: backlog, todo, in-progress, and in-review. Agent state labels (agent-working, agent-blocked) are created at init and managed by the heartbeat.

How does priority work without a native priority field?

Through labels: priority:high, none, and priority:low. That's three levels instead of Linear's four – a real precision loss the mapping accepts and documents rather than papering over.

What happens to sub-issues?

WoterClip uses GitHub's native sub-issues through the REST API. Two traps: sub-issues attach by issue ID (not issue number), and gh api needs -F for the integer parameter. The agent also assigns sub-issues explicitly, because GitHub never auto-assigns creators.

Will the agent's escalation @-mentions notify me?

Only if gh is authenticated as a different account than yours. GitHub never notifies you of your own comments, so the common single-account setup means no pings. A separate bot account for gh auth gives you real mention notifications.

WoterClip is MIT-licensed and open source: github.com/wotai-dev/woterclip. If you're running Claude Code agents against real issue queues, the WotAI Skool community (760+ builders) is where I share what breaks and what ships. For the weekly version in your inbox, subscribe to the newsletter.