# Install & start in one command
npx commandmate

# Or install globally
npm install -g commandmate
commandmate init
commandmate start --daemon

Open http://localhost:3000 in your browser.

See the CLI Setup Guide for details. For Windows users, see the WSL2 Setup Guide.

Basic

Worktree Parallel Development

Run separate servers per Issue/worktree with automatic port allocation.

Agent Operations

Operate agent sessions from the CLI. See the CLI Operations Guide for details.

Typical workflow:

WT=$(commandmate ls --branch feature/101 --quiet)
commandmate send "$WT" "Implement Issue #101" --auto-yes
commandmate wait "$WT" --timeout 600
commandmate capture "$WT"

For coding agents (Claude Code, Codex, etc.): Have your agent run these commands to get the full guide and workflow samples:

commandmate docs --section agent-operations          # Full guide
commandmate docs --section agent-operations-samples  # Workflow samples

GitHub Issue Management

Requires gh CLI to be installed.

Documentation

See commandmate --help for all options.

Claude CLI not found / path changed?

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.

Port conflict?

commandmate start -p 3001

Session stuck or not responding?

Check 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+b then d to detach and operate through the CommandMate UI instead.

Sessions fail when launching from within Claude Code?

Claude Code sets CLAUDECODE=1 to prevent nesting. CommandMate removes this automatically, but if it persists, run: tmux set-environment -g -u CLAUDECODE

FAQ

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.

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 launch

Manual Setup (for customization)

git 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 start

Note: ./scripts/* scripts are only available in the development environment. For global installs (npm install -g), use the commandmate CLI.