warden-mcp

Warden MCP

Warden MCP is a plan-governance MCP server for coding agents. It keeps agents on a concrete execution plan, makes progress explicit, and blocks premature "done" claims with finish-gate checks.

Fastest setup for Claude Code, Auggie, and most coding agents

If you just want the easiest local install for an MCP-capable coding agent, use npm:

npm install -g warden-mcp
warden-mcp health

Then add this MCP server entry:

{
  "mcpServers": {
    "warden": {
      "command": "warden-mcp",
      "args": []
    }
  }
}

After your client connects, call these tools in order:

1. get_agent_guide
2. health_check
3. get_status

If your client supports Claude Code-style local MCP config, the same warden-mcp entry should work there too. That includes Claude Code directly and Claude-compatible setups such as Auggie-style local MCP flows.

Install

Claude Code plugin marketplace (git repo)

If you prefer Claude Code's plugin flow, this repository ships a repo-root plugin and marketplace entry.

1. In Claude Code, run /plugin marketplace add https://github.com/Blu3Ph4ntom/warden-mcp
2. Open /plugin, install warden-mcp, and enable it for your project or session

The plugin launches Warden with npx -y warden-mcp, so Claude Code downloads the published npm package on first run instead of requiring a separate global install.

This plugin now ships three layers for Claude Code and compatible clients:

• an MCP tool server (.mcp.json)
• lifecycle hooks (hooks/hooks.json) for enforced completion gating
• convenience command files (commands/warden-start.md, commands/warden-next.md, commands/warden-finish.md)

The hooks are the important part: on Stop, the client calls Warden's finish gate and gets blocked from stopping when required work remains.

The shared marketplace hook config intentionally uses a conservative event subset that loads in Augment-compatible clients too. Richer Claude lifecycle events such as TaskCompleted and SubagentStop are not treated as portable defaults.

For the most reliable enforced mode, make sure warden-mcp is also available on your PATH (for example via npm install -g warden-mcp or a released binary). The hooks first try the local warden-mcp binary and only fall back to npx -y warden-mcp if needed.

After installing or updating the plugin, restart Claude Code so the hook configuration reloads.

Recommended for most coding-agent users: npm

This is the easiest path for Claude Code, Auggie, Cursor, Windsurf, Codex, and other local MCP clients.

npm install -g warden-mcp

Verify the install:

warden-mcp health

Native install via Go

Prerequisite: Go 1.24+

go install github.com/Blu3Ph4ntom/warden-mcp/cmd/warden-mcp@latest

Then make sure your Go bin directory is on PATH and verify the binary is available:

warden-mcp health

Native install via npm

If you prefer installing through npm, the published package downloads the correct native warden-mcp binary for your platform during installation.

npm install -g warden-mcp

or:

npx warden-mcp health

This is now a real native install path. Go is not required for npm users, but the installer does need network access to the matching GitHub Release asset for the package version.

Quickstart for coding agents

1. Install warden-mcp with npm or Go.
2. Add warden-mcp as a local MCP server in your client config.
3. If your client can set environment variables, set WARDEN_WORKSPACE_ROOT to your repo root.
4. After connecting, call get_agent_guide, then health_check, then get_status.

If your client does not have a custom startup flow yet, this one works well:

{ "command": "warden-mcp", "args": [] }

What Warden MCP provides

• strict plan initialization and validation
• task updates and next-step selection
• reset, prioritization, and reconciliation flows
• finish-gate enforcement before completion is allowed
• plan import/export/archive utilities

Warden speaks MCP over stdio, so most local MCP clients can launch it with a simple command entry:

{ "command": "warden-mcp", "args": [] }

When launched with no CLI args, warden-mcp now defaults to MCP server (serve) mode so local MCP clients can invoke the command directly.

Tool surface

The current public MCP tools are:

• init_plan, health_check, get_agent_guide, validate_plan, edit_plan
• get_status, get_next_task, prioritize_tasks
• update_task, reset_task, request_finish
• list_plans, import_plan, export_plan, archive_plan
• reconcile_plan

For most clients, the first helpful call after connecting is get_agent_guide or health_check, followed by get_status.

Typical workflow