Move issues forward, not terminal tabs.
CommandMate is an IDE for issue-driven AI development.
npx commandmateFrom install to your first session in 60 seconds. macOS / Linux · Node.js v20+ · npm · git · tmux
Instead of jumping straight into implementation, you define an issue, refine it with AI, review the direction, generate a plan, and then let your coding agent execute. CommandMate helps you run multiple issues in parallel with Git worktrees, choose the right agent for each issue, and keep work moving even when you leave your desk.
If your workflow is shifting from "writing code yourself" to "defining issues, reviewing direction, and accepting outcomes," CommandMate can become the center of your development workflow.
Works on desktop and mobile — monitor and steer sessions from any browser, including your phone.
If this is the kind of AI development workflow you want, give the repo a star.
CommandMate is built for developers who spend less time editing files and more time defining issues, reviewing direction, and accepting outcomes from coding agents. The commands below turn that workflow into a repeatable process.
Define Issue → Refine with AI → Review Direction → Generate Plan → Agent Executes
| Step | Command | What happens |
|---|---|---|
| Refine the issue | /issue-enhance |
AI asks clarifying questions and fills in missing details |
| Review the issue | /multi-stage-issue-review |
Multi-stage review (consistency, impact scope) with automated fixes |
| Review the design | /multi-stage-design-review |
4-stage review (general → consistency → impact → security) |
| Plan the work | /work-plan |
Generates a task breakdown with dependencies |
| Implement via TDD | /tdd-impl |
Red-Green-Refactor cycle, automated |
| Verify acceptance | /acceptance-test |
Validates all acceptance criteria from the issue |
| Create the PR | /create-pr |
Auto-generates title, description, and labels |
| Dev (full) | /pm-auto-dev |
TDD implementation → acceptance test → refactoring → progress report |
| Issue → Dev (full) | /pm-auto-issue2dev |
Issue review → design review → work plan → TDD → acceptance test → refactoring → progress report |
| Design → Dev (full) | /pm-auto-design2dev |
Design review → work plan → TDD → acceptance test → refactoring → progress report |
For details, see the issues, dev reports, and workflow examples in the CommandMate repository.
| Feature | What it does | Why it matters |
|---|---|---|
| Git Worktree Sessions | One session per worktree, parallel execution | Multiple issues progress simultaneously without interference |
| Multi-Agent Support | Choose Claude Code, Codex, Gemini, or local models per issue | Pick the right agent for each task |
| Auto Yes Mode | Agent runs without stopping for confirmations | No babysitting — the agent keeps working while you're away |
| Web UI (Desktop & Mobile) | Full session control from any browser | Monitor and steer from your desk or your phone |
| File Viewer & Markdown Editor | Browse and edit worktree files in the browser | Review changes and update AI instructions without opening an IDE |
| Screenshot Instructions | Attach images to your prompts | Snap a bug → "Fix this" — the agent sees the screenshot |
| Scheduled Execution | Cron-based auto-run via CMATE.md | Daily reviews, nightly tests — agents work on a schedule |
| Token Authentication | SHA-256 hashed token + HTTPS + rate limiting | Secure remote access — no credentials leaked, brute-force protected |
| Scenario | How CommandMate helps |
|---|---|
| Parallel issue development | Run multiple issues in separate worktrees, each with its own agent session |
| Issue refinement | Define an issue, let AI fill gaps, review before any code is written |
| Overnight execution | Queue issues with scheduled execution — check progress in the morning |
| Mobile review | Review AI-generated changes and steer direction from your phone |
| Visual bug fix | Snap a UI bug on your phone, send it with "Fix this" |
Runs 100% locally. No external server, no cloud relay, no account required. The only network traffic is Claude CLI's own API calls.
- Fully open-source (MIT License)
- Local database, local sessions
- For remote access, use a tunneling service (Cloudflare Tunnel, ngrok, Pinggy), a VPN, or an authenticated reverse proxy
See the Security Guide and Trust & Safety for details.
flowchart LR
A["Browser / Phone"] -->|HTTP| B["CommandMate Server"]
B --> C["Session Manager"]
C -->|"spawn / attach"| D["tmux sessions\n(per worktree)"]
D --> E["Claude Code CLI"]
C <-->|"read / write"| F[("Local DB\n& State")]
Each Git worktree gets its own tmux session, so multiple tasks run in parallel without interference.
Quick Start (detailed)
# Install & start in one command
npx commandmate
# Or install globally
npm install -g commandmate
commandmate init
commandmate start --daemonOpen http://localhost:3000 in your browser.
See the CLI Setup Guide for details.
CLI Commands
| Command | Description |
|---|---|
commandmate init |
Initial setup (interactive) |
commandmate init --defaults |
Initial setup (default values) |
commandmate init --force |
Overwrite existing configuration |
commandmate start |
Start the server (foreground) |
commandmate start --daemon |
Start in background |
commandmate start --dev |
Start in development mode |
commandmate start -p 3001 |
Start on a specific port |
commandmate stop |
Stop the server |
commandmate stop --force |
Force stop (SIGKILL) |
commandmate status |
Check status |
Run separate servers per Issue/worktree with automatic port allocation.
| Command | Description |
|---|---|
commandmate start --issue 123 |
Start server for Issue #123 worktree |
commandmate start --issue 123 --auto-port |
Start with automatic port allocation |
commandmate start --issue 123 -p 3123 |
Start on a specific port |
commandmate stop --issue 123 |
Stop server for Issue #123 |
commandmate status --issue 123 |
Check status for Issue #123 |
commandmate status --all |
Check status for all servers |
Requires gh CLI to be installed.
| Command | Description |
|---|---|
commandmate issue create |
Create a new issue |
commandmate issue create --bug |
Create with bug report template |
commandmate issue create --feature |
Create with feature request template |
commandmate issue create --question |
Create with question template |
commandmate issue create --title <title> |
Specify issue title |
commandmate issue create --body <body> |
Specify issue body |
commandmate issue create --labels <labels> |
Add labels (comma-separated) |
commandmate issue search <query> |
Search issues |
commandmate issue list |
List issues |
| Command | Description |
|---|---|
commandmate docs |
Show documentation |
commandmate docs -s <section> |
Show a specific section |
commandmate docs -q <query> |
Search documentation |
commandmate docs --all |
List all available sections |
See commandmate --help for all options.
Troubleshooting & FAQ
If you switch between npm and standalone versions of Claude CLI, the path may change. CommandMate auto-detects the new path on the next session start. To set a custom path, add CLAUDE_PATH=/path/to/claude to .env.
commandmate start -p 3001Check tmux sessions directly. CommandMate manages sessions with the naming format mcbd-{tool}-{worktree}:
# List all CommandMate sessions
tmux list-sessions | grep mcbd
# View session output (without attaching)
tmux capture-pane -t "mcbd-claude-feature-123" -p
# Attach to inspect (detach with Ctrl+b then d)
tmux attach -t "mcbd-claude-feature-123"
# Kill a broken session
tmux kill-session -t "mcbd-claude-feature-123"Note: When attached, avoid typing directly into the session — this can interfere with CommandMate's session management. Use
Ctrl+bthendto detach and operate through the CommandMate UI instead.
Claude Code sets CLAUDECODE=1 to prevent nesting. CommandMate removes this automatically, but if it persists, run: tmux set-environment -g -u CLAUDECODE
Q: How do I use CommandMate from my phone?
A: CommandMate runs a web server on your PC. To access it from your phone, your phone and PC must be on the same network (Wi-Fi). Run commandmate init and enable external access — this sets CM_BIND=0.0.0.0. Then open http://<your-PC-IP>:3000 in your phone's browser.
Q: Can I access it from outside my home network? A: Yes. Use a tunneling service to securely expose your local server without opening router ports:
- Cloudflare Tunnel — free, requires Cloudflare account
- ngrok — free tier available, easy setup
- Pinggy — no sign-up required, simple SSH-based tunnel
Alternatively, a VPN or an authenticated reverse proxy (Basic Auth, OIDC, etc.) also works. Do not expose the server directly to the internet without authentication.
Q: Does it work on iPhone / Android? A: Yes. CommandMate's Web UI is responsive and works on any modern mobile browser (Safari, Chrome, etc.). No app install required.
Q: Is tmux required? A: CommandMate uses tmux internally to manage CLI sessions. You don't need to operate tmux directly — CommandMate handles it for you.
Q: What about Claude Code's permissions? A: Claude Code's own permission settings apply as-is. CommandMate does not expand permissions. See Trust & Safety for details.
Q: Can multiple people use it? A: Currently designed for individual use. Simultaneous multi-user access is not supported.
Developer Setup
For contributors or those building a development environment:
git clone https://github.com/Kewton/CommandMate.git
cd CommandMate
./scripts/setup.sh # Auto-runs dependency check, env setup, build, and launchgit clone https://github.com/Kewton/CommandMate.git
cd CommandMate
./scripts/preflight-check.sh # Dependency check
npm install
./scripts/setup-env.sh # Interactive .env generation
npm run db:init
npm run build
npm startNote:
./scripts/*scripts are only available in the development environment. For global installs (npm install -g), use thecommandmateCLI.
Comparison
| Feature | CommandMate | Remote Control (Official) | Happy Coder | claude-squad | Omnara |
|---|---|---|---|---|---|
| Auto Yes Mode | Yes | No | No | Yes (TUI only) | No |
| Git Worktree Management | Yes | No | No | Yes (TUI only) | No |
| Parallel Sessions | Yes | No (1 only) | Yes | Yes | No |
| Mobile Web UI | Yes | Yes (claude.ai) | Yes | No | Yes |
| File Viewer | Yes | No | No | No | No |
| Markdown Editor | Yes | No | No | No | No |
| Screenshot Instructions | Yes | No | No | Not possible | No |
| Scheduled Execution | Yes | No | No | No | No |
| Survives Laptop Close | Yes (daemon) | No (terminal must stay open) | Yes | Yes | Yes |
| Token Authentication | Yes | N/A (Anthropic account) | N/A (app) | No | N/A (cloud) |
| Free / OSS | Yes | Requires Pro/Max | Free + Paid | Yes | $20/mo |
| Runs 100% Locally | Yes | Via Anthropic API | Server-routed | Yes | Cloud fallback |
| Document | Description |
|---|---|
| CLI Setup Guide | Installation and initial setup |
| Web App Guide | Basic web app operations |
| Quick Start | Using Claude Code commands |
| Concept | Vision and problems solved |
| Architecture | System design |
| Deployment Guide | Production environment setup |
| UI/UX Guide | UI implementation details |
| Trust & Safety | Security and permissions |
Bug reports, feature suggestions, and documentation improvements are welcome. See CONTRIBUTING.md for details.
MIT License - Copyright (c) 2026 Kewton