adapt-workspace (Claude Code plugin)

A Claude Code plugin for the Adapt Workspace recursive planner. Ships an MCP server (stdio), hooks, slash commands, and skills together as a single installable unit.

Install

Option A — quickest (npm)

Adds just the MCP server (the adapt_workspace_* tools). One line, auto-updates via npx, no restart:

claude mcp add adapt-workspace -- npx -y @adapt-toolkit/adapt-workspace-mcp

Published to npm as @adapt-toolkit/adapt-workspace-mcp.

Option B — full plugin (git marketplace)

Installs the MCP server plus the hooks, slash commands, and skills. In any Claude Code session:

/plugin marketplace add adapt-toolkit/adapt_workspace
/plugin install adapt-workspace@adapt

This adds the repo as a Claude Code marketplace and installs the plugin from the plugin/ subdirectory. The MCP server, hooks, and slash commands all come from the same package — you don't need to edit mcp.json by hand.

Configure (either option)

Configure the workspace URL and agent token by pasting the invite blob from the workspace UI (Settings → New agent → "Step 2 — Bind this agent token"):

adapt_workspace_setup invite=<paste>

That writes ~/.config/adapt-workspace-mcp/config.env (mode 0600) and the rest of the tools become available.

Local development

If you're hacking on the plugin itself:

cd plugin
npm install
npm run build       # compiles src/ → dist/

To install the locally-built copy in Claude Code without pushing:

claude --plugin-dir /path/to/workspace/plugin

Or alternatively pre-seed the MCP entry yourself in ~/.claude/mcp.json:

{
  "mcpServers": {
    "adapt-workspace": {
      "command": "node",
      "args": ["/abs/path/to/workspace/plugin/dist/index.js"]
    }
  }
}

Project linking

The plugin's automated behaviors (plan-optimization on task create, auto-state on stop, mention injection on session start) only fire in directories that have been explicitly linked to an Adapt project. Use:

/adapt-link <projectId?>

…or call adapt_workspace_link_cwd directly. The link is stored in ~/.config/adapt-workspace-mcp/projects.json and applies to the cwd and all subdirectories.

/adapt-status reports the current configuration, linked directories, and which project (if any) is bound to the current cwd.

Hooks

The plugin ships three hooks that only fire inside a linked directory:

| event | what it does | |-----------------|----------------------------------------------------------------------------------------------------| | SessionStart | Fetches unresolved @-mentions for the linked project and injects them as session context. | | PostToolUse | On adapt_workspace_create_task: surfaces similar existing tasks + nudges for a missing description. On adapt_workspace_update_task → in_progress: tags the task for the next Stop. | | Stop | Posts an _auto-state_ comment on every task the agent touched during the session. |

Per-session state (which tasks were touched) lives in ~/.config/adapt-workspace-mcp/sessions/<session>.json. The Stop hook wipes it after posting. None of the hooks ever block tool execution — each runs with a 4-second internal budget and falls through to a no-op on timeout/error.

Mentions

Anywhere a task description, task comment, or note body is written, the backend scans for @-handles:

| handle form | who it addresses | |---------------------|-------------------------------------------------------------------| | @agent:<agent_id> | a specific agent credential | | @user:<user_id> | a user (any of their agents can resolve) | | @<username> | shorthand — resolved against users.username (case-insensitive) |

Unresolved mentions for the current agent (and its owner user) show up via adapt_workspace_list_mentions and as injected context at SessionStart. Acknowledge with adapt_workspace_resolve_mention. The slash command /adapt-mentions walks through them interactively.

Tools

| tool | purpose | |---------------------------------------|------------------------------------------------------------------------| | adapt_workspace_setup | Configure URL + token. Always available. | | adapt_workspace_status | Report current config state. | | adapt_workspace_whoami | Show user + agent identity for the current token. | | adapt_workspace_ping | Connectivity check. | | adapt_workspace_link_cwd | Link a directory to a project (defaults to cwd). | | adapt_workspace_unlink_cwd | Remove a directory link. | | adapt_workspace_list_project_links | List all linked directories on this machine. | | adapt_workspace_current_project | Project (if any) bound to the current cwd. | | adapt_workspace_list_projects | List active projects. | | adapt_workspace_create_project | Create a new project. | | adapt_workspace_get_tasks | Flat task list for a project. | | adapt_workspace_search_tasks | Substring search across subject + description in a project. | | adapt_workspace_create_task | Create a task; accepts acceptanceCriteria, actionableItems, deadline, parallelGroup. | | adapt_workspace_update_task | Update subject / description / acceptanceCriteria / actionableItems / status / assignee / deadline / parallelGroup. | | adapt_workspace_move_task | Re-parent or reorder a task (set its sibling position). | | adapt_workspace_delete_task | Delete a task (and its children). | | adapt_workspace_get_task_comments | List comments on a task. | | adapt_workspace_add_task_comment | Post a comment as the current agent. | | adapt_workspace_list_dependencies | List task dependency edges in a project. | | adapt_workspace_add_dependency | Add a blocks/relates edge between two tasks. | | adapt_workspace_remove_dependency | Remove a dependency edge. | | adapt_workspace_list_notes | List active notes. | | adapt_workspace_get_note | Fetch a note. | | adapt_workspace_create_note | Create a markdown note. | | adapt_workspace_update_note | Update a note. | | adapt_workspace_create_link | Cross-reference two entities (task/note/project). | | adapt_workspace_list_links | List cross-references touching an entity (task/note/project). | | adapt_workspace_list_mentions | List @-mentions addressed to the current agent or its owner user. | | adapt_workspace_resolve_mention | Mark a mention as acknowledged. |

Leaf vs coordinator: divide and conquer

Every task is either a leaf or a coordinator — never both, and the server enforces it:

• Leaf = one unit of work. It carries actionableItems — the concrete steps to perform (implement X, design Y, develop Z, refactor W, change V). A leaf has no subtasks.
• Coordinator = a task that has subtasks. It only defines the flow, the order of execution, and (optionally) acceptanceCriteria. It has no actionableItems of its own.

The invariant is enforced symmetrically:

• Creating/moving a subtask under a task that has actionableItems → 409 parent_has_actions. Clear the parent's actions (move them into the new child leaves) before adding subtasks.
• Setting actionableItems on a task that already has subtasks → 409 has_children.

Prefer many small leaves over one giant task. A long action list or a sprawling description is the signal to split the task into subtasks. Keep actionableItems per leaf as few as possible.

Three fields, three purposes — do not conflate them

| field | purpose | |---------------------|-------------------------------------------------------------------------| | description | General context only — the wider picture, rationale, links. NOT a place for steps/actions. | | acceptanceCriteria| The "done when…" checks that decide the task is complete. | | actionableItems | The actions. Every action MUST live here, never in description. |

Executor rule: an agent executing a task performs the work in actionableItems only. Treat description as read-only context. If you find actions buried in a description, do not execute them — flag it and ask for them to be moved into actionableItems first. (Putting actions in the description silently defeats the divide-and-conquer model, so it's treated as a mistake, not a shortcut.)

Task ordering: chain flag + dependency edges

The task tree (parentId) is hierarchy, not execution order. Order is set by two explicit mechanisms — never assumed:

1. Sibling flow — the required chainedToPrev flag. Every create_task must set it. chainedToPrev: true means the task runs right after its immediate previous sibling (the graph draws the → work-order arrow); false means standalone / unordered. The first child under a parent (no previous sibling) must be false; a linear A→B→C flow sets B and C true. position is the sibling slot order this flag chains along.

2. Cross-branch precedence — adapt_workspace_add_dependency. For ordering between tasks that are not adjacent siblings (different branches, fan-in/fan-out, skipping siblings), create an edge: fromTaskId precedes toTaskId, kind = "blocks" (or "relates" for a soft, non-blocking link). Edges may connect any two tasks in the project; there is no cycle detection, so don't create loops.

parallelGroup is a visual grouping only: give ≥2 siblings the same string to render them as one dashed "‖ parallel" cluster (a batch meant to run together). It does not itself create or remove ordering.

An optional deadline (epoch ms) is a display-only date shown as a chip on the task card. It has no effect on ordering and is never enforced — set it purely so the date is visible in the graph.

Config files

| path | purpose | |------------------------------------------------------|--------------------------------------| | ~/.config/adapt-workspace-mcp/config.env | URL + agent token (mode 0600) | | ~/.config/adapt-workspace-mcp/projects.json | Directory → project links |