MAXSIM

A meta-prompting, context engineering, and spec-driven development system for Claude Code, OpenCode, Gemini CLI, and Codex.

Solves context rot — the quality degradation that happens as Claude fills its context window.

npx maxsimcli@latest

Works on Mac, Windows, and Linux.

Getting Started

npx maxsimcli@latest

The installer prompts you to choose:

1. Runtime — Claude Code, OpenCode, Gemini, Codex, or all
2. Location — Global (all projects) or local (current project only)

Verify with:

• Claude Code / Gemini: /maxsim:help
• OpenCode: /maxsim-help
• Codex: $maxsim-help

npx maxsimcli --claude --global    # Claude Code → ~/.claude/
npx maxsimcli --opencode --global  # OpenCode → ~/.config/opencode/
npx maxsimcli --gemini --global    # Gemini CLI → ~/.gemini/
npx maxsimcli --codex --global     # Codex → ~/.codex/
npx maxsimcli --all --global       # All runtimes

Add --local instead of --global for project-scoped installs.

How It Works

1. Initialize Project

/maxsim:new-project

Questions → Research → Requirements → Roadmap. One command captures your idea, scopes v1/v2, and creates a phased build plan.

2. Discuss Phase

/maxsim:discuss-phase 1

Shape the implementation before anything gets built. The system identifies gray areas and asks until your vision is clear.

3. Plan Phase

/maxsim:plan-phase 1

Researches how to implement, creates atomic task plans, and verifies them against requirements.

4. Execute Phase

/maxsim:execute-phase 1

Runs plans in parallel waves with fresh context per plan. Each task gets its own atomic commit. Verifies the codebase delivers what the phase promised.

5. Verify Work

/maxsim:verify-work 1

Walk through testable deliverables one by one. If something's broken, the system creates fix plans automatically.

6. Repeat → Ship

/maxsim:complete-milestone
/maxsim:new-milestone

Loop discuss → plan → execute → verify until done. Archive the milestone and start the next version.

Commands

Core Workflow

| Command | Description | |---------|-------------| | /maxsim:new-project | Initialize: questions → research → requirements → roadmap | | /maxsim:discuss-phase [N] | Capture implementation decisions before planning | | /maxsim:plan-phase [N] | Research + plan + verify for a phase | | /maxsim:execute-phase <N> | Execute plans in parallel waves | | /maxsim:verify-work [N] | User acceptance testing | | /maxsim:complete-milestone | Archive milestone, tag release | | /maxsim:new-milestone | Start next version |

Navigation & Utilities

| Command | Description | |---------|-------------| | /maxsim:progress | Where am I? What's next? | | /maxsim:help | Show all commands | | /maxsim:quick | Ad-hoc task with atomic commits | | /maxsim:debug [desc] | Systematic debugging with persistent state | | /maxsim:map-codebase | Analyze existing codebase | | /maxsim:pause-work | Create handoff when stopping mid-phase | | /maxsim:resume-work | Restore from last session |

Live Dashboard

| Command | Description | |---------|-------------| | npx maxsimcli dashboard | Launch the live project dashboard |

MAXSIM includes a real-time web dashboard that shows phase progress, open tasks, blockers, and allows inline plan editing.

npx maxsimcli dashboard

The dashboard auto-detects a free port starting from 3333 and opens your browser. It watches .planning/ for changes and updates in real-time via WebSocket.

• Auto-installed during npx maxsimcli@latest -- no separate setup needed
• Works with both global and local installs
• Auto-opens browser on launch
• Detects running instances -- won't start a duplicate server
• Auto-launches during /maxsim:execute-phase

Features:

• Real-time updates via WebSocket -- edit a .planning/ file and the dashboard refreshes instantly
• Phase overview with animated progress bars and milestone stats
• Phase drill-down with plan tasks and toggleable checkboxes
• Inline CodeMirror Markdown editor for plan files (Ctrl+S to save)
• Todos panel -- create, complete, and manage todos
• Blockers panel -- view and resolve blockers from STATE.md
• Swiss Style Design dark theme

Phase Management

| Command | Description | |---------|-------------| | /maxsim:add-phase | Append phase to roadmap | | /maxsim:insert-phase [N] | Insert urgent work between phases | | /maxsim:remove-phase [N] | Remove future phase, renumber | | /maxsim:settings | Configure model profile and workflow agents |

Configuration

Project settings live in .planning/config.json, created during /maxsim:new-project or editable via /maxsim:settings.

Model Profiles control which Claude model each agent uses:

| Profile | Planning | Execution | Verification | |---------|----------|-----------|--------------| | quality | Opus | Opus | Sonnet | | balanced (default) | Opus | Sonnet | Sonnet | | budget | Sonnet | Sonnet | Haiku |

Switch with /maxsim:set-profile <profile>.

License

MIT License. See LICENSE for details.

Built and maintained by MayStudios.