Plugin

The plugin connects a Claude Code session to your Kairoku workspace over MCP with OAuth browser sign-in — no pasted tokens — and ships the skills and the role agents that follow the delivery protocol.

Install

The quick path is the Kairoku CLI, which registers the marketplace and installs the plugin through the claude CLI without prompts:

curl -fsSL https://gitlab.com/owds-inc/releases/kairoku/distribution/-/raw/main/install.sh | sh   # mac or linux
kairoku setup --plugin

kairoku plugin update picks up new plugin releases, and kairoku plugin status says what is installed.

The manual path is two slash commands in a Claude Code session — the plugin is published from the public distribution project on GitLab, which is also its marketplace:

/plugin marketplace add https://gitlab.com/owds-inc/releases/kairoku/distribution.git
/plugin install kairoku@kairoku-marketplace

Either way, then /mcp → kairoku → Authenticate for the browser sign-in. The only configuration key is the Kairoku API URL and it defaults to https://api.kairoku.io, so a fresh install prompts for nothing.

If you registered the marketplace from the old GitHub source owds-inc/kairoku, re-point it: claude plugin marketplace remove kairoku-marketplace, then either path above. kairoku doctor warns while the old source is registered.

The plugin also carries a SessionStart hook that prints one orientation line when a session opens on an epic (mvp/*) or story (story/*, fix/*) branch. It reads local git only and prints nothing anywhere else.

The skills

Nine skills ship with the plugin. Six are commands you invoke; three are protocol the agent loads as background knowledge and never announces.

User-invocable

/kairoku:operator — drive one project end to end through the app's MCP tools instead of clicking: start a project, link its repo, seed its documents, draft a plan, open a release, dispatch work to a machine, watch it run, and ask a person to ship it. Approval-class steps are requested and waited on with get_ask, never claimed. See the operator agent below and Operator.
/kairoku:plan — take an idea from a rough thought to a pushable plan inside the app: a short one-question-at-a-time interview, a spec document, then phases and items written with upsert_plan. Agents never create Jira issues for plan structure; the human pushes the plan out of the app.
/kairoku:next — where the project stands and the single thing to do now, answered from the app's live plan and release gates. One question, one answer — not a status report, not a backlog.
/kairoku:intake — talk an idea or a direction change through to exactly one next step: which open release it belongs in, then a vision amendment, a handoff to /kairoku:plan, or a parked note.
/kairoku:continuity — hand this session's working state to the one that replaces it: branch, full commit SHAs, the test command with its counts, in-flight plan item ids and open decisions, written as one document in Kairoku, plus the short prompt to paste into the fresh session.
/kairoku:wrap — close a working session: one line on the dashboard via add_progress_note, plus the item statuses that actually changed.

Background protocol (not commands — the agent reads these to know how to behave)

jira-ops — the Jira lifecycle every Kairoku agent follows: discover transitions rather than hardcode them, who moves which issue when, how to close testing subtasks with evidence, how to block a story without stalling its epic.
git-pr — branch, commit, merge and pull-request conventions: one branch per story, an integration branch per epic, issue-key-first commits, wave merges, PR bodies built from the epic's own stories.
kairoku-mcp — how agents read from and write back to the app: which tool to use for what, how to report progress without spamming the activity log, and which writes belong to the app rather than to the agent.

The operator agent

The plugin also ships a dedicated operator subagent that follows the kairoku:operator skill's playbook step by step, with the kairoku-mcp skill alongside it for which tool to use for what. Invoke it by name — the same way you would reach for any Claude Code subagent — to hand it a whole project rather than running /kairoku:operator in your own session. It runs on Opus at high effort with a 400-turn ceiling, the same allowance as the planner role below, because a bootstrap-to-ship run is long: planning, a dispatch, polling, and waiting on approvals.

It reads before it writes (get_project, get_plan, get_operations), treats a tool result as the only proof something happened, and stops to hand back to you after two refusals on the same step rather than guessing. Exactly like every other agent on MCP, an approval_required result means a person decides — it names which card to open in Kairoku and waits with get_ask, and it never asks you to paste an approval back to it.

The four role agents

These are the roles a dispatched team runs. They are ordinary Claude Code subagents, so you can also invoke them by hand in a session.

Agent	What it does	What it never does
`implementer`	Builds exactly one plan item end to end from its six-section body: tests first from its Test notes, implementation to green, the repository's own checks clean, one branch, one pull request, honest status	Picks its own work · verifies its own work · marks an item done
`reviewer`	Reads a finished item against the diff on its branch, requirement by requirement, re-runs the instruments the implementer claimed, and returns one structured verdict — `CLEAN` or `NOT_CLEAN` with defects	Edits · fixes · merges
`planner`	Turns an ask into a plan the app can hold — phases, and items with the six-section body — without an interview, and sets needs manual check on every item whose test notes describe something a person has to look at	Runs a shell
`researcher`	Answers one question from primary sources and files one draft document with every claim cited	Runs a shell · edits files

Under a dispatched run, all four read the repository before their first write. The daemon prepends its own copy of each role's contract to every prompt, on both providers, and each of the four says to read AGENTS.md (or CLAUDE.md) at the root and .kairoku/patterns.md when it exists — the exemplar snippets that say what shape this repository actually wants, as opposed to the shape that merely compiles. A role may change patterns.md only when the item it was given is what changes it; a pattern worth recording but outside that scope goes in its report instead, and the reviewer treats any other edit to the file as a defect. One writer per resource, and the human merge is the gate on what a repository says about itself. The plugin's own implementer and reviewer definitions carry the same instruction, so it holds when you invoke those two by hand as well.

implementer inherits the launching session's full tool set deliberately: a restricted tool list silently drops the MCP servers it needs, leaving it unable to reach Jira or Kairoku at all. Under a dispatched run the real tool policy is enforced by the daemon with a PreToolUse hook rather than by frontmatter — a reviewer gets read and run and no write tool at all — and every denial is recorded as an event.

What is still the human's click

The plugin's kairoku-mcp skill carries this table, and the app enforces it. Authoring happens in Kairoku through the write tools; what the server does not expose is anything that fires the app's outbound sync — and that omission is deliberate.

Still manual	Why
Creating a project or release	Quick capture is the app's front door, and stage is a human judgment
Push plan → Jira (Sync tab)	The only writer that creates sync mappings. No `push_plan` tool exists
Publish document → Confluence	Same: the publish path is what records the page mapping
Changing a release stage	A gate, not a status
The Done transition on a plan item	Done comes from a person — a merge marks the run merged, not the item done. `update_item_status` refuses `done` from an agent credential and answers with an error; `in_progress` and `blocked` are yours. An item with needs manual check set is put in front of a person on the Floor once its pull request merges
Merging a pull request	A non-human identity never approves, verifies or releases its own work

So the shape is: agents write into Kairoku, the human pushes out of it.

Codex

Codex installs the same plugin from the same marketplace; its own manifest names the MCP endpoint https://api.kairoku.io/api/mcp directly, with no bearer:

codex plugin marketplace add https://gitlab.com/owds-inc/releases/kairoku/distribution.git
codex plugin add kairoku@kairoku-marketplace
codex mcp login kairoku

login opens the same browser grant. On a machine where you would rather not do a per-agent OAuth at all, kairoku login then kairoku mcp setup --agent codex registers the CLI's stdio bridge as the kairoku server instead, carrying the token kairoku login minted. Headless Codex runs skip both and take a kai_ per-run token through bearer_token_env_var — but in the worktree's own config, written by the daemon per run, never the machine-wide one. See Runner setup for why a global bearer entry breaks your own Codex, and for the configuration that makes MCP writes actually land under a non-interactive approval policy.

Codex reads AGENTS.md, not CLAUDE.md, which is why the invariants are mirrored verbatim in both files rather than one importing the other.