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 (a "plan" — tasks are recursive). | | adapt_workspace_update_task | Update subject / description / status / assignee. | | adapt_workspace_move_task | Re-parent or reorder a task. | | 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. |

Config files

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