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, Pi, 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:

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

Claude Code and Copilot CLI install from the same marketplace — Copilot CLI reads the Claude Code plugin format, so the same commands work. Pi has no plugin marketplace: it loads the same skills straight from a kraken checkout.

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

Then launch a worker from the work repo's checkout. Copilot takes its unattended permissions as launch flags rather than from a settings file, so two scripts in a kraken checkout carry them for you — the same flags, from one source:

cd /path/to/my_app
/path/to/kraken/scripts/kraken-copilot.sh OWNER/tasks --worker-name env-1 --project my_app   # interactive
/path/to/kraken/scripts/kraken-loop.sh    OWNER/tasks --worker-name env-1 --project my_app   # headless

kraken-copilot.sh opens a Copilot session running /kraken:unleash that stays in ambush and that you can talk to; kraken-loop.sh runs one copilot -p per startable task, with no session to watch.

Pi

Clone kraken and point Pi at the checkout's skills/ — in ~/.pi/agent/settings.json, or per run with --skill /path/to/kraken/skills:

{
  "skills": ["/path/to/kraken/skills"],
  "extensions": ["/path/to/kraken/extensions/pi/kraken.ts"],
  "defaultTools": ["+grep", "+find", "+ls"]
}

• Point at the checkout, never at a copy. kraken.py finds the plugin manifest and PROTOCOL.md two levels above its skill folder. A copied skills/ tree stamps every delivered commit kraken@unknown, and kraken.py contract boundary — the rules a worker asks for — prints nothing. Check out a release tag to pin a version, the way the plugin is pinned.
• Mind the +. Pi's default tools are read, bash, edit and write; +name adds one, while a plain name replaces the defaults — so ["grep", "find", "ls"] would leave the worker unable to edit or deliver.
• The extensions entry is optional. It loads kraken's Pi extension, which does for Pi what hooks.json does for the other two: hands the session's claim back when the session ends (only that session's — kraken.py claim records Pi's PI_SESSION_ID), and refuses gh pr merge, gh repo delete and gh issue close in the bash tool. Pi compiles it on load; nothing to build. The loop loads it on its own (-e), so this entry matters for the sessions you start yourself. Without it a worker still conforms — an abandoned claim frees itself within one lease TTL.
• Pick a model provider other than a Claude plan's OAuth. Pi on Anthropic OAuth is billed as extra usage, not against your plan limits — Anthropic answers 400 invalid_request_error: "Third-party apps now draw from your extra usage, not your plan limits.". Use an API key or another provider (OpenAI works).

The skills are /skill:init, /skill:unleash and /skill:status in Pi — the prefix belongs to the harness, the arguments are the same. A worker runs headless through the loop, from the work repo's checkout:

cd /path/to/my_app
/path/to/kraken/scripts/kraken-loop.sh OWNER/tasks --worker-name env-1 --project my_app --harness pi

Deny rules, in two halves. What Copilot denies with --deny-tool, a Pi worker under the loop refuses this way: the GitHub MCP server's merge_pull_request and issue_write tools are excluded whole (--exclude-tools 'mcp__*__merge_pull_request,mcp__*__issue_write'), and the extension refuses gh pr merge, gh repo delete and gh issue close inside the single bash tool. That second half matches the command's words (extensions/pi/deny.py) — it catches cd x && GH_TOKEN=… gh pr merge 1 --admin but not a variable, eval, a script or gh api; it is defense in depth, not a sandbox. Protect the work repo's default branch, and run Pi workers in an isolated environment (see step 3).

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

Requirements: git, python3 (every transition runs through the bundled kraken.py), 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:

Concepts

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

How it works (10,000 ft)