kraken

Kraken

You set the targets; the tentacles devour them. Unleash the Kraken.

One head, many tentacles — a task queue built on GitHub Issues where named agent workers (Claude Code, GitHub Copilot CLI, or any tool that follows the protocol) claim tasks, execute them, and record the evidence. Write the list once; the tentacles do the rest.

GitHub does the tracking. Your coding agent does the coding. Kraken is just the protocol between them — it ships nothing you have to operate.

In 30 seconds

What it is. A task queue for AI coding agents, where the queue is GitHub Issues in a private repo you own. You write tasks; named agent workers claim them one at a time, do the work in your prepared environment, and open draft PRs. You review and merge.

What you run.

/plugin marketplace add rafael-adcp/kraken
/plugin install kraken@kraken
/kraken:init OWNER/tasks --project my_app                 # once
/kraken:unleash OWNER/tasks --worker-name env-1 --project my_app

Launch that last line in N terminals and you have N workers. There is no server, no database, no daemon — the coordination state is issue labels plus a git ref, and the dashboard is the GitHub UI you already have.

Why it might be for you. You have more agent-sized tasks than attention: you're the bus between a task list and a row of terminals, and things get dropped. Kraken takes you out of that loop without moving your work off the machine where your services, data and credentials already live.

Why it might not be. If your code is on GitHub and the task needs nothing your platform doesn't already give it, Copilot's coding agent or claude-code-action in CI is less to run — see Why not just use X? for the honest cut.

Everything below is detail. The walkthrough is the next stop if you want to run it; PROTOCOL.md is the spec if you want to build a worker, and HISTORY.md is how that spec got the shape it has.

Why?

Kraken treats AI coding prompts the way a CI server treats builds: you push them onto a queue (GitHub Issues), a pool of named workers (tentacles) picks them up, and the issue timeline tells you what happened.

AI coding agents made each change cheap — but you are still the bus between the task list and the terminals. You can only watch so many spinners, juggle so many windows, and stay awake so many hours before something gets dropped. Kraken removes you from the loop and replaces infrastructure with things that already exist:

Concern	Kraken's answer
Queue & state	GitHub Issues in a private coordination repo you own
Claiming (no race)	Atomic compare-and-swap on a git ref — one creator wins, HTTP 422 to the rest
Dependencies	Native blocked-by relationships — closing a task unblocks
Parallelism	Capacity = how many workers you launch; 1 task per worker
Dead workers	The claim is a lease (30 min, renewed as you work); stop renewing and the next worker to read the queue takes the task over
Bad tasks	The issue form requires Goal + Acceptance; status reports what a worker still cannot start
Dashboard	The GitHub UI — filters, notifications, mobile app
Audit trail	The issue timeline: who, when, why, validated how

Work repos can live anywhere (GitHub, GitLab, private servers) — only the coordination repo needs to be on GitHub, and it holds issues, never code.

Wondering how this differs from Copilot's coding agent, Claude's cloud agents, or claude-code-action in CI? The honest side-by-side — including when to prefer them — is Why not just use X?.

Install

Both agents install from the same marketplace — Copilot CLI reads the Claude Code plugin format, so the same commands work.

Claude Code (plugin)

Zero to a draining queue in four commands:

/plugin marketplace add rafael-adcp/kraken
/plugin install kraken@kraken
/kraken:init OWNER/tasks --project my_app          # stand up the queue (once)
                                                   # ...file task issues, then:
/kraken:unleash OWNER/tasks --worker-name env-1 --project my_app

GitHub Copilot CLI

Same plugin, same commands — Copilot CLI reads the Claude Code plugin format and loads its three skills:

/plugin marketplace add rafael-adcp/kraken
/plugin install kraken@kraken

Each command in context — environments, permissions, parallelism — is the full walkthrough below.

Requirements: git, and a gh CLI from June 2026 or later — the dependency flags (--add-blocked-by / --blocked-by) shipped then. Older gh still works for everything else; set dependencies via the Relationships sidebar instead.

Three skills ship in the box:

Skill	Role
/kraken:init	The bootstrap — stands up a coordination repo: private repo, templates, canonical labels
/kraken:unleash	The worker — claims one task at a time, executes, validates, delivers a draft PR; then lurks behind a zero-token watcher
/kraken:status	The console — review + decision queues, what's in flight with PR links, and ready-to-paste unleash launch lines

Concepts

Five nouns do all the work in Kraken. Keep them straight and the rest follows:

Concept	What it is	What it is not	Lives on
Coordination repo	The kraken's head — a private repo whose Issues are the queue; also holds the labels (the state machine), the claim refs, and the dependency graph	A place for code — it holds none	GitHub (required)
Work repo	Where the code lives; workers push branches + open draft PRs here	The queue — it holds no tasks	Anywhere (GitHub, GitLab, private)
project:<name> label	A task's canonical identity — --project filters on it, and it says which prepared environment the task belongs to	Optional — a task without it is invisible to every worker	Coordination repo
Worker (tentacle)	A named agent session (Claude Code, Copilot CLI, ...) draining the queue one task at a time, inside one prepared environment	A pool — capacity is just how many you launch	Your machine / container / clone
Task	An open Issue labeled kraken-task (goal, acceptance, notes) that moves in-progress → awaiting-merge / needs-decision	Closed until the work truly lands — the merge closes it	Coordination repo

How it works (10,000 ft)

                     YOU
                      │ file kraken-task issues
                      ▼
    ┌────────────────────────────────────┐
    │  COORDINATION REPO (GitHub Issues) │
    │  labels · claim refs · dependencies│
    └──────────────────┬─────────────────┘
                       │ claim, renew, release
                       ▼
    ┌────────────────────────────────────┐
    │  TENTACLES (agent workers)         │
    │  ONE task at a time · per env      │
    └──────────────────┬─────────────────┘
                       │ push branch + draft PR
                       ▼
    ┌────────────────────────────────────┐
    │  WORK REPO (GitHub, GitLab, ...)   │
    │  draft PR with Kraken-Task trailer │
    └──────────────────┬─────────────────┘
                       │
                       ▼
                     YOU
                 (review · merge)

The label state machine

Four labels are the whole state machine — every transition is a label change, which is why the GitHub UI is the dashboard and the issue timeline is the log:

flowchart LR
    S((" ")) -->|you file the issue| Q["kraken-task (queued)"]
    Q -->|claim| P[in-progress]
    P -->|deliver — draft PR or analysis| M[awaiting-merge]
    P -->|blocking question| D[needs-decision]
    P -->|lease expires — the next reader steals it| Q
    D -->|you reply — the next reader requeues it| Q
    M -->|you reply — the next reader requeues it| Q
    M -->|PR merges — the task closes| E(((closed)))

Every requeue arrow lands the task back in the queue with its full thread — the next claim inherits the whole discussion as context.

Only two transitions are ever yours: answering a decision and merging (or bouncing) a PR. The tentacles drive everything else.

The coordination contract — task shape, state machine, the machine marker, the claim algorithm — is normatively specified in PROTOCOL.md (kraken-protocol/9); it is agent-agnostic, so any tool that follows it can be a tentacle on the same queue. How a worker executes it lives in skills/unleash/SKILL.md — a loop around kraken.py next-action, which answers "what do I do now" with a JSON envelope so the ordering rules are the program's job rather than something the agent has to remember. That makes the skill harness-neutral: the GitHub Copilot CLI worker reuses it through AGENTS.md with no deltas at all.

The full walkthrough

1. Create the coordination repo (once). Running the plugin? One command stands it all up — verifies or creates the private repo, installs the task template, deletes anything an earlier release installed to be executed server-side, and creates the canonical labels (idempotent, safe to re-run):

   /kraken:init OWNER/tasks --project YOUR_PROJECT_NAME
   

   One file. Under kraken-protocol/9 the coordination repo runs nothing — no workflows, and no vendored copy of the transition program for them to exec. Stale claims, an answered task's requeue and queue-entry validation are all derived by the reader, on the queue read a worker or status performs anyway (PROTOCOL.md §2.1, §6). You do not need GitHub Actions enabled on this repo at all.

   gh repo create OWNER/tasks --private --clone && cd tasks
   mkdir -p .github/ISSUE_TEMPLATE
   curl -sL https://raw.githubusercontent.com/rafael-adcp/kraken/main/skills/unleash/task-template.yml -o .github/ISSUE_TEMPLATE/task.yml
   git add -A && git commit -m "chore: kraken task template" && git push
   
   gh -R OWNER/tasks label create kraken-task
   gh -R OWNER/tasks label create in-progress
   gh -R OWNER/tasks label create needs-decision
   gh -R OWNER/tasks label create awaiting-merge
   gh -R OWNER/tasks label create priority:high                    # optional — jumps the startable queue
   gh -R OWNER/tasks label create "project:YOUR_PROJECT_NAME"      # one per project you'll queue
   

2. Queue the work: one issue per task (goal, acceptance, notes). Every issue gets a project:<name> label (workers are scoped to one project — an unlabeled task is invisible to all of them) and dependencies via gh issue edit <n> --add-label "project:YOUR_PROJECT_NAME" --add-blocked-by <m>. Add the optional priority:high label to jump a task to the front of the startable queue — workers claim high-priority tasks before older normal ones, with createdAt FIFO still ordering each tier.