CommandMate

Status: Beta

English | 日本語

commandmate website →

From vibe coding to Vibe Engineering.

Vibe Engineering — the AI does the building; the system, not your expertise, guarantees the engineering.

npx commandmate@latest

From install to your first session in 60 seconds. macOS / Linux / Windows (WSL2) · Node.js v22+ · npm · git · tmux

CommandMate adds the machinery — a contract before the work, verification gates after it, Skills that carry the method — on top of the agent CLIs you already use. It does not replace tmux, Git worktrees, your terminal, or your agent CLI. It puts a frame around them, so the work arrives verified instead of merely finished.

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.

Key Features

| Feature | What it does | Why it matters | |---------|-------------|----------------| | Task Contract | Declare the goal, the changeable scope and the gates before the work starts, then send --contract hands them to the agent | The agent works to a written definition of done instead of guessing at one | | Verification Gates | Gates declared in .commandmate/verify.yaml run through verify / wait --verify and return exit 0 / 20 / 21 | "Done" is what a verification run returned, not what the agent said | | Evidence & Metrics | The built-in work-evidence and scope gates, plus verify history, task show and report metrics | Commits, gate logs and numbers are left behind for the next decision | | Skills Catalog | Install and update official Skills per worktree, from the web UI or commandmate skill | The method is installed for the agent to read, not kept in someone's head | | Never miss a waiting agent | A waiting agent shows up as a badge, a toast, the tab title, the PWA app badge and a push notification | You find out the moment an agent needs you, even away from the desk | | Git Worktree Sessions | One session per worktree, parallel execution | Multiple issues progress simultaneously without interference | | Multi-Agent Support | Choose Claude Code, Codex, Gemini CLI, Copilot, OpenCode, Antigravity or local models per worktree | Pick the right agent for each task | | Auto Yes Mode | Agent runs without stopping for confirmations | Optional unattended mode for trusted workflows — review the Security section before enabling | | 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 |

Use Cases

| 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" |

Security

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.

Install as an App (PWA)

CommandMate is a Progressive Web App. On a mobile browser, use Add to Home Screen to launch it full-screen (standalone), which is ideal for monitoring agents on the go. A Service Worker precaches static assets and shows an offline fallback screen; API responses, the login page, and WebSocket traffic are never cached.

HTTPS is required for installation. Browsers only register a Service Worker (and offer install) on https:// or http://localhost. When accessing a self-hosted instance over plain HTTP on the LAN (e.g. http://192.168.x.x:3000), install and offline support are disabled by the browser — use a tunnel or an HTTPS reverse proxy (see Security above) to enable them. The app itself remains fully usable without the PWA layer.

Phone notifications (Web Push)

Once installed, CommandMate can push a notification to your phone while the app is closed — an agent waiting for you, a verification gate that failed, a session that could not start.

It is off until you generate a VAPID key pair. commandmate init generates one and writes CM_VAPID_PUBLIC_KEY / CM_VAPID_PRIVATE_KEY / CM_VAPID_SUBJECT into .env; when they are missing, the startup log and commandmate status say so in one line. iOS/iPadOS additionally require the Home Screen install above — a Safari tab cannot subscribe. Full setup, including the HTTPS requirement and what to do when nothing arrives: Web App Guide -> Phone Notifications.

Browser Support

The web UI is built with Tailwind CSS 4, which targets modern browsers and relies on @property and color-mix() for its color and theming layer. The minimum supported versions are:

| Browser | Minimum version | |---------|-----------------| | Safari (macOS / iOS) | 16.4+ | | Chrome / Edge | 111+ | | Firefox | 128+ |

Older browsers will load the app but render it with degraded colors and spacing. CommandMate is a local developer tool, so this matches the browsers a current development machine or phone will already have.

How it works

flowchart LR
    A["Browser / Phone"] -->|HTTP| B["CommandMate Server"]
    B --> C["Session Manager"]
    G["Task Contract\n.commandmate/tasks/*.yaml"] --> C
    C -->|"spawn / attach"| D["tmux sessions\n(per worktree)"]
    D --> E["Agent CLI"]
    C <-->|"read / write"| F[("Local DB\n& State")]
    E --> H["Verification Gates\n.commandmate/verify.yaml"]
    H -->|"exit 0 / 20 / 21"| B

Each Git worktree gets its own tmux session, so multiple tasks run in parallel without interference. The contract goes in before the session starts; the gates run after it stops, and their exit code is the verdict.

# Try it in one command (guided setup)
npx commandmate@latest

# Or install globally — recommended if you plan to keep the server running
npm install -g commandmate
commandmate init
commandmate start --daemon

Always write npx commandmate@latest, not bare npx commandmate. If CommandMate is already installed globally, bare npx commandmate runs that existing binary without ever checking the registry, so you silently keep running an old version. @latest forces npx to resolve the newest release. This only affects npx — npm install -g commandmate always resolves from the registry.

For anything beyond a first look, prefer the global install. npx unpacks CommandMate into the npm cache, and commandmate start --daemon runs the background server out of that cache directory — a later npx run or a cache clean can delete it out from under the running server.

Running commandmate with no arguments walks you through the whole first run: it checks your dependencies, asks a few setup questions on first use, starts the server in the background, waits for it to come up, and opens the UI in your browser.

Run it again later and it skips straight to opening the UI (or tells you the server is already running). Requires Node.js 22 or later.

• Already have a .env? The setup questions are skipped.
• Don't want the browser to open? Use commandmate --no-open (also skipped automatically on CI and headless sessions).
• Otherwise, open http://127.0.0.1:3000 in your browser. CommandMate binds 127.0.0.1 by default, and localhost can resolve to ::1 (IPv6) first — an address CommandMate does not listen on, and another process may.

See the CLI Setup Guide for details. For Windows users, see the WSL2 Setup Guide — CommandMate depends on tmux, so it runs on Windows via WSL2 (native Windows is not supported).

Basic

| 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 | | commandmate update | Update to the latest version |

Worktree Parallel Development

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 |

Agent Operations

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

| Command | Description | |---------|-------------| | commandmate ls | List worktrees with status (idle/ready/running/waiting) | | commandmate ls --json | JSON output (for agent consumption) | | commandmate ls --quiet | IDs only, one per line (for piping) | | commandmate ls --branch feature/ | Filter by branch name prefix | | commandmate ls --id <prefix> | Filter by worktree ID prefix | | commandmate send <id> "message" | Send a message to an agent | | commandmate send <id> "msg" --auto-yes | Send with auto-yes enabled | | commandmate send <id> "msg" --instance codex | Send to a specific agent instance | | commandmate wait <id> --timeout 300 | Wait for agent completion (exit 0) or prompt (exit 10) | | commandmate wait <id> --instance codex | Wait on a specific agent instance | | commandmate wait <id> --on-prompt human | Wait, let human respond to prompts via browser UI | | commandmate respond <id> "yes" | Respond to an agent's prompt | | commandmate capture <id> | Get current terminal output | | commandmate capture <id> --json | Get output with status info as JSON | | commandmate auto-yes <id> --enable | Enable auto-yes (default 1h) | | commandmate auto-yes <id> --disable | Disable auto-yes |

Name the target with --instance, on every command. It is the only target flag wait accepts — wait --agent fails with unknown option. Naming the agent only on send leaves wait watching the worktree's default agent, so a worktree cut for Codex silently waits for Claude Code. --agent still works on send/respond/capture/auto-yes as the supplement for instances the roster does not know (it is what --register needs). See the CLI Operations Guide.

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.

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

Documentation

| 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.

If you installed globally (npm install -g commandmate), one command does everything — it stops the server, installs the latest version, restarts it, and checks that it came back up.

# See whether an update is available (changes nothing)
commandmate update --check

# Update (asks for confirmation)
commandmate update

# Non-interactive environments (CI, scripts) require --yes
commandmate update --yes

Your data is safe. Database migrations run automatically the next time the server starts, so your worktrees, sessions, and settings carry over. There is no manual migration step.

Manual update (fallback) — if commandmate update is unavailable:

commandmate stop
npm install -g commandmate@latest
commandmate start --daemon

Notes:

• After updating, the server restarts using only your .env. If you had started it with flags such as --auth / --cert / --key / --allowed-ips / --trust-proxy / --port, start it again manually with those flags (--auth generates a new token on each start).
• Worktree servers (--issue) are not stopped automatically. Stop them with commandmate stop --issue <number> before updating.
• On permission errors (EACCES), don't re-run with sudo — fix your npm global directory permissions using the CLI Setup Guide.

See the Deployment Guide for exit codes and details.

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.

The comparison that matters is not against other products; it is against the way of working.

| Dimension | Vibe coding | Vibe Engineering with CommandMate | |---|---|---| | What "done" means | The agent says it's done | A verification run says so — exit 0 / 20 / 21 | | Scope of change | Whatever the agent touched | Declared in the contract, enforced by the scope gate | | Method | In someone's head | Installed as Skills from the Catalog (cmate-task-contract, cmate-verify, …) | | Evidence | A chat transcript | Commits, gate logs, verify history, report metrics | | Parallel work | Terminal tabs | One worktree and one contract per task | | When it stops | You notice, eventually | Waiting is surfaced: badge, toast, tab title, push | | Which agent | Locked to one | Claude Code, Codex, Gemini CLI, Copilot, OpenCode, Antigravity, local models |

Vibe Engineering workflow

We do not make the AI smarter. We make the software-engineering ability its user needed into a system. That system is three things you can hand to any agent: the method, as installed Skills; the contract, declared before the work; the gates, which decide afterwards whether the work is done.

Requirement → Contract → Agent runs (any CLI, per worktree) → Verified result

1. Install the method as Skills

Skills come from the official Catalog (Kewton/commandmate-skills) and install into the worktree you choose — from the web UI (/skills, or the Skills pane of a worktree) or from the CLI.

commandmate skill list
commandmate skill install cmate-task-contract --worktree <worktree-id> --version <version> --yes

| Skill | What it covers | |-------|----------------| | cmate-issue-authoring | Turns a feature description into a set of implementable issues | | cmate-issue-refinement | Refines a vague issue into an implementable specification, read-only | | cmate-task-contract | Drafts .commandmate/tasks/<name>.yaml from an issue: goal, scope, gates | | cmate-verify | Declares the gates in .commandmate/verify.yaml and runs them for a real exit code | | cmate-verify-advisor | Proposes gate improvements from the verification history | | cmate-worker-development | The six steps a worker follows: read, investigate, plan, implement, verify, evidence | | cmate-acceptance-test | Checks the issue's acceptance criteria and returns Go / Conditional Go / No-Go | | cmate-orchestrate | Plans several issues in parallel, dispatches them with contracts, judges by exit code |

The Catalog also publishes cmate-repository-analysis, cmate-orchestrate-monitor, cmate-worktree-setup and cmate-worktree-cleanup. See the Skills guide for the support matrix, the install roots, and the rollback story.

2. Declare the contract, then let the gates judge

# .commandmate/tasks/issue-123.yaml declares goal, scope.allow / scope.deny and the gates to run
commandmate send <worktree-id> --contract .commandmate/tasks/issue-123.yaml
commandmate wait <worktree-id> --verify

--contract supplies the message, so you do not pass one yourself. wait --verify runs the gates once the agent stops and returns the verdict as its exit code: 0 everything passed, 20 a gate failed, 21 the work-evidence gate found neither a commit nor an uncommitted change.

The contract format is specified in Task Contract, the gate format in Verification gates — both specifications are written in Japanese, but the YAML they specify is the same on either side.

Read next

| Document | What it gives you | |----------|-------------------| | Concept | The Vision, the Mission, and how each implementation item maps to a feature | | Tutorial | Fork a sample repository and run one task through contract and verification in about fifteen minutes | | Product Highlights | A feature-by-feature tour of the product | | CLI Operations Guide | Every agent-facing command, in depth |

Developing CommandMate itself? The /work-plan, /pm-auto-dev and other slash commands under .claude/commands belong to this repository only — they are not installed into yours, and the portable equivalents are the Catalog Skills above. See the Commands guide.

Documentation

| Document | Description | |----------|-------------| | CLI Setup Guide | Installation and initial setup | | Tutorial | Fork a sample repository and go from contract to verified result in about fifteen minutes | | Web App Guide | Basic web app operations | | Quick Start | Using Claude Code commands | | CLI Operations Guide | Driving sessions from the CLI: execution contracts, verification gates, Skills, agent instances | | Concept | The canonical Vision, Mission and core principle, and how each implementation item maps to a feature | | Product Highlights | A feature-by-feature tour of the product | | Skills Guide | Installing official Catalog Skills into a worktree | | Agent Event Hooks | Structured agent events instead of terminal scraping | | Architecture | System design | | Deployment Guide | Production environment setup | | UI/UX Guide | UI implementation details | | Trust & Safety | Security and permissions |

Contributing

Bug reports, feature suggestions, and documentation improvements are welcome. See CONTRIBUTING.md for details.

License

MIT License - Copyright (c) 2026 Kewton