CommandMate

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 38 Open GitHub ↗

Issue-driven AI development IDE for Claude Code and Codex CLI. Run multiple issues in parallel and keep work moving from desktop or mobile.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# CommandMate

[![GitHub Stars](https://img.shields.io/github/stars/Kewton/CommandMate?style=social)](https://github.com/Kewton/CommandMate)
![npm version](https://img.shields.io/npm/v/commandmate)
![npm downloads](https://img.shields.io/npm/dm/commandmate)
![license](https://img.shields.io/github/license/Kewton/CommandMate)
![CI](https://img.shields.io/github/actions/workflow/status/Kewton/CommandMate/ci-pr.yml)
**Status: Beta**

[English](./README.md) | [日本語](./docs/ja/README.md)

**[commandmate website →](https://kewton.github.io/CommandMate/)**

> **Orchestrate your agent CLIs, not your terminal tabs.**

CommandMate is a local control plane for agent CLIs.

```bash
npx commandmate@latest
```

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

---

CommandMate adds orchestration and visibility on top of your existing agent CLIs.
It does not replace tmux, Git worktrees, or your terminal. It makes them easier to manage at scale.

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](https://github.com/Kewton/CommandMate).

---

## Key Features

| 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 | 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](./LICENSE))
- Local database, local sessions
- For remote access, use a tunneling service ([Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/), [ngrok](https://ngrok.com/), [Pinggy](https://pinggy.io/)), a VPN, or an authenticated reverse proxy

See the [Security Guide](./docs/security-guide.md) and [Trust & Safety](./docs/en/TRUST_AND_SAFETY.md) 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.

---

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

Each Git worktree gets its own tmux session, so multiple tasks run in parallel without interference.

---

<details>
<summary>Quick Start (detailed)</summary>

```bash
# 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://localhost:3000 in your browser.

See the [CLI Setup Guide](./docs/en/user-guide/cli-setup-guide.md) for details.
For Windows users, see the [WSL2 Setup Guide](./docs/en/user-guide/wsl2-setup.md) — CommandMate depends on tmux, so it runs on Windows via WSL2 (native Windows is not supported).

</details>

<details>
<summary>CLI Commands</summary>

### 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](./docs/en/user-guide/cli-operations-guide.md) 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](./docs/en/user-guide/cli-operations-guide.md).

**Typical workflow:**

```bash
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:

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

### GitHub Issue Management

Requires [gh CLI](https://cli.github.com/) 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.

</details>

<details>
<summary>Update</summary>

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.

```bash
# 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:

```bash
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](./docs/en/user-guide/cli-setup-guide.md).

See the [Deployment Guide](./docs/en/DEPLOYMENT.md) for exit codes and details.

</details>

<details>
<summary>Troubleshooting & FAQ</summary>

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

```bash
commandmate start -p 3001
```

### Session stuck or not responding?

Check tmux sessions directly. CommandMate manages sessions with the naming format `mcbd-{tool}-{worktree}`:

```bash
# 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](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) — free, requires Cloudflare account
- [ngrok](https://ngrok.com/) — free tier available, easy setup
- [Pinggy](https://pinggy.io/) — 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](./docs/en/TRUST_AND_SAFETY.md) for details.

**Q: Can multiple people use it?**
A: Currently designed for individual use. Simultaneous multi-user access is not supported.

</details>

<details>
<summary>Developer Setup</summary>

For contributors or those building a development environment:

```bash
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)

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

</details>

---

<details>
<summary>Comparison</summary>

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

</details>

---

## Optional Workflow Layer

If your team wants more structure, CommandMate can also help you standardize
issue refinement, design review, planning, implementation, and acceptance checks.
These workflows build on top of the same CLI sessions and worktrees. They are optional, not required.

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](https://github.com/Kewton/CommandMate/issues), [dev reports](./dev-reports/issue/), and [workflow examples](./docs/en/user-guide/workflow-examples.md) in the CommandMate repository.

---

## Documentation

| Document | Description |
|----------|-------------|
| [CLI Setup Guide](./docs/en/user-guide/cli-setup-guide.md) | Installation and initial setup |
| [Web App Guide](./docs/en/user-guide/webapp-guide.md) | Basic web app operations |
| [Quick Start](./docs/en/user-guide/quick-start.md) | Using Claude Code commands |
| [Concept](./docs/en/concept.md) | Vision and problems solved |
| [Architecture](./docs/en/architecture.md) | System design |
| [Deployment Guide](./docs/en/DEPLOYMENT.md) | Production environment setup |
| [UI/UX Guide](./docs/en/UI_UX_GUIDE.md) | UI implementation details |
| [Trust & Safety](./docs/en/TRUST_AND_SAFETY.md) | Security and permissions |

## Contributing

Bug reports, feature suggestions, and documentation improvements are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.

## License

CommandMate

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README