Getting Started

Planu is a plugin for your AI coding tool that helps you plan, track, and verify software features. Instead of repeating yourself in every chat, you create a spec (a short plan with a "done" checklist) and your AI follows it automatically.

It works with any programming language, any framework, and most AI tools — including tools that don't support MCP.

Install

npm install -g @planu/cli

Then configure all your AI tools in one command:

planu install --global

That's it. Planu scans your machine, detects every AI tool you have installed, and configures each one automatically.

$ planu install --global

Scanning for AI tools...
  Claude Code   found  → ~/.claude/claude.json updated
  Cursor        found  → ~/.cursor/mcp.json updated
  Windsurf      found  → ~/.windsurf/mcp.json updated
  OpenCode      found  → ~/.config/opencode/config.json updated
  Codex         found  → AGENTS.md updated

Restart your AI tools. Planu is ready.

No JSON editing. No MCP knowledge required. No config files to learn.

No npm installed?

Run without a global install using npx:

npx @planu/cli@latest install --global

Compatible AI Tools

MCP-compatible tools (plug-and-play)

Planu connects as an MCP server — the open standard for AI plugins:

AI Tool	Auto-detected
Claude Code	✓
Cursor	✓
Windsurf	✓
OpenCode	✓
Zed	✓
Cline (VS Code)	✓
Continue (VS Code)	✓
Claude Desktop	Manual config
Gemini CLI	Manual config

Tools without MCP (CLI + HTTP)

For AI tools that don't support MCP natively, Planu works two ways:

Codex / AGENTS.md style — planu install --codex injects Planu CLI instructions into AGENTS.md. Codex and any LLM that reads agent instruction files will use Planu automatically.

HTTP / OpenAI function calling — start the HTTP server and any LLM with HTTP tool use (GPT-4, Gemini, Kimi, Claude API) can call Planu tools directly:

planu serve --http --port 7823
# Tools available at: POST http://localhost:7823/v1/tools/call
# Tool list at:       GET  http://localhost:7823/v1/tools

Skip permission prompts (recommended)

By default, your AI tool will ask for approval every time Planu uses a tool. To auto-approve all Planu tools (safe — Planu only reads and writes local spec files):

Claude Code

claude settings add permissions.allow "mcp__planu__*"

Or add manually to ~/.claude/settings.json:

{
  "permissions": {
    "allow": ["mcp__planu__*"]
  }
}

Cursor

In Cursor settings → Features → MCP → toggle Auto-approve for the Planu server.

Windsurf / OpenCode

Auto-approve MCP tools by default — no extra config needed.

Why is this safe?

Planu only reads and writes files inside your project's planu/ folder. It never executes code, accesses the internet, or modifies your source files.

Manual installation (for unsupported tools or custom setups)

{
  "mcpServers": {
    "planu": {
      "command": "npx",
      "args": ["--prefer-online", "-y", "@planu/cli@latest"]
    }
  }
}

Claude Code:

claude mcp add planu -- npx -y @planu/cli@latest

Cursor: Open or create ~/.cursor/mcp.json and paste the config block.

Windsurf: Open or create ~/.windsurf/mcp.json and paste the config block.

OpenCode: Open or create ~/.config/opencode/config.json and paste:

{
  "mcp": {
    "planu": { "type": "local", "command": ["planu", "serve"], "enabled": true }
  }
}

Gemini CLI: Open or create ~/.gemini/settings.json and paste the config block.

Codex / AGENTS.md:

planu install --codex     # injects instructions into AGENTS.md

ChatGPT Desktop:

• Mac: ~/Library/Application Support/ChatGPT/config.json
• Windows: %APPDATA%\ChatGPT\config.json

Your First Project

Once installed, just start a conversation with your AI assistant. No commands to memorize.

If you are starting from a parent workspace and want Planu to create a new app, read Project Onboarding Flows first. It explains why Planu should create or confirm the app folder before running init_project.

Example: "I want to add Google login to my app"

That's it. Just say what you want. Planu will automatically:

1. Analyze your project — detects your tech stack, existing code, and structure
2. Create a detailed plan — a spec with acceptance criteria, estimated effort, and technical approach
3. Ask for your approval — you review the plan and approve, request changes, or reject
4. Implement following the plan — code is written according to the approved spec
5. Validate the result — checks that the implementation matches the plan

More things you can say

• "Build me a payment system with Stripe"
• "Add a dark mode toggle to the settings page"
• "Fix the bug where users can't upload large files"
• "Refactor the authentication module to use JWT"
• "I need an API endpoint for user profiles"

You're always in control

• Approve or reject any plan before code is written
• Request changes — "make it simpler" or "add rate limiting"
• Skip the workflow — "just add a console.log" works too
• Track progress — Planu keeps track of what's done and what's pending

That's the whole tutorial. Install, talk, build. Planu handles the rest.

Your AI Ecosystem — Automatic Configuration for Every Tool

If you use more than one AI coding tool, Planu has two commands that will save you hours of configuration work.

ai_ecosystem_status — Health check for every AI tool

Planu scans your machine for installed AI tools and returns a health score (0–100) for each one, showing exactly what is misconfigured, missing, or suboptimal.

Prompt: "What is the health of my AI ecosystem?"

Example output:

Claude Code    82/100   Stop hook: OK, PreCompact: OK, UserPromptSubmit: missing
Gemini CLI     41/100   7 hooks unconfigured, policy engine not set up
Codex CLI       0/100   Not initialized — no AGENTS.md, no config
Cursor         95/100   .cursorrules: OK, MCP server: OK
Windsurf       70/100   .windsurfrules present, no SDD workflow context

Supported tools: Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf, GitHub Copilot, Continue.dev, Aider.

sync_ai_configs — Fix everything at once

Once you know what is missing, sync_ai_configs generates the correct configuration for every tool Planu detected — simultaneously.

Prompt: "Sync my AI configs"

What Planu generates per tool:

• Claude Code — Stop hook, PreCompact, UserPromptSubmit, 14 custom commands, effort levels, profiles
• Codex CLI — AGENTS.md + .codex/config.toml + 3 agent roles (spec-writer, implementer, reviewer)
• Gemini CLI — GEMINI.md + .gemini/settings.json + 11 hooks + policy engine TOML + recommended extensions
• Cursor / Windsurf — .cursorrules / .windsurfrules with SDD workflow context and spec awareness
• Aider — .aider.conf.yml tuned for spec-driven, validated development

One install, zero config effort

Run sync_ai_configs once after installing Planu. From that point on, every AI tool you use is configured for spec-driven development.

Next Steps

• Understand the full SDD Workflow →
• Explore all Planu tools →
• See real-world recipes →