@planu/cli weekly downloads statistics

Planu

The high-performance SDD Engine for AI coding agents.

What is Planu?

Planu v8 is a thin MCP sandbox + cognitive skills stack for Spec Driven Development. Its supported runtime is FEAT-only and exposes exactly nine canonical tools. Canonical design: PLANU_V8_MANIFESTO.txt.

Spec first, always. No locked trinity means no product code.

• The Holy Trinity — .sdd/features/{FEAT-*}/[spec.md, plan.md, tasks.md]
• Zero-Freedom Execution — mutations and exact DELETE: operations go through sdd_apply_file_patch; the File Manifest is the sandbox
• Single Task Window — sdd_get_active_task + sdd_read_file_slice
• 9 Canonical MCP Tools — listed below
• Cognitive gates — host skills under .claude/skills/planu-*, .cursor/skills/planu-*, and .agents/skills/planu-* replace challenge_spec / check_readiness / validate
• Git Hygiene — git-janitor.md skill (the server does not mutate Git)

Authentication is not required. Do not call mcp_auth.

---

Installation

Install Node.js >=22.13.0 with npm/npx available to your MCP client. Register Planu once using a host option below, then restart its MCP connection so the nine tools are available. Open the project you intend to set up.

Claude Code plugin

Claude Code users can install Planu as a plugin instead of hand-editing .mcp.json:

/plugin marketplace add planu-dev/planu
/plugin install planu@planu

This registers the same npx -y @planu/cli@latest server. planu-dev/planu is not a public source repository. Use a project .mcp.json and do not point the server at $HOME. The plugin also ships planu-guard hooks: while a locked feature has an unchecked task, native Write/Edit inside the workspace is denied in favor of sdd_apply_file_patch; git ... --no-verify is denied; and session start re-injects the active task. Disable them with the plugin manager.

Codex plugin

Codex CLI reads the same marketplace:

codex plugin marketplace add planu-dev/planu
codex plugin add planu@planu

This registers the same npx -y @planu/cli@latest server as MCP server planu. The planu-guard hooks are Claude Code only.

Cursor one-click install

Open this link in a browser with Cursor installed. It installs the server below with PLANU_WORKSPACE bound to ${workspaceFolder}:

cursor://anysphere.cursor-deeplink/mcp/install?name=planu&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBwbGFudS9jbGlAbGF0ZXN0Il0sImVudiI6eyJQTEFOVV9XT1JLU1BBQ0UiOiIke3dvcmtzcGFjZUZvbGRlcn0ifX0=

Paste this into Claude Code, Cursor, Windsurf, Codex, Copilot, Gemini CLI, OpenCode, or any stdio MCP client. Prefer a project config so the host can bind the open folder. A user-global server with no workspace interpolation will start in $HOME and fail closed.

{
  "mcpServers": {
    "planu": {
      "command": "npx",
      "args": ["-y", "@planu/cli@latest"],
      "env": {
        "PLANU_WORKSPACE": "${workspaceFolder}"
      }
    }
  }
}

Host	Where to put it	How the project is bound
Cursor	.cursor/mcp.json (project) or ~/.cursor/mcp.json	${workspaceFolder} is interpolated into PLANU_WORKSPACE (absolute or ~/...). Cursor user-global cwd is not reliable.
Claude Code	.mcp.json in the project	Process cwd is the launch directory; unexpanded ${workspaceFolder} is ignored.
Codex	.codex/config.toml (trusted project) or ~/.codex/config.toml	TOML [mcp_servers.planu]. ChatGPT desktop, Codex CLI, and Codex IDE share this file. Set cwd to the repo. JSON mcpServers is the wrong format.
Copilot / VS Code	.vscode/mcp.json	Top-level key is servers. ${workspaceFolder} is interpolated.
Gemini CLI	.gemini/settings.json	mcpServers JSON. No ${workspaceFolder} interpolation; use repo cwd.
Windsurf	~/.codeium/windsurf/mcp_config.json	User-global Cascade config. Prefer an absolute project PLANU_WORKSPACE; do not use $HOME.
OpenCode	opencode.json	mcp.planu with type: "local" and a command array.
Claude Desktop	claude_desktop_config.json	mcpServers JSON. Set PLANU_WORKSPACE to an absolute project path.
ChatGPT web	Plugins / remote MCP only	Cannot spawn local stdio. Use Codex desktop or CLI for Planu.
Other stdio	Cline, Zed, JetBrains, Amazon Q	Same npx -y @planu/cli@latest process; bind via cwd, roots, or PLANU_WORKSPACE.

npx @planu/cli starts the MCP stdio server (cli, planu, and sdd-engine are the same binary). Each host restart resolves latest from npm.

Local development in this repo:

{
  "mcpServers": {
    "planu": {
      "command": "node",
      "args": ["${workspaceFolder}/dist/sdd-engine/cli.js"],
      "env": {
        "PLANU_WORKSPACE": "${workspaceFolder}"
      }
    }
  }
}

The published server asks the host for MCP roots and binds to the open project that owns .sdd/. Unexpanded ${workspaceFolder} and a PLANU_WORKSPACE equal to $HOME are ignored. A ~/... workspace path is expanded against $HOME so hosts that interpolate tildes still bind the open folder. If the process cwd is still the user home directory, project-scoped tools return ERR_WORKSPACE_UNRESOLVED instead of creating .sdd under $HOME. sdd_init_workspace always writes Planu-owned Cursor, Claude, and Gemini host rules. Existing AGENTS.md is preserved unless force: true or the file still requires planu/specs/SPEC-* or instructs calling create_spec. sdd_lock_spec refuses empty skeletons and can reseal with relock: true and reason. Do not set a shell-global PLANU_WORKSPACE. pnpm start runs the MCP server.…