breakaway 1.4.0 → 1.5.0-main.25

package/README.md

@@ -53,7 +53,7 @@ Rather do it by hand? [The self-hosting guide](https://github.com/TheAnarchoX/br
 </picture>
 
 1. **Write the work down.** Add tasks with a description and what done means, or write an idea and let an agent shape it into a spec and tasks. Starting something with no repository yet? **Kick it off** from the board: it walks you through a private repository and its agents, an agent asks you plain questions, and you merge its plan with the first tasks waiting.
-2. **Agents claim it.** A claim is atomic, so two agents never work the same task. Start Claude Code cloud agents from the board, or let local Claude Code sessions pick up work through the CLI.
+2. **Agents claim it.** A claim is atomic, so two agents never work the same task. Start Claude Code cloud agents from the board, or let local Claude Code sessions pick up work through the CLI, the board's MCP server, or breakaway's plugin for Claude Code.
 3. **Pull requests close tasks.** A pull request that says `Closes BRK-12.` puts the task in review. The task is done when you merge it.
 4. **They ping you when they're stuck.** An agent that needs you sends a ping to your inbox. The rest waits on the board.
 
@@ -90,8 +90,8 @@ Rather do it by hand? [The self-hosting guide](https://github.com/TheAnarchoX/br
 <table>
   <tr>
     <td valign="top">
-      <h3>Three ways in, one set of data.</h3>
-      <p>The web board in your browser, installable on your phone. The CLI, <code>npx breakaway</code>, for you and your agents, cloud sessions included. And Taskwarrior 3, which syncs with the board using its own protocol.</p>
+      <h3>Four ways in, one set of data.</h3>
+      <p>The web board in your browser, installable on your phone. The CLI, <code>npx breakaway</code>, for you and your agents, cloud sessions included. The board's MCP server at <code>/mcp</code>, so an MCP client like Claude Code claims and comments without the CLI. And Taskwarrior 3, which syncs with the board using its own protocol.</p>
 
 ```sh
 npx breakaway next --claim --as claude-brk-12
@@ -121,10 +121,10 @@ npx breakaway list --ready
 
 <picture>
   <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/TheAnarchoX/breakaway/main/docs/media/built-light.png">
-  <img alt="How breakaway is built. Three ways in: the web board, the CLI, and Taskwarrior. They reach one Worker and its Durable Object on your own Cloudflare account, which holds every task. The board talks to GitHub through its own GitHub App, and starts Claude Code cloud agents through your routine; agents work the board through the CLI." src="https://raw.githubusercontent.com/TheAnarchoX/breakaway/main/docs/media/built-dark.png" width="100%">
+  <img alt="How breakaway is built. Four ways in: the web board, the CLI, the MCP server, and Taskwarrior. They reach one Worker and its Durable Object on your own Cloudflare account, which holds every task. The board talks to GitHub through its own GitHub App, and starts Claude Code cloud agents through your routine; agents work the board through the CLI or MCP." src="https://raw.githubusercontent.com/TheAnarchoX/breakaway/main/docs/media/built-dark.png" width="100%">
 </picture>
 
-One Cloudflare Worker serves the API, the web app (Preact), and Taskwarrior sync, and one SQLite Durable Object holds every task, claim, comment, and change. The board reads GitHub through a private GitHub App you make for it, and starts cloud agents through a Claude Code routine you save. [Architecture](https://leavethepack.dev/docs/architecture/) has the rest.
+One Cloudflare Worker serves the API, the MCP server, the web app (Preact), and Taskwarrior sync, and one SQLite Durable Object holds every task, claim, comment, and change. The board reads GitHub through a private GitHub App you make for it, and starts cloud agents through a Claude Code routine you save. [Architecture](https://leavethepack.dev/docs/architecture/) has the rest.
 
 ## Docs
 
@@ -139,6 +139,8 @@ One Cloudflare Worker serves the API, the web app (Preact), and Taskwarrior sync
 | [Ideas, decisions, and pings](https://leavethepack.dev/docs/ideas-decisions-pings/) | Let an agent shape an idea, answer its questions in a form, and get a ping when only you can help |
 | [Routines](https://leavethepack.dev/docs/routines/) | Save an agent run and start it by hand, on a schedule, or on a GitHub event |
 | [The CLI](https://leavethepack.dev/docs/cli/) | Every command of `npx breakaway` |
+| [The Claude Code plugin](https://leavethepack.dev/docs/plugin/) | The `tasks` skill, `/breakaway:next`, the session hooks, and the MCP server in one install, for you or a whole repository |
+| [MCP clients](https://leavethepack.dev/docs/mcp/) | Connect Claude Code or any MCP client to your board's `/mcp`, and sign in from Claude's apps |
 | [GitHub](https://leavethepack.dev/docs/github/) | Your own private App, how pull requests link to tasks, merging, and moving a repository to the deploy flow to promote, roll back, and release |
 | [Taskwarrior](https://leavethepack.dev/docs/taskwarrior/) | Sync, reports, and contexts with Taskwarrior 3 |
 | [Deploying](https://leavethepack.dev/docs/deploying/) | Releases, channels, the Deploy and Update workflows, and rollbacks |
@@ -180,6 +182,7 @@ breakaway publishes releases and never deploys an install. Every install, the ow
 - **Every merge to `main`**, once CI passes, publishes a GitHub pre-release `vX.Y.Z-main.N` on the `main` channel. It carries the bundle (`breakaway-bundle.tar.gz`: the Worker's files and the web app's `dist`), a `manifest.json` (version, channel, commit, `manual`, and the lowest version it updates from), its signature `manifest.json.sig` (Ed25519, made with a key only the release workflow holds; the public key is `src/release-key.js`), and `SHA256SUMS`. The notes list the merged pull requests by title.
 - **A stable release** `vX.Y.Z` is the owner's: they run the **Release** workflow with the pre-release to promote. The bundle is that pre-release's, unchanged, and the notes cover everything since the last stable, under the release's own words from [`docs/releases/vX.Y.Z.md`](https://github.com/TheAnarchoX/breakaway/tree/main/docs/releases) when it's there.
 - **The CLI** is on npm as [`breakaway`](https://www.npmjs.com/package/breakaway), staged on npm by the same workflow, with provenance, and live once the owner approves it there with 2FA. npm's trusted publishing can't yet read the OIDC identity of a repository as new as this one ([npm/cli#9969](https://github.com/npm/cli/issues/9969)), so until it can, a token that can stage but never publish by itself stands in, in an environment only `main` can use. Every pre-release goes out under the `next` dist-tag, and a stable release as `latest`. `npx breakaway <command>` is `node scripts/tasks.mjs <command>`.
+- **The plugin** for Claude Code (`plugin/`) goes out from the `plugin` branch, never from `main`: Anthropic's plugin directory and this repository's marketplace follow that branch. A stable release runs the **Plugin** workflow, which validates the plugin and moves the branch to the released tag, with `plugin.json`'s version set to the release's. To put a fix out before the next release, the owner runs it by hand on `main` with a release tag, or a commit on `main` a pre-release was made from. As with `site`, a ruleset lets only deploy keys move `plugin`, and the key is the `PLUGIN_DEPLOY_KEY` secret in a `plugin` environment that only `main` can use.
 - **A major release** is one where an install has to do something by hand: a config or binding change, a Durable Object class or migration, a route or cron. Its notes have a **Manual steps** section and its manifest says `manual: true`, which an install's deploy stops on. A change that needs it sets `manual` and `manualSteps` in `release.json`, and the pull request that ships the steps clears them. When the only step is `wrangler deploy` (a new Durable Object class, a cron, a route), it also sets `wranglerDeploy: true`, and an install whose Deploy may run `wrangler deploy` does it itself (the install template's README says when). Data the Durable Object stores changes forward-only and additively, so an install can always go back one release, except across a new Durable Object class, which Cloudflare doesn't roll back.
 - **The version** is `package.json`'s; the release workflow sets it to the pre-release's before it builds. Patches count by themselves: once a stable is out, the pre-releases work toward its next patch. For the next minor or major, pick it as **next** when you run the **Release** workflow (patch, the default, opens nothing): once the stable is published, the workflow opens a pull request setting `package.json` to it, and after it merges the next pre-release is `vX.Y.0-main.1`. That needs **Allow GitHub Actions to create and approve pull requests** on in the repository's Actions settings (if it was off, turn it on and re-run the **next version** job: it opens the pull request from the branch it already made), and a pull request opened with the workflow's token starts no workflows, so close and reopen it, or push to it, for CI to run. At any other time, **Prepare** on the board's GitHub view starts an agent that opens the same pull request. `GET /api/ping` and `GET /api/health` report it as `release`. An install that deploys a stable passes it as the `BREAKAWAY_VERSION` variable, since the bundle was built as the pre-release.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakaway",
-  "version": "1.4.0",
+  "version": "1.5.0-main.25",
   "description": "The task board for you and your coding agents: a Cloudflare Worker, its web app, Taskwarrior sync, and the CLI (npx breakaway).",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",

package/scripts/brand-lint.mjs

@@ -2,7 +2,7 @@
 /**
  * Lint breakaway's words against the brand guide's mechanical rules (scripts/lib/brand-lint.js).
  *   node scripts/brand-lint.mjs [path ...]
- * Paths are files or folders; with none, the web app, brand/, the docs, launch/, and the README and root
+ * Paths are files or folders; with none, the web app, brand/, the docs, launch/, the plugin, and the README and root
  * markdown files. Exits 1 and prints each finding. A line opts out with `brand-lint-ignore <rule>`.
  */
 import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
@@ -15,6 +15,7 @@ const DEFAULT = [
   'brand',
   'docs',
   'launch',
+  'plugin',
   'site/README.md',
   'site/content',
   'README.md',

package/scripts/plugin.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * Writes the breakaway plugin's generated files (CLI-7, docs/specs/IDEA-25-claude-plugin.md): the `tasks` skill, made
+ * from .agents/skills/tasks/SKILL.md for any repository, the session hooks from sessionHooks() in src/init.js, and the
+ * licence. Unlike src/board-files.json they're committed, because the plugin is read from git; a test in
+ * scripts/tasks/plugin.test.js fails when one is behind its source. The rest of plugin/ is written by hand.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { SKILL } from '../src/prompt.js';
+import { sessionHooks, skillFor } from '../src/init.js';
+import { BREAKAWAY_REPO } from '../src/updates.js';
+
+export const BOARD = BREAKAWAY_REPO;
+export const PLUGIN_DIR = 'plugin/';
+
+/**
+ * The tasks skill as the plugin ships it. A plugin works in any checkout, so the skill names no breakaway rule and
+ * links nowhere a checkout may not have: the board's docs and the core point at GitHub, `AGENTS.md` is the checkout's
+ * own. Each change must find its text, so a skill reworded there fails here instead of shipping half changed.
+ */
+export function pluginSkill(text, board = BOARD) {
+  /** @type {[RegExp, string][]} */
+  const changes = [
+    [
+      /breakaway's work is on the board that tracks this repository/gu,
+      "This repository's work is on the board that tracks it",
+    ],
+    [/breakaway's areas: [^.\n]+\./gu, "This repository's areas are in its `AGENTS.md`."],
+    [
+      /\[`prompts\/core\.md`\]\(\.\.\/\.\.\/\.\.\/prompts\/core\.md\)/gu,
+      `the core: \`tools/tasks/prompts/core.md\` in a repository \`repos init\` set up, and [on GitHub](https://github.com/${board}/blob/main/prompts/core.md)`,
+    ],
+    [/\[`AGENTS\.md`\]\(\.\.\/\.\.\/\.\.\/AGENTS\.md\)/gu, '`AGENTS.md`'],
+    [
+      /Follow \[`prompts\/breakaway\.md`\]\(\.\.\/\.\.\/\.\.\/prompts\/breakaway\.md\), which starts with the core\./gu,
+      "Follow the repository's agent prompt, which `AGENTS.md` names and which starts with the core.",
+    ],
+  ];
+  let out = String(text);
+  for (const [pattern, replacement] of changes) {
+    if (!pattern.test(out))
+      throw new Error(`The tasks skill no longer has ${pattern}: update pluginSkill in scripts/plugin.mjs.`);
+    pattern.lastIndex = 0;
+    out = out.replace(pattern, replacement);
+  }
+  // The rest of the board's docs are on GitHub, as they are for a copy (skillFor).
+  return skillFor(out, board);
+}
+
+/** The plugin's generated files, by their path from the repository's root. */
+export function pluginFiles(read) {
+  return {
+    [`${PLUGIN_DIR}skills/tasks/SKILL.md`]: pluginSkill(read(SKILL)),
+    [`${PLUGIN_DIR}hooks/hooks.json`]: `${JSON.stringify({ hooks: sessionHooks() }, null, 2)}\n`,
+    [`${PLUGIN_DIR}LICENSE`]: read('LICENSE'),
+  };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const ROOT = new URL('../', import.meta.url);
+  const read = (/** @type {string} */ path) => readFileSync(new URL(path, ROOT), 'utf8');
+  for (const [path, content] of Object.entries(pluginFiles(read))) writeFileSync(new URL(path, ROOT), content);
+  console.error('Wrote the plugin’s skill, hooks, and licence in plugin/.');
+}

package/scripts/tasks/cli.js

@@ -23,6 +23,7 @@ export const NO_ARGUMENTS = new Set([
   'next',
   'activity',
   'health',
+  'mcp',
   'connections',
   'export',
   'setup',

package/scripts/tasks/hook-config.js

@@ -7,7 +7,7 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync, rmSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { boardUrl, configDir, parseEnvFile, readSetting } from './settings.js';
+import { boardUrl, configDir, parseEnvFile, readSetting, settingFrom } from './settings.js';
 
 /** The git root of the current folder, or null outside a repository. */
 function gitRoot() {
@@ -69,8 +69,9 @@ export function boardConfig(root = projectRoot()) {
     /* the CLI says what's wrong with it */
   }
   const { url } = boardUrl({ env: process.env, file, taskrc: readOptional(join(root, '.taskrc')), config });
-  // In a cloud session there's no token here: the environment's API credential adds it.
-  const token = readSetting('TOKEN', { env: process.env, file });
+  // In a cloud session there's no token here: the environment's API credential adds it. In the plugin's hooks, its
+  // `token` comes after the CLI's own (CLI-8).
+  const token = settingFrom('TOKEN', { env: process.env, file }).value;
   return { base: url, headers: token ? { Authorization: `Bearer ${token}` } : {} };
 }
 

package/scripts/tasks/mcp.js

@@ -0,0 +1,199 @@
+/**
+ * npx breakaway mcp (docs/specs/IDEA-24-mcp-server.md, section 5; CLI-6): how a checkout connects an MCP client to the
+ * board's /mcp, and whether it answers. Pure apart from the `fetch` it's handed, so it's tested without a board.
+ */
+import { githubFromRemote, pickRepo } from './repo.js';
+
+/** The MCP revision `--check` speaks: the one with an `initialize` handshake, which /mcp accepts (src/mcp.js, LEGACY). */
+export const CHECK_PROTOCOL = '2025-11-25';
+/** The server's name in a client's config. */
+export const SERVER = 'breakaway';
+
+const AGENT = /^[\w.@:/-]{1,64}$/u;
+
+/**
+ * The agent name an MCP connection claims as: --as or BREAKAWAY_AGENT (`named`), else `claude-<branch>` for the
+ * checkout's branch, else `fallback` (the CLI's own default). A branch's `/` and anything a name can't hold become `-`.
+ * @param {{ named?: string | null, branch?: string | null, fallback: string }} options
+ */
+export function mcpAgent({ named, branch, fallback }) {
+  if (named) return named;
+  const b = String(branch ?? '').trim();
+  if (!b || b === 'HEAD') return fallback;
+  const name = (/^claude[-/]/u.test(b) ? b : `claude-${b}`).replace(/[^\w.@:-]+/gu, '-').slice(0, 64);
+  return AGENT.test(name) ? name : fallback;
+}
+
+/**
+ * The `claude mcp add` line and the `.mcp.json` entry for a checkout. The token is always the environment variable
+ * `tokenVar`, never its value: the shell fills it in for the line, and Claude Code for `.mcp.json`. Without `repo` (a
+ * checkout the board doesn't track) there's no X-Breakaway-Repo, and the repository's tools say what's missing.
+ * @param {{ url: string, agent: string, repo?: string | null, tokenVar: string }} options
+ * @returns {{ endpoint: string, command: string, json: { mcpServers: Record<string, any> } }}
+ */
+export function mcpConfig({ url, agent, repo = null, tokenVar }) {
+  const endpoint = `${String(url).replace(/\/+$/u, '')}/mcp`;
+  const headers = {
+    Authorization: `Bearer \${${tokenVar}}`,
+    'X-Breakaway-Agent': agent,
+    ...(repo ? { 'X-Breakaway-Repo': repo } : {}),
+  };
+  const command = [
+    `claude mcp add --transport http ${SERVER} ${endpoint}`,
+    `  --header "Authorization: Bearer $${tokenVar}"`,
+    `  --header "X-Breakaway-Agent: ${agent}"`,
+    ...(repo ? [`  --header "X-Breakaway-Repo: ${repo}"`] : []),
+  ].join(' \\\n');
+  return { endpoint, command, json: { mcpServers: { [SERVER]: { type: 'http', url: endpoint, headers } } } };
+}
+
+/**
+ * `--headers`: the headers Claude Code sends to /mcp, for the plugin's `headersHelper` (CLI-9,
+ * docs/specs/IDEA-25-claude-plugin.md, section 4). Claude Code reads them as JSON from standard output, so the token is
+ * its value here, and only there. Outside a repository the board tracks there's only Authorization, and the repository's
+ * tools say what's missing; without a token there's none, so a session's proxy can add it.
+ *
+ * The agent's name is X-Breakaway-Agent only when the CLI has one of its own (`named`: --as, BREAKAWAY_AGENT, or
+ * tasks.env). Otherwise it's `agent`, claude-<branch>, as X-Breakaway-Agent-Default: the helper can't see the plugin's
+ * agent_name, which the plugin sends as a static X-Breakaway-Agent that this one would override, and /mcp takes the
+ * default only when that's empty (CLI-16).
+ * @param {{ token?: string | null, named?: string | null, agent: string, repo?: string | null }} options
+ * @returns {Record<string, string>}
+ */
+export function mcpHeaders({ token = null, named = null, agent, repo = null }) {
+  return {
+    ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    ...(repo
+      ? {
+          ...(named ? { 'X-Breakaway-Agent': named } : { 'X-Breakaway-Agent-Default': agent }),
+          'X-Breakaway-Repo': repo,
+        }
+      : {}),
+  };
+}
+
+/**
+ * The repository `--headers` names: the board's slug for the checkout when the board says which (`GET /api/repos`), and
+ * null when it tracks none of them. A plugin's headersHelper runs without the plugin's settings, so with only the
+ * plugin set up there's no token to ask with: then it's the checkout's GitHub `owner/name`, which /mcp matches against
+ * its repositories itself (src/mcp.js). `named` is --repo or BREAKAWAY_REPO. Never throws: Claude Code is waiting.
+ * @param {{ base?: string | null, token?: string | null, named?: string | null, remote?: string | null, fetch: typeof globalThis.fetch }} options
+ * @returns {Promise<string | null>}
+ */
+export async function headersRepo({ base = null, token = null, named = null, remote = null, fetch }) {
+  let registry = null;
+  if (base)
+    try {
+      const res = await fetch(`${String(base).replace(/\/+$/u, '')}/api/repos`, {
+        headers: token ? { Authorization: `Bearer ${token}` } : {},
+        signal: AbortSignal.timeout(5000),
+      });
+      if (res.ok) registry = await res.json();
+    } catch {
+      /* the board can't be reached: /mcp will say so itself */
+    }
+  if (registry) {
+    try {
+      return pickRepo({ named, remote, registry });
+    } catch {
+      return null; // --repo names a repository the board doesn't have
+    }
+  }
+  if (named) return String(named).trim().toLowerCase();
+  return githubFromRemote(remote)?.toLowerCase() ?? null;
+}
+
+/**
+ * What `npx breakaway mcp` prints: the line, the `.mcp.json` entry, and what to check.
+ * @param {{ endpoint: string, command: string, json: object }} config
+ * @param {{ repo?: string | null, tokenVar: string }} options
+ */
+export function mcpLines(config, { repo = null, tokenVar }) {
+  return [
+    `Connect Claude Code to the board's MCP server at ${config.endpoint}:`,
+    '',
+    config.command,
+    '',
+    `Run it where ${tokenVar} is set, then type /mcp in Claude Code. Or put this in the checkout's .mcp.json, which`,
+    `Claude Code fills in from ${tokenVar} when it starts:`,
+    '',
+    JSON.stringify(config.json, null, 2),
+    '',
+    ...(repo
+      ? []
+      : [
+          'This checkout isn’t a repository the board tracks, so there’s no X-Breakaway-Repo header: the tools that work',
+          'in a repository will ask for one. Run this in a tracked checkout, or name one with --repo <slug>.',
+          '',
+        ]),
+    `The token is the board's full token: give it only to a client you run. npx breakaway mcp --check tests the connection.`,
+  ];
+}
+
+/**
+ * `--check`: an `initialize` and a `tools/list` against /mcp with the same headers the config sends, and what came
+ * back. `ok` is false with the board's own error when either fails.
+ * @param {{ endpoint: string, token?: string | null, agent: string, repo?: string | null, fetch: typeof globalThis.fetch }} options
+ * @returns {Promise<{ ok: boolean, lines: string[] }>}
+ */
+export async function checkMcp({ endpoint, token = null, agent, repo = null, fetch }) {
+  const headers = {
+    ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    'Content-Type': 'application/json',
+    Accept: 'application/json, text/event-stream',
+    'X-Breakaway-Agent': agent,
+    ...(repo ? { 'X-Breakaway-Repo': repo } : {}),
+  };
+  const rpc = async (id, method, params, version) => {
+    let res;
+    try {
+      res = await fetch(endpoint, {
+        method: 'POST',
+        headers: { ...headers, ...(version ? { 'MCP-Protocol-Version': version } : {}) },
+        body: JSON.stringify({ jsonrpc: '2.0', id, method, params }),
+      });
+    } catch (error) {
+      return { error: `can't reach ${endpoint} (${reasonOf(error)})` };
+    }
+    const data = await res.json().catch(() => null);
+    // An install from before /mcp answers it with the web app, a 404, or a 405: anything but JSON-RPC.
+    if (res.status !== 401 && (res.status === 404 || res.status === 405 || (res.ok && !data?.jsonrpc)))
+      return {
+        error: `${endpoint} answered ${res.status}: this install has no MCP server yet. Update and deploy it (docs/tasks.md#updates).`,
+      };
+    if (res.status === 401)
+      return {
+        error: `${endpoint} refused the token (401)${data?.error ? `: ${data.error}` : ''}${token ? '' : '. No token is set'}`,
+      };
+    if (data?.error)
+      return { error: `${method} failed: ${data.error.message ?? data.error}${res.ok ? '' : ` (HTTP ${res.status})`}` };
+    if (!res.ok || !data?.result) return { error: `${method} failed: HTTP ${res.status}` };
+    return { result: data.result };
+  };
+
+  const init = await rpc(1, 'initialize', {
+    protocolVersion: CHECK_PROTOCOL,
+    capabilities: {},
+    clientInfo: { name: 'breakaway-cli', version: '1' },
+  });
+  if (init.error) return { ok: false, lines: [`The board's MCP server didn't answer: ${init.error}`] };
+  const listed = await rpc(2, 'tools/list', {}, init.result.protocolVersion ?? CHECK_PROTOCOL);
+  if (listed.error) return { ok: false, lines: [`The board's MCP server didn't answer: ${listed.error}`] };
+  const server = init.result.serverInfo ?? {};
+  const tools = (listed.result.tools ?? []).map((t) => t.name);
+  return {
+    ok: true,
+    lines: [
+      `The board's MCP server answers at ${endpoint}: ${server.name ?? SERVER}${server.version ? ` ${server.version}` : ''}, MCP ${init.result.protocolVersion}.`,
+      `${tools.length} tools: ${tools.join(', ') || 'none'}.`,
+      `As ${agent}${repo ? `, in ${repo}` : ', in no repository (set X-Breakaway-Repo, or run it in a tracked checkout)'}.`,
+    ],
+  };
+}
+
+/** Why a fetch failed: the innermost cause, like ECONNREFUSED. */
+function reasonOf(error) {
+  let root = error;
+  while (root?.cause) root = root.cause;
+  return typeof root?.code === 'string' ? root.code : (root?.message ?? String(error));
+}

package/scripts/tasks/message-wait.mjs

@@ -17,12 +17,15 @@ import { readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
+import { checkoutRunsHooks } from './plugin-hooks.js';
 import { boardConfig, claimedTask, projectRoot } from './hook-config.js';
 import { sessionRequest } from './proxy.js';
 import { waitForMessages } from './session-messages.js';
 
 async function main() {
   const root = projectRoot();
+  // The plugin's copy of this hook steps aside when the checkout's settings run it too (BRK-159).
+  if (checkoutRunsHooks(root)) return 0;
   const claim = claimedTask(root);
   if (!claim?.agent) return 0;
   for await (const _ of process.stdin); // Claude Code sends the hook's input; it isn't needed.

package/scripts/tasks/plugin-env.js

@@ -0,0 +1,37 @@
+/**
+ * Hands the plugin's settings to the session's Bash commands (CLI-8, docs/specs/IDEA-25-claude-plugin.md, section 2).
+ * Claude Code gives a plugin's options to its hooks as CLAUDE_PLUGIN_OPTION_<option>, but not to the commands its
+ * skills run, so `/breakaway:next` would find no board. A SessionStart hook may append `export` lines to
+ * CLAUDE_ENV_FILE, which Claude Code applies to every later Bash command, so the plugin's SessionStart hook passes
+ * them on under the same names: the CLI still reads them after its own settings (scripts/tasks/settings.js).
+ */
+import { appendFileSync } from 'node:fs';
+import { PLUGIN_OPTIONS } from './settings.js';
+
+/** `value` quoted for a POSIX shell. */
+const quote = (value) => `'${String(value).replace(/'/gu, `'\\''`)}'`;
+
+/**
+ * The `export` lines for the plugin's options that are set, or '' outside a plugin's hook (no CLAUDE_PLUGIN_ROOT)
+ * or when none is.
+ * @param {Record<string, string | undefined>} env
+ */
+export function pluginEnvLines(env) {
+  if (!env.CLAUDE_PLUGIN_ROOT) return '';
+  return Object.values(PLUGIN_OPTIONS)
+    .filter((name) => env[name])
+    .map((name) => `export ${name}=${quote(env[name])}\n`)
+    .join('');
+}
+
+/** Appends them to CLAUDE_ENV_FILE when Claude Code gave one (only SessionStart does). Never throws: hooks stay quiet. */
+export function passPluginEnv(env = process.env, append = appendFileSync) {
+  const lines = env.CLAUDE_ENV_FILE ? pluginEnvLines(env) : '';
+  if (!lines) return false;
+  try {
+    append(env.CLAUDE_ENV_FILE, lines, { mode: 0o600 });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/scripts/tasks/plugin-hooks.js

@@ -0,0 +1,32 @@
+/**
+ * The session hooks when breakaway's plugin runs them (BRK-159, docs/specs/IDEA-25-claude-plugin.md, section 7): a
+ * checkout repos init set up before the plugin, or with --copies, runs the same hooks from its .claude/settings.json,
+ * so a person who installed the plugin would post each entry twice. Claude Code sets CLAUDE_PLUGIN_ROOT for a plugin's
+ * hooks, and then the plugin's hooks step aside for the checkout's.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** A session hook command repos init writes: through npx, any version, or an old copy's script. */
+const BOARD_HOOK =
+  /\bbreakaway(?:@[^\s"]+)? hook (?:session|wait)\b|scripts\/tasks\/(?:session-hook|message-wait)\.mjs/u;
+
+/** A file's text, or null when it can't be read. */
+function readOptional(path) {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether this hook is the plugin's and the checkout's settings already run the board's hooks, so this one does
+ * nothing. Outside the plugin it's always false: the checkout's own hooks always run.
+ */
+export function checkoutRunsHooks(root, env = process.env, read = readOptional) {
+  if (!env.CLAUDE_PLUGIN_ROOT) return false;
+  return ['settings.json', 'settings.local.json'].some((name) =>
+    BOARD_HOOK.test(read(join(root, '.claude', name)) ?? ''),
+  );
+}

package/scripts/tasks/session-hook.mjs

@@ -10,14 +10,21 @@
  * Quiet by design: without a claimed task (.task-session, written by `tasks claim`), with
  * BREAKAWAY_SESSION_LOG=off, or on any error, it does nothing and exits 0. A post
  * that fails leaves its reason in the temp folder, which the CLI's next command here shows (BRK-86).
+ *
+ * Run by the plugin at SessionStart, it first passes the plugin's settings on to the session's Bash commands (CLI-8).
  */
+import { checkoutRunsHooks } from './plugin-hooks.js';
 import { boardConfig, claimedTask, dropClaim, projectRoot } from './hook-config.js';
+import { passPluginEnv } from './plugin-env.js';
 import { clearHookFailure, noteHookFailure, sessionRequest } from './proxy.js';
 import { entryFor } from './session-log.js';
 import { CONTEXT_EVENTS, messageOutput, releasedOutput } from './session-messages.js';
 
 async function main() {
+  passPluginEnv();
   const root = projectRoot();
+  // The plugin's copy of this hook steps aside when the checkout's settings run it too (BRK-159).
+  if (checkoutRunsHooks(root)) return;
   const claim = claimedTask(root);
   if (!claim) return;
 

package/scripts/tasks/settings.js

@@ -15,9 +15,21 @@ export const NAMES = Object.freeze({
   SESSION_LOG: 'BREAKAWAY_SESSION_LOG',
 });
 
+/**
+ * The plugin's settings (CLI-8, docs/specs/IDEA-25-claude-plugin.md, section 2): Claude Code asks for them when the
+ * plugin is enabled and hands them to its hooks as CLAUDE_PLUGIN_OPTION_<option>. They come after the CLI's own, so a
+ * machine set up with `npx breakaway setup`, or a cloud session's environment, keeps working unchanged.
+ */
+export const PLUGIN_OPTIONS = Object.freeze({
+  URL: 'CLAUDE_PLUGIN_OPTION_BOARD_URL',
+  TOKEN: 'CLAUDE_PLUGIN_OPTION_TOKEN',
+  AGENT: 'CLAUDE_PLUGIN_OPTION_AGENT_NAME',
+});
+
 /**
  * A setting's value: from the environment first, then the env file, else `fallback`. The environment always wins,
- * so `BREAKAWAY_URL=… npx breakaway` points one command elsewhere.
+ * so `BREAKAWAY_URL=… npx breakaway` points one command elsewhere. The plugin's options aren't read here: see
+ * `settingFrom`.
  */
 export function readSetting(key, { env = {}, file = {} }, fallback) {
   const name = NAMES[key];
@@ -25,6 +37,23 @@ export function readSetting(key, { env = {}, file = {} }, fallback) {
   return env[name] || file[name] || fallback;
 }
 
+/**
+ * A setting's value and where it came from: the environment, then tasks.env, then the plugin's option for it, else
+ * `{ value: undefined, from: null }`. `from` names the source, never the value, so `health` can print it.
+ * @param {string} key
+ * @param {{ env?: Record<string, string | undefined>, file?: Record<string, string> }} sources
+ * @returns {{ value: string | undefined, from: 'environment' | 'tasks.env' | 'plugin' | null }}
+ */
+export function settingFrom(key, { env = {}, file = {} }) {
+  const name = NAMES[key];
+  if (!name) throw new Error(`no setting ${key}`);
+  if (env[name]) return { value: env[name], from: 'environment' };
+  if (file[name]) return { value: file[name], from: 'tasks.env' };
+  const option = PLUGIN_OPTIONS[key];
+  if (option && env[option]) return { value: env[option], from: 'plugin' };
+  return { value: undefined, from: null };
+}
+
 /**
  * This machine's folder for the board (tasks.env, the Taskwarrior credentials, the routines copy):
  * BREAKAWAY_HOME when it's set (one per install, for a machine that uses two), else ~/.config/breakaway.
@@ -45,16 +74,19 @@ export function taskrcUrl(text) {
 }
 
 /**
- * The board's base URL, and where it came from: the environment or env file (BREAKAWAY_URL), else the checkout's own .taskrc (`sync.server.url`, so the CLI and Taskwarrior agree),
- * else the install's breakaway.config.json (`url`), else null: nothing says which board.
+ * The board's base URL, and where it came from: the environment or tasks.env (BREAKAWAY_URL), else the checkout's own
+ * .taskrc (`sync.server.url`, so the CLI and Taskwarrior agree), else the install's breakaway.config.json (`url`), else
+ * the plugin's `board_url` (CLI-8: a setting of the person's, so anything the machine or checkout says comes first),
+ * else null: nothing says which board.
  */
 export function boardUrl({ env = {}, file = {}, taskrc = null, config = null }) {
   const pick = () => {
-    const set = readSetting('URL', { env, file });
-    if (set) return { url: set, from: 'setting' };
+    if (env[NAMES.URL]) return { url: env[NAMES.URL], from: 'environment' };
+    if (file[NAMES.URL]) return { url: file[NAMES.URL], from: 'tasks.env' };
     const rc = taskrcUrl(taskrc);
     if (rc) return { url: rc, from: '.taskrc' };
     if (config?.url) return { url: config.url, from: 'config' };
+    if (env[PLUGIN_OPTIONS.URL]) return { url: env[PLUGIN_OPTIONS.URL], from: 'plugin' };
     return { url: null, from: 'default' };
   };
   const { url, from } = pick();

package/scripts/tasks.mjs

@@ -49,6 +49,8 @@ import { checkInstall, confirmInstall, tokenTarget, unverifiedInstall } from './
 import { NO_TERMINAL, ask as askIn } from './tasks/ask.js';
 import {
   CLI_PACKAGE,
+  PLUGIN_BRANCH,
+  PLUGIN_REPO,
   PROMPT_SECTIONS,
   initCommitMessage,
   initPlan,
@@ -81,10 +83,20 @@ import {
   unknownSubcommand,
 } from './tasks/cli.js';
 import { keepLines } from './tasks/keep.js';
+import { checkMcp, headersRepo, mcpAgent, mcpConfig, mcpHeaders, mcpLines } from './tasks/mcp.js';
 import { mergeViews, pelotonLines, pelotonPost, pickPeloton } from './tasks/peloton.js';
 import { CLI_VERSION } from '../src/cli-version.js';
 import { parseInstall, secretName } from '../src/install.js';
-import { NAMES, boardUrl, configDir, parseEnvFile, readSetting, taskrcFixes, tildePath } from './tasks/settings.js';
+import {
+  NAMES,
+  boardUrl,
+  configDir,
+  parseEnvFile,
+  readSetting,
+  settingFrom,
+  taskrcFixes,
+  tildePath,
+} from './tasks/settings.js';
 
 const CONFIG_DIR = configDir({ env: process.env, home: homedir() });
 const ENV_FILE = join(CONFIG_DIR, 'tasks.env');
@@ -235,6 +247,11 @@ Reading                (list, next, claim, and add work in this checkout's repos
   github                 the checkout's repository on GitHub: open pull requests, checks, reviews, CI, deploys, alerts  [--sync] [--repo <slug>]
   hook session|wait      the Claude Code session hooks a repository's .claude/settings.json runs (npx breakaway hook session)
   health                 the server's state
+  mcp                    print the claude mcp add line and the .mcp.json entry that connect an MCP client to the board's
+                         /mcp from this checkout, with the token as $BREAKAWAY_TOKEN, never its value. Writes nothing
+    --check              …or check the server answers: initialize and tools/list, or the board's error
+    --headers            …or print the headers Claude Code sends to /mcp as JSON, the token included: the plugin's
+                         headersHelper. Only Authorization outside a repository the board tracks
   export                 every task (all repositories, statuses, and horizons) as JSON, checked against health's count  [--out <file>]
   connections            is everything the board leans on wired up: GitHub, Cloudflare, Claude, sync, push; the fix for each that isn't
 
@@ -292,8 +309,12 @@ Working
                          In a terminal it asks for each section of the agent prompt (Enter takes the default), or
                          takes them from --building --checks --pull-requests --direction --dependency-updates
                          --never-share <text>; --defaults takes the default for the rest without asking
-    --update             refresh the copied files (the CLI, core, skill, Taskwarrior files) in a pull request when they're
-                         older than this checkout's; the repository's own (its prompt, AGENTS.md) are never touched
+                         The tasks skill and the session hooks come from breakaway's Claude Code plugin, which
+                         .claude/settings.json turns on; until the plugin is out, they're copied, and it says so
+    --update             refresh the copied files (core, Taskwarrior files, release helpers) in a pull request when
+                         they're older than this checkout's, and move a repository with copies to the plugin; the
+                         repository's own (its prompt, AGENTS.md) are never touched
+    --copies             copy the tasks skill and the session hooks instead of using the plugin (with or without --update)
     --pipeline           also add the deploy flow: .github/breakaway-pipeline.json for the Workers --staging <name> and
                          --production <name> (asked in a terminal; default <slug>-staging and <slug>), what it renders,
                          and a minimal CI when the repository has no workflow. Only new files: never one it already has
@@ -361,7 +382,9 @@ Projects: ideas and routines are the board's; repos lists each repository's area
 
 Settings: BREAKAWAY_TOKEN, BREAKAWAY_URL, BREAKAWAY_AGENT, BREAKAWAY_REPO, from the environment or tasks.env in
   $BREAKAWAY_HOME (default ~/.config/breakaway).
-  Without BREAKAWAY_URL the board is this checkout's .taskrc sync.server.url. See docs/tasks.md#another-install.`;
+  Without BREAKAWAY_URL the board is this checkout's .taskrc sync.server.url. See docs/tasks.md#another-install.
+  Last come the breakaway plugin's settings for Claude Code (board_url, token, agent_name). health says which
+  source each setting came from.`;
 
 // ---- settings ----------------------------------------------------------------------------
 
@@ -370,8 +393,11 @@ function readEnvFile() {
 }
 
 const fileEnv = readEnvFile();
-/** A setting by its key in NAMES (scripts/tasks/settings.js): `TOKEN` reads BREAKAWAY_TOKEN. */
-const setting = (key, fallback) => readSetting(key, { env: process.env, file: fileEnv }, fallback);
+/**
+ * A setting by its key in NAMES (scripts/tasks/settings.js): `TOKEN` reads BREAKAWAY_TOKEN, then the plugin's `token`
+ * when the CLI runs in a Claude Code session with the breakaway plugin (CLI-8).
+ */
+const setting = (key, fallback) => settingFrom(key, { env: process.env, file: fileEnv }).value ?? fallback;
 const BOARD = boardUrl({
   env: process.env,
   file: fileEnv,
@@ -417,9 +443,11 @@ const FLAGS = new Set([
   'update',
   'defaults',
   'package',
+  'check',
+  'headers',
 ]);
 /** Flags only in repos init (BRK-91): --pipeline takes a file in repos modify, and is a flag there. */
-const INIT_FLAGS = new Set(['pipeline']);
+const INIT_FLAGS = new Set(['pipeline', 'copies']);
 
 function parse(argv) {
   const positional = [];
@@ -474,7 +502,7 @@ async function call(method, path, body, { soft = false } = {}) {
   warnIfStale(res.headers.get('X-Tasks-Cli'), res.headers.get('X-Tasks-Release'));
   if (res.status === 401 && !token)
     fail(
-      `no token. Set BREAKAWAY_TOKEN, put it in ${ENV_FILE}, or add it as an API credential in the cloud environment (see docs/tasks.md#cloud-agents).`,
+      `no token. Set BREAKAWAY_TOKEN, put it in ${ENV_FILE}, set it in the breakaway plugin's settings, or add it as an API credential in the cloud environment (see docs/tasks.md#cloud-agents).`,
     );
   const data = await res.json().catch(() => ({
     // The board always answers in JSON, so anything else came from something in between.
@@ -797,6 +825,29 @@ function changesFrom(o) {
   return c;
 }
 
+/** Where the board's address, token, and agent name came from (CLI-8): the sources only, never a value. */
+function settingSources() {
+  const sources = { env: process.env, file: fileEnv };
+  return { url: BOARD.from, token: settingFrom('TOKEN', sources).from, agent: settingFrom('AGENT', sources).from };
+}
+
+const SOURCE = {
+  environment: 'the environment',
+  'tasks.env': ENV_FILE,
+  '.taskrc': "this checkout's .taskrc",
+  config: "the install's breakaway.config.json",
+  plugin: "the breakaway plugin's settings",
+};
+
+/** settingSources() in a line: `address from …, token from …, agent name from …`. */
+function describeSources({ url, token, agent: name }) {
+  return [
+    `address from ${SOURCE[url] ?? 'nowhere'}`,
+    `token ${token ? `from ${SOURCE[token]}` : "not set (a cloud session's proxy may add it)"}`,
+    `agent name ${name ? `from ${SOURCE[name]}` : 'not set'}`,
+  ].join(', ');
+}
+
 const commands = {
   /** The Claude Code session hooks (BRK-7), so a repository's .claude/settings.json runs them through npx. */
   async hook() {
@@ -1573,12 +1624,69 @@ const commands = {
       return out.join('\n');
     });
   },
+  /** How to connect an MCP client to the board's /mcp from this checkout, and --check whether it answers (CLI-6). */
+  async mcp() {
+    // --headers is the plugin's headersHelper: it asks the board itself, and never fails (CLI-9).
+    const { slug } = opts.headers ? { slug: null } : await checkoutRepo();
+    let branch = null;
+    try {
+      branch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+    } catch {
+      /* not a git checkout */
+    }
+    const named = opts.as ?? setting('AGENT');
+    const name = mcpAgent({ named, branch, fallback: agent() });
+    if (opts.headers) {
+      const token = setting('TOKEN');
+      let remote = null;
+      try {
+        remote = execFileSync('git', ['remote', 'get-url', 'origin'], {
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+        });
+      } catch {
+        /* not a git checkout, or no origin */
+      }
+      // Claude Code says which server it's connecting: the plugin's board_url, when the CLI's settings don't name one.
+      const server = process.env.CLAUDE_CODE_MCP_SERVER_URL?.replace(/\/mcp\/?$/u, '');
+      const repo = await headersRepo({
+        base: BASE ?? (server?.startsWith('http') ? server : null),
+        token,
+        named: opts.repo ?? setting('REPO'),
+        remote,
+        fetch,
+      });
+      // Standard output is Claude Code's, and only the headers go there: never --json's wrapping, never a line of text.
+      console.log(JSON.stringify(mcpHeaders({ token, named, agent: name, repo })));
+      return;
+    }
+    const tokenVar = envName('TOKEN');
+    const config = mcpConfig({ url: BASE, agent: name, repo: slug, tokenVar });
+    if (!opts.check) {
+      print(config, () => mcpLines(config, { repo: slug, tokenVar }).join('\n'));
+      return;
+    }
+    const checked = await checkMcp({
+      endpoint: config.endpoint,
+      token: setting('TOKEN'),
+      agent: name,
+      repo: slug,
+      fetch,
+    });
+    print(checked, (c) => c.lines.join('\n'));
+    if (!checked.ok) process.exitCode = 1;
+  },
   async health() {
-    print(await call('GET', 'health'), (h) =>
+    const settings = settingSources();
+    print({ ...(await call('GET', 'health')), settings }, (h) =>
       [
         h.ok ? 'The task server is healthy.' : `The task server can't read its history: ${h.replicaError}`,
         `  ${h.tasks.pending} open of ${h.tasks.total} tasks, ${h.versions} versions`,
         `  snapshot: ${h.snapshot ? `${h.snapshot.created.slice(0, 16)}, ${h.snapshot.versionsSince} versions since` : 'none'}`,
+        `  settings: ${describeSources(settings)}`,
       ].join('\n'),
     );
   },
@@ -2019,7 +2127,10 @@ async function initRepo(slug) {
     /* not a git checkout */
   }
   const answers = update || readTarget(promptPathOf(repo)) !== null ? {} : await promptAnswers();
+  const plugin = !opts.copies;
   const plan = initPlan({
+    plugin,
+    pluginReleased: plugin ? pluginReleased() : false,
     repo,
     board: board ?? 'TheAnarchoX/breakaway',
     url: BASE,
@@ -2071,7 +2182,7 @@ async function initRepo(slug) {
       : []),
     ...(plan.removals.length
       ? [
-          `${opts['dry-run'] ? 'Would remove' : 'Removing'} ${plan.removals.length} files of the old copy of the CLI (npx breakaway replaces it):`,
+          `${opts['dry-run'] ? 'Would remove' : 'Removing'} ${plan.removals.length} files the board no longer copies here (npx breakaway${plan.plugin ? " and breakaway's plugin replace" : ' replaces'} them):`,
           ...plan.removals.map((p) => `  ${p}`),
         ]
       : []),
@@ -2134,7 +2245,8 @@ async function initRepo(slug) {
     );
   }
   const first = initCommitMessage(repo.slug, {
-    by: `npx breakaway repos init ${repo.slug}${opts.pipeline ? ' --pipeline' : ''}${opts.package ? ' --package' : ''}`,
+    by: `npx breakaway repos init ${repo.slug}${opts.copies ? ' --copies' : ''}${opts.pipeline ? ' --pipeline' : ''}${opts.package ? ' --package' : ''}`,
+    plugin: plan.plugin,
   });
   const title = update ? "Update the task board's agent files" : first.title;
   git(
@@ -2143,7 +2255,7 @@ async function initRepo(slug) {
     title,
     '-m',
     update
-      ? `The board's core, skill, release helpers, and Taskwarrior files as they are in ${board ?? 'breakaway'} now, and the session hooks run through npx, so an old copy of the CLI is removed: run it as npx ${CLI_PACKAGE}. This repository's own files are unchanged. Updated by npx ${CLI_PACKAGE} repos init ${repo.slug} --update.`
+      ? `The board's core, ${plan.plugin ? '' : 'skill, '}release helpers, and Taskwarrior files as they are in ${board ?? 'breakaway'} now, ${plan.plugin ? "and breakaway's Claude Code plugin in .claude/settings.json instead of the copied tasks skill and session hooks" : 'and the session hooks run through npx'}, so an old copy of the CLI is removed: run it as npx ${CLI_PACKAGE}. This repository's own files are unchanged. Updated by npx ${CLI_PACKAGE} repos init ${repo.slug} --update${opts.copies ? ' --copies' : ''}.`
       : `${first.body}${starter.files.length ? ` It also adds the deploy and release flows, rendered from ${starter.files[0].path}.` : ''}`,
   );
   const pushed = spawnSync('git', ['-C', dir, 'push', '-u', 'origin', empty ? `HEAD:refs/heads/${branch}` : work], {
@@ -2169,7 +2281,7 @@ async function initRepo(slug) {
         title,
         '--body',
         update
-          ? `The task board's copied files (its CLI, the core and stub, the tasks skill, and the Taskwarrior files) as they are on the board's repository now, updated by \`npx breakaway repos init ${repo.slug} --update\`. This repository's own files (its agent prompt, AGENTS.md, .taskrc, .envrc, package.json, .claude/settings.json) are unchanged.`
+          ? `The task board's copied files (the core and stub, ${plan.plugin ? '' : 'the tasks skill, '}the release helpers, and the Taskwarrior files) as they are on the board's repository now, updated by \`npx breakaway repos init ${repo.slug} --update${opts.copies ? ' --copies' : ''}\`. ${plan.plugin ? "The tasks skill and the session hooks come from breakaway's Claude Code plugin, which .claude/settings.json turns on, so their copies are removed. " : ''}This repository's own files (its agent prompt, AGENTS.md, .taskrc, .envrc, package.json${plan.plugin ? '' : ', .claude/settings.json'}) are otherwise unchanged.${plan.notes.length ? `\n\nNotes:\n${plan.notes.map((n) => `- ${n}`).join('\n')}` : ''}`
           : `The files the task board's agents need to claim and work a task in this repository, added by \`npx breakaway repos init ${repo.slug}\`. Nothing that was there is changed. If this repository's linter reads plain JavaScript, exclude the copied scripts (tools/tasks/ and the release helpers) from it.${plan.todo.length ? `\n\nStill to do:\n${plan.todo.map((t) => `- ${t}`).join('\n')}` : ''}`,
       ],
       { encoding: 'utf8' },
@@ -2189,6 +2301,24 @@ async function initRepo(slug) {
   console.log(['', ...next].join('\n'));
 }
 
+/**
+ * Whether breakaway's plugin is out (BRK-159): its marketplace gives it out from the plugin branch, which a stable
+ * release moves, so until that branch is there, repos init copies the skill and hooks instead. Null when GitHub can't
+ * be reached, which repos init says, and copies too.
+ */
+function pluginReleased() {
+  try {
+    const heads = execFileSync(
+      'git',
+      ['ls-remote', '--heads', `https://github.com/${PLUGIN_REPO}.git`, `refs/heads/${PLUGIN_BRANCH}`],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 20_000 },
+    );
+    return heads.trim() !== '';
+  } catch {
+    return null;
+  }
+}
+
 /**
  * The staging and production Workers for repos init --pipeline (BRK-91): --staging and --production, else asked in a
  * terminal, else `<slug>-staging` and `<slug>`.
@@ -2411,9 +2541,11 @@ if (opts.help || command === 'help') {
   process.exitCode = (await import('./tasks/pipeline.js')).run(args, opts);
 } else if (!commands[command]) {
   fail(`no command "${command}". npx breakaway help lists them.`);
-} else if (!BASE && command !== 'init-secrets') {
+} else if (!BASE && command !== 'init-secrets' && command !== 'hook' && !(command === 'mcp' && opts.headers)) {
+  // The hooks stay quiet without a board (a plugin installed but not set up, CLI-8): session-hook.mjs checks for itself.
+  // The plugin's headersHelper never fails, and Claude Code tells it the board's address when only the plugin knows it.
   fail(
-    `no board address. Set BREAKAWAY_URL (in the environment or ${ENV_FILE}), or sync.server.url in this checkout's .taskrc: see docs/tasks.md#another-install.`,
+    `no board address. Set BREAKAWAY_URL (in the environment or ${ENV_FILE}), sync.server.url in this checkout's .taskrc, or the board's address in the breakaway plugin's settings (or run npx breakaway setup): see docs/tasks.md#another-install.`,
   );
 } else if (unknownSubcommand(command, args[0])) {
   fail(unknownSubcommand(command, args[0]));

package/src/init.js

@@ -62,6 +62,101 @@ const TARGET_DIR = 'tools/tasks/';
  */
 export const MANIFEST = `${TARGET_DIR}copied.json`;
 const GITIGNORE = ['.task/', '.task-session', '.env'];
+
+/**
+ * breakaway's Claude Code plugin (docs/specs/IDEA-25-claude-plugin.md, section 3): repos init sets a repository up with
+ * it by default (BRK-158), so .claude/settings.json names breakaway's marketplace and turns the plugin on instead of
+ * running the session hooks, and the tasks skill comes with the plugin instead of a copy. The marketplace lives on
+ * breakaway's own repository, and gives out the plugin from its `plugin` branch, which moves at a stable release.
+ */
+export const PLUGIN_REPO = 'TheAnarchoX/breakaway';
+export const PLUGIN_MARKETPLACE = 'breakaway';
+export const PLUGIN = `breakaway@${PLUGIN_MARKETPLACE}`;
+export const PLUGIN_BRANCH = 'plugin';
+
+/** The two keys .claude/settings.json gets for the plugin: breakaway's marketplace, and the plugin turned on. */
+export function pluginSettings() {
+  return {
+    extraKnownMarketplaces: { [PLUGIN_MARKETPLACE]: { source: { source: 'github', repo: PLUGIN_REPO } } },
+    enabledPlugins: { [PLUGIN]: true },
+  };
+}
+
+/** Whether a hook command is one of the session hooks repos init wrote: through npx, any version, or an old copy's. */
+const BOARD_HOOK =
+  /\bbreakaway(?:@[^\s"]+)? hook (?:session|wait)\b|scripts\/tasks\/(?:session-hook|message-wait)\.mjs/u;
+
+/**
+ * settings.json moved to the plugin (repos init --update): the session hooks repos init wrote are gone, with any event
+ * left empty, and the plugin's two keys are there. A plugin the settings turn off stays off, and the rest is untouched.
+ * Null when it isn't JSON, so the caller says what to do instead.
+ */
+export function withPluginSettings(text) {
+  let settings;
+  try {
+    settings = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) return null;
+  const hooks = settings.hooks;
+  if (hooks && typeof hooks === 'object') {
+    for (const [event, groups] of Object.entries(hooks)) {
+      if (!Array.isArray(groups)) continue;
+      const kept = groups
+        .map((group) =>
+          Array.isArray(group?.hooks)
+            ? { ...group, hooks: group.hooks.filter((h) => !BOARD_HOOK.test(String(h?.command ?? ''))) }
+            : group,
+        )
+        .filter((group, i) => !(Array.isArray(group?.hooks) && !group.hooks.length && groups[i].hooks.length));
+      if (kept.length) hooks[event] = kept;
+      else delete hooks[event];
+    }
+    if (!Object.keys(hooks).length) delete settings.hooks;
+  }
+  const want = pluginSettings();
+  settings.extraKnownMarketplaces = {
+    ...want.extraKnownMarketplaces,
+    ...settings.extraKnownMarketplaces,
+  };
+  if (typeof settings.enabledPlugins?.[PLUGIN] !== 'boolean')
+    settings.enabledPlugins = { ...settings.enabledPlugins, ...want.enabledPlugins };
+  return `${JSON.stringify(settings, null, 2)}\n`;
+}
+
+/** Whether two JSON texts hold the same value, whatever their layout. */
+const sameJson = (a, b) => {
+  try {
+    return JSON.stringify(JSON.parse(a)) === JSON.stringify(JSON.parse(b));
+  } catch {
+    return false;
+  }
+};
+
+/** Whether settings.json already has the plugin: breakaway's marketplace, and the plugin named in enabledPlugins. */
+function hasPlugin(text) {
+  try {
+    const settings = JSON.parse(text);
+    return (
+      Boolean(settings?.extraKnownMarketplaces?.[PLUGIN_MARKETPLACE]) && PLUGIN in (settings?.enabledPlugins ?? {})
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Why repos init copies the tasks skill and the session hooks when it was asked for the plugin: the plugin isn't out
+ * yet (its branch isn't there), or GitHub couldn't say (`released` null).
+ */
+export function pluginPendingNote(slug, released = false) {
+  const why =
+    released === null
+      ? `GitHub couldn't say whether breakaway's plugin is out yet (the ${PLUGIN_BRANCH} branch on ${PLUGIN_REPO})`
+      : `breakaway's plugin isn't out yet (${PLUGIN_REPO} has no ${PLUGIN_BRANCH} branch until a stable release moves it)`;
+  return `${why}, so this copies the tasks skill and the session hooks instead. Once it's out, npx breakaway repos init ${slug} --update moves the repository to the plugin.`;
+}
 /** Pinned to LF so the shell scripts run on a checkout with core.autocrlf=true (BRK-41). */
 const GITATTRIBUTES = ['scripts/task text eol=lf', '.envrc text eol=lf'];
 
@@ -75,10 +170,13 @@ export function boardSources(read) {
 }
 
 /** The first commit's message for a repository set up from scratch: its title and body, the CLI's and the board's alike. */
-export function initCommitMessage(slug, { by = `npx breakaway repos init ${slug}` } = {}) {
+export function initCommitMessage(slug, { by = `npx breakaway repos init ${slug}`, plugin = true } = {}) {
+  const agentParts = plugin
+    ? "breakaway's Claude Code plugin, turned on in .claude/settings.json (it brings the tasks skill and the session hooks)"
+    : 'the session hooks (they run the CLI through npx), the tasks skill';
   return {
     title: "Set up the task board's agent files",
-    body: `What a board-started agent needs to claim and work a task here: the agent prompt, the board's core, the session hooks (they run the CLI through npx), the tasks skill, AGENTS.md, and Taskwarrior with direnv. Added by ${by}.`,
+    body: `What a board-started agent needs to claim and work a task here: the agent prompt, the board's core, ${agentParts}, AGENTS.md, and Taskwarrior with direnv. Added by ${by}.`,
   };
 }
 
@@ -310,14 +408,20 @@ export function skillFor(text, board, repo = null) {
 }
 
 /** A starter AGENTS.md: how this repository works with the board. The owner adds how to build here. */
-export function agentsMd(repo, board, dir = DEFAULT_DIR) {
+export function agentsMd(repo, board, dir = DEFAULT_DIR, { plugin = true } = {}) {
+  const skill = plugin
+    ? `Use the \`tasks\` skill (from breakaway's Claude Code plugin, which \`.claude/settings.json\` turns on) and the CLI, \`npx breakaway\` (the \`breakaway\` package on npm), to claim, comment, and hand over. It works in this checkout's repository, so \`list\` and \`next\` show only this repository's tasks. The skill is the board's, written for any repository: this repository's areas are above, and its rules are here.`
+    : `Use the \`tasks\` skill (\`${SKILL}\`) and the CLI, \`npx breakaway\` (the \`breakaway\` package on npm), to claim, comment, and hand over. It works in this checkout's repository, so \`list\` and \`next\` show only this repository's tasks. The skill is breakaway's, written for this repository's areas and prompt: where it names breakaway's own files or rules, the board's part applies and the rest doesn't.`;
+  const copied = plugin
+    ? `\`tools/tasks/\`, the release helpers in \`scripts/\`, and \`${PIPELINE_SKILL}\` come from [${board}](https://github.com/${board}). Don't edit them here: change them there. \`${MANIFEST}\` lists every file it copied, and \`repos init --update\` replaces only those: a file it doesn't list is this repository's own, even at a path breakaway copies to. \`.claude/settings.json\` turns on breakaway's plugin (\`${PLUGIN}\`), which brings the \`tasks\` skill, its commands, and the session hooks that show a cloud agent's output on its task, so this repository carries no copy of them.`
+    : `\`tools/tasks/\`, the release helpers in \`scripts/\`, \`${SKILL}\`, and \`${PIPELINE_SKILL}\` come from [${board}](https://github.com/${board}). Don't edit them here: change them there. \`${MANIFEST}\` lists every file it copied, and \`repos init --update\` replaces only those: a file it doesn't list is this repository's own, even at a path breakaway copies to. \`.claude/settings.json\` holds the session hooks that show a cloud agent's output on its task, and they run through \`npx\`, so this repository carries no copy of the CLI.`;
   return `# Agent instructions
 
 <!-- Started by \`npx breakaway repos init\` (breakaway's task board). Add how to build here: setup, tests, style, and anything agents must never do. -->
 
-- **Work lives on the task board.** This repository's tasks are in the areas ${areaList(repo)}. Use the \`tasks\` skill (\`${SKILL}\`) and the CLI, \`npx breakaway\` (the \`breakaway\` package on npm), to claim, comment, and hand over. It works in this checkout's repository, so \`list\` and \`next\` show only this repository's tasks. The skill is breakaway's, written for this repository's areas and prompt: where it names breakaway's own files or rules, the board's part applies and the rest doesn't.
+- **Work lives on the task board.** This repository's tasks are in the areas ${areaList(repo)}. ${skill}
 - **Agents started by the board** follow [\`${promptPathOf(repo)}\`](${promptPathOf(repo)}), which starts with the board's core, \`tools/tasks/prompts/core.md\`.
-- **Copied files.** \`tools/tasks/\`, the release helpers in \`scripts/\`, \`${SKILL}\`, and \`${PIPELINE_SKILL}\` come from [${board}](https://github.com/${board}). Don't edit them here: change them there. \`${MANIFEST}\` lists every file it copied, and \`repos init --update\` replaces only those: a file it doesn't list is this repository's own, even at a path breakaway copies to. \`.claude/settings.json\` holds the session hooks that show a cloud agent's output on its task, and they run through \`npx\`, so this repository carries no copy of the CLI.
+- **Copied files.** ${copied}
 - **Taskwarrior** (optional): \`scripts/task\`, or plain \`task\` with direnv after \`direnv allow\`, uses the board with this checkout's own \`.task/\` database, in the \`${repo.slug}\` context. \`npx breakaway setup\` connects the machine once.
 - **Changes reach \`${repo.defaultBranch || 'main'}\` through pull requests**, which the owner merges. Never merge, force-push, or rewrite \`${repo.defaultBranch || 'main'}\`.
 - **Never put a secret or token** in a file, task, comment, or pull request. The board's token lives in \`${dir}/tasks.env\` (or \`$BREAKAWAY_HOME/tasks.env\`) or the cloud environment's credentials, never in this repository.
@@ -368,6 +472,8 @@ export function initPlan({
   url,
   configDir = DEFAULT_DIR,
   update = false,
+  plugin = true,
+  pluginReleased = true,
   sections = {},
   defaulted = [],
 }) {
@@ -376,6 +482,9 @@ export function initPlan({
   const current = [];
   const notes = [];
   const todo = [];
+  // The plugin unless the repository asked for copies (--copies), and copies while the plugin isn't out yet.
+  const usePlugin = plugin && pluginReleased === true;
+  if (plugin && !usePlugin) notes.push(pluginPendingNote(repo.slug, pluginReleased));
   const add = (path, content, extra = {}) => {
     if (readTarget(path) !== null) skipped.push(path);
     else files.push({ path, content, ...extra });
@@ -455,8 +564,22 @@ export function initPlan({
       `${leftover.join(', ')} came with the old copy of the CLI. Nothing here needs them now: delete the ones this repository doesn't use itself.`,
     );
 
-  add('.claude/settings.json', `${JSON.stringify({ hooks: sessionHooks() }, null, 2)}\n`);
-  if (skipped.includes('.claude/settings.json')) {
+  add(
+    '.claude/settings.json',
+    `${JSON.stringify(usePlugin ? pluginSettings() : { hooks: sessionHooks() }, null, 2)}\n`,
+  );
+  if (usePlugin && skipped.includes('.claude/settings.json')) {
+    // Moving to the plugin (BRK-159): --update takes out the hooks repos init wrote and adds the plugin's two keys.
+    const there = readTarget('.claude/settings.json');
+    const moved = withPluginSettings(there);
+    if (update && moved !== null && !sameJson(moved, there)) {
+      skipped.splice(skipped.indexOf('.claude/settings.json'), 1);
+      files.push({ path: '.claude/settings.json', content: moved, changed: true });
+    } else if (!hasPlugin(there))
+      notes.push(
+        `.claude/settings.json is already there${moved === null ? " and isn't JSON" : ''}: add breakaway's plugin to it (${JSON.stringify(pluginSettings())}), or a started agent won't have the tasks skill and its output won't show on its task.${update ? '' : ` npx breakaway repos init ${repo.slug} --update adds it.`}`,
+      );
+  } else if (skipped.includes('.claude/settings.json')) {
     const there = readTarget('.claude/settings.json');
     const rewired = update ? rewireHooks(there) : there;
     if (rewired !== there) {
@@ -471,9 +594,19 @@ export function initPlan({
       );
   }
   if (readTarget('.claude/skills') === null) files.push({ path: '.claude/skills', link: '../.agents/skills' });
-  copy(SKILL, skillFor(read(SKILL), board, repo));
+  if (!usePlugin) copy(SKILL, skillFor(read(SKILL), board, repo));
+  else if (update && readTarget(SKILL) !== null) {
+    // The plugin brings the tasks skill: the copy repos init wrote goes, and a skill of the repository's own stays.
+    if (owns(SKILL)) {
+      removals.push(SKILL);
+      if (String(readTarget('AGENTS.md') ?? '').includes(SKILL))
+        notes.push(
+          `AGENTS.md still names ${SKILL} and the session hooks in .claude/settings.json: the tasks skill and the hooks come from breakaway's plugin now (${PLUGIN}, turned on in .claude/settings.json), so say that there instead.`,
+        );
+    } else theirs.push(SKILL);
+  }
   copy(PIPELINE_SKILL, skillFor(read(PIPELINE_SKILL), board, repo));
-  add('AGENTS.md', agentsMd(repo, board, configDir));
+  add('AGENTS.md', agentsMd(repo, board, configDir, { plugin: usePlugin }));
   if (!skipped.includes('AGENTS.md')) todo.push('AGENTS.md: add how to build in this repository');
 
   const pkg = readTarget('package.json');
@@ -564,5 +697,5 @@ export function initPlan({
   else if (recordThere === record) current.push(MANIFEST);
   else if (update) files.push({ path: MANIFEST, content: record, changed: true });
   else skipped.push(MANIFEST);
-  return { files, removals, skipped, current, notes, todo };
+  return { files, removals, skipped, current, notes, todo, plugin: usePlugin };
 }

package/src/install.js

@@ -158,7 +158,17 @@ export const secretName = (inst, key) => `${inst.secretsPrefix}${key}`;
 export const docsLink = (inst, anchor) => (inst.docs ? `${inst.docs}${anchor ? `#${anchor}` : ''}` : null);
 
 /** The routes `run_worker_first` sends to the Worker; everything else is the web app. */
-export const WORKER_FIRST = ['/api/*', '/v1/*', '/github/*', '/login', '/logout'];
+export const WORKER_FIRST = [
+  '/api/*',
+  '/v1/*',
+  '/github/*',
+  '/mcp',
+  // The sign-in Claude's apps use for /mcp (BRK-157).
+  '/oauth/*',
+  '/.well-known/oauth-*',
+  '/login',
+  '/logout',
+];
 
 /**
  * The Worker's wrangler config for an install. `local` is for `wrangler dev` (interop): no custom