{"id":43110960,"url":"https://github.com/kewton/commandmate","last_synced_at":"2026-04-01T20:52:42.368Z","repository":{"id":324811210,"uuid":"1097615367","full_name":"Kewton/CommandMate","owner":"Kewton","description":"Your coding companion - lightweight terminal session manager for code agents","archived":false,"fork":false,"pushed_at":"2026-02-17T05:02:29.000Z","size":14820,"stargazers_count":0,"open_issues_count":22,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-17T10:55:29.775Z","etag":null,"topics":["claude-code","commandmate","developer-tools","git-worktree","nextjs","terminal","tmux","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kewton.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-16T14:18:16.000Z","updated_at":"2026-02-17T05:00:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Kewton/CommandMate","commit_stats":null,"previous_names":["kewton/mycodebranchdesk","kewton/commandmate"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/Kewton/CommandMate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kewton%2FCommandMate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kewton%2FCommandMate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kewton%2FCommandMate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kewton%2FCommandMate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kewton","download_url":"https://codeload.github.com/Kewton/CommandMate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kewton%2FCommandMate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29642907,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T05:21:04.652Z","status":"ssl_error","status_checked_at":"2026-02-20T05:21:04.238Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","commandmate","developer-tools","git-worktree","nextjs","terminal","tmux","typescript"],"created_at":"2026-01-31T18:22:55.568Z","updated_at":"2026-04-01T20:52:42.356Z","avatar_url":"https://github.com/Kewton.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CommandMate\n\n[![GitHub Stars](https://img.shields.io/github/stars/Kewton/CommandMate?style=social)](https://github.com/Kewton/CommandMate)\n![npm version](https://img.shields.io/npm/v/commandmate)\n![npm downloads](https://img.shields.io/npm/dm/commandmate)\n![license](https://img.shields.io/github/license/Kewton/CommandMate)\n![CI](https://img.shields.io/github/actions/workflow/status/Kewton/CommandMate/ci-pr.yml)\n**Status: Beta**\n\n[English](./README.md) | [日本語](./docs/ja/README.md)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/images/demo-desktop.gif\" width=\"600\" alt=\"CommandMate Desktop Demo\" /\u003e\n\u003c/p\u003e\n\n\u003e **Orchestrate your agent CLIs, not your terminal tabs.**\n\nCommandMate is a local control plane for agent CLIs.\n\n```bash\nnpx commandmate\n```\n\n**From install to your first session in 60 seconds.** macOS / Linux / Windows (WSL2) · Node.js v20+ · npm · git · tmux\n\n---\n\nCommandMate adds orchestration and visibility on top of your existing agent CLIs.\nIt does not replace tmux, Git worktrees, or your terminal. It makes them easier to manage at scale.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/images/demo-mobile.gif\" width=\"300\" alt=\"CommandMate Mobile Demo\" /\u003e\n\u003c/p\u003e\n\nWorks on desktop and mobile — monitor and steer sessions from any browser, including your phone.\n\nIf this is the kind of AI development workflow you want, [give the repo a star](https://github.com/Kewton/CommandMate).\n\n---\n\n## Key Features\n\n| Feature | What it does | Why it matters |\n|---------|-------------|----------------|\n| **Git Worktree Sessions** | One session per worktree, parallel execution | Multiple issues progress simultaneously without interference |\n| **Multi-Agent Support** | Choose Claude Code, Codex, Gemini, or local models per issue | Pick the right agent for each task |\n| **Auto Yes Mode** | Agent runs without stopping for confirmations | Optional unattended mode for trusted workflows — review the Security section before enabling |\n| **Web UI (Desktop \u0026 Mobile)** | Full session control from any browser | Monitor and steer from your desk or your phone |\n| **File Viewer \u0026 Markdown Editor** | Browse and edit worktree files in the browser | Review changes and update AI instructions without opening an IDE |\n| **Screenshot Instructions** | Attach images to your prompts | Snap a bug → \"Fix this\" — the agent sees the screenshot |\n| **Scheduled Execution** | Cron-based auto-run via CMATE.md | Daily reviews, nightly tests — agents work on a schedule |\n| **Token Authentication** | SHA-256 hashed token + HTTPS + rate limiting | Secure remote access — no credentials leaked, brute-force protected |\n\n---\n\n## Use Cases\n\n| Scenario | How CommandMate helps |\n|----------|----------------------|\n| **Parallel issue development** | Run multiple issues in separate worktrees, each with its own agent session |\n| **Issue refinement** | Define an issue, let AI fill gaps, review before any code is written |\n| **Overnight execution** | Queue issues with scheduled execution — check progress in the morning |\n| **Mobile review** | Review AI-generated changes and steer direction from your phone |\n| **Visual bug fix** | Snap a UI bug on your phone, send it with \"Fix this\" |\n\n---\n\n## Security\n\nRuns **100% locally**. No external server, no cloud relay, no account required. The only network traffic is Claude CLI's own API calls.\n\n- Fully open-source ([MIT License](./LICENSE))\n- Local database, local sessions\n- 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\n\nSee the [Security Guide](./docs/security-guide.md) and [Trust \u0026 Safety](./docs/en/TRUST_AND_SAFETY.md) for details.\n\n---\n\n## How it works\n\n```mermaid\nflowchart LR\n    A[\"Browser / Phone\"] --\u003e|HTTP| B[\"CommandMate Server\"]\n    B --\u003e C[\"Session Manager\"]\n    C --\u003e|\"spawn / attach\"| D[\"tmux sessions\\n(per worktree)\"]\n    D --\u003e E[\"Claude Code CLI\"]\n    C \u003c--\u003e|\"read / write\"| F[(\"Local DB\\n\u0026 State\")]\n```\n\nEach Git worktree gets its own tmux session, so multiple tasks run in parallel without interference.\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eQuick Start (detailed)\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n# Install \u0026 start in one command\nnpx commandmate\n\n# Or install globally\nnpm install -g commandmate\ncommandmate init\ncommandmate start --daemon\n```\n\nOpen http://localhost:3000 in your browser.\n\nSee the [CLI Setup Guide](./docs/en/user-guide/cli-setup-guide.md) for details.\nFor Windows users, see the [WSL2 Setup Guide](./docs/user-guide/wsl2-setup.md).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCLI Commands\u003c/strong\u003e\u003c/summary\u003e\n\n### Basic\n\n| Command | Description |\n|---------|-------------|\n| `commandmate init` | Initial setup (interactive) |\n| `commandmate init --defaults` | Initial setup (default values) |\n| `commandmate init --force` | Overwrite existing configuration |\n| `commandmate start` | Start the server (foreground) |\n| `commandmate start --daemon` | Start in background |\n| `commandmate start --dev` | Start in development mode |\n| `commandmate start -p 3001` | Start on a specific port |\n| `commandmate stop` | Stop the server |\n| `commandmate stop --force` | Force stop (SIGKILL) |\n| `commandmate status` | Check status |\n\n### Worktree Parallel Development\n\nRun separate servers per Issue/worktree with automatic port allocation.\n\n| Command | Description |\n|---------|-------------|\n| `commandmate start --issue 123` | Start server for Issue #123 worktree |\n| `commandmate start --issue 123 --auto-port` | Start with automatic port allocation |\n| `commandmate start --issue 123 -p 3123` | Start on a specific port |\n| `commandmate stop --issue 123` | Stop server for Issue #123 |\n| `commandmate status --issue 123` | Check status for Issue #123 |\n| `commandmate status --all` | Check status for all servers |\n\n### Agent Operations\n\nOperate agent sessions from the CLI. See the [CLI Operations Guide](./docs/en/user-guide/cli-operations-guide.md) for details.\n\n| Command | Description |\n|---------|-------------|\n| `commandmate ls` | List worktrees with status (idle/ready/running/waiting) |\n| `commandmate ls --json` | JSON output (for agent consumption) |\n| `commandmate ls --quiet` | IDs only, one per line (for piping) |\n| `commandmate ls --branch feature/` | Filter by branch name prefix |\n| `commandmate send \u003cid\u003e \"message\"` | Send a message to an agent |\n| `commandmate send \u003cid\u003e \"msg\" --auto-yes` | Send with auto-yes enabled |\n| `commandmate send \u003cid\u003e \"msg\" --agent codex` | Send to a specific agent |\n| `commandmate wait \u003cid\u003e --timeout 300` | Wait for agent completion (exit 0) or prompt (exit 10) |\n| `commandmate wait \u003cid\u003e --on-prompt human` | Wait, let human respond to prompts via browser UI |\n| `commandmate respond \u003cid\u003e \"yes\"` | Respond to an agent's prompt |\n| `commandmate capture \u003cid\u003e` | Get current terminal output |\n| `commandmate capture \u003cid\u003e --json` | Get output with status info as JSON |\n| `commandmate auto-yes \u003cid\u003e --enable` | Enable auto-yes (default 1h) |\n| `commandmate auto-yes \u003cid\u003e --disable` | Disable auto-yes |\n\n**Typical workflow:**\n\n```bash\nWT=$(commandmate ls --branch feature/101 --quiet)\ncommandmate send \"$WT\" \"Implement Issue #101\" --auto-yes\ncommandmate wait \"$WT\" --timeout 600\ncommandmate capture \"$WT\"\n```\n\n**For coding agents (Claude Code, Codex, etc.):** Have your agent run these commands to get the full guide and workflow samples:\n\n```bash\ncommandmate docs --section agent-operations          # Full guide\ncommandmate docs --section agent-operations-samples  # Workflow samples\n```\n\n### GitHub Issue Management\n\nRequires [gh CLI](https://cli.github.com/) to be installed.\n\n| Command | Description |\n|---------|-------------|\n| `commandmate issue create` | Create a new issue |\n| `commandmate issue create --bug` | Create with bug report template |\n| `commandmate issue create --feature` | Create with feature request template |\n| `commandmate issue create --question` | Create with question template |\n| `commandmate issue create --title \u003ctitle\u003e` | Specify issue title |\n| `commandmate issue create --body \u003cbody\u003e` | Specify issue body |\n| `commandmate issue create --labels \u003clabels\u003e` | Add labels (comma-separated) |\n| `commandmate issue search \u003cquery\u003e` | Search issues |\n| `commandmate issue list` | List issues |\n\n### Documentation\n\n| Command | Description |\n|---------|-------------|\n| `commandmate docs` | Show documentation |\n| `commandmate docs -s \u003csection\u003e` | Show a specific section |\n| `commandmate docs -q \u003cquery\u003e` | Search documentation |\n| `commandmate docs --all` | List all available sections |\n\nSee `commandmate --help` for all options.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTroubleshooting \u0026 FAQ\u003c/strong\u003e\u003c/summary\u003e\n\n### Claude CLI not found / path changed?\n\nIf 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`.\n\n### Port conflict?\n\n```bash\ncommandmate start -p 3001\n```\n\n### Session stuck or not responding?\n\nCheck tmux sessions directly. CommandMate manages sessions with the naming format `mcbd-{tool}-{worktree}`:\n\n```bash\n# List all CommandMate sessions\ntmux list-sessions | grep mcbd\n\n# View session output (without attaching)\ntmux capture-pane -t \"mcbd-claude-feature-123\" -p\n\n# Attach to inspect (detach with Ctrl+b then d)\ntmux attach -t \"mcbd-claude-feature-123\"\n\n# Kill a broken session\ntmux kill-session -t \"mcbd-claude-feature-123\"\n```\n\n\u003e **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.\n\n### Sessions fail when launching from within Claude Code?\n\nClaude Code sets `CLAUDECODE=1` to prevent nesting. CommandMate removes this automatically, but if it persists, run: `tmux set-environment -g -u CLAUDECODE`\n\n### FAQ\n\n**Q: How do I use CommandMate from my phone?**\nA: 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://\u003cyour-PC-IP\u003e:3000` in your phone's browser.\n\n**Q: Can I access it from outside my home network?**\nA: Yes. Use a tunneling service to securely expose your local server without opening router ports:\n\n- [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) — free, requires Cloudflare account\n- [ngrok](https://ngrok.com/) — free tier available, easy setup\n- [Pinggy](https://pinggy.io/) — no sign-up required, simple SSH-based tunnel\n\nAlternatively, a VPN or an authenticated reverse proxy (Basic Auth, OIDC, etc.) also works. **Do not** expose the server directly to the internet without authentication.\n\n**Q: Does it work on iPhone / Android?**\nA: Yes. CommandMate's Web UI is responsive and works on any modern mobile browser (Safari, Chrome, etc.). No app install required.\n\n**Q: Is tmux required?**\nA: CommandMate uses tmux internally to manage CLI sessions. You don't need to operate tmux directly — CommandMate handles it for you.\n\n**Q: What about Claude Code's permissions?**\nA: Claude Code's own permission settings apply as-is. CommandMate does not expand permissions. See [Trust \u0026 Safety](./docs/en/TRUST_AND_SAFETY.md) for details.\n\n**Q: Can multiple people use it?**\nA: Currently designed for individual use. Simultaneous multi-user access is not supported.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDeveloper Setup\u003c/strong\u003e\u003c/summary\u003e\n\nFor contributors or those building a development environment:\n\n```bash\ngit clone https://github.com/Kewton/CommandMate.git\ncd CommandMate\n./scripts/setup.sh  # Auto-runs dependency check, env setup, build, and launch\n```\n\n### Manual Setup (for customization)\n\n```bash\ngit clone https://github.com/Kewton/CommandMate.git\ncd CommandMate\n./scripts/preflight-check.sh          # Dependency check\nnpm install\n./scripts/setup-env.sh                # Interactive .env generation\nnpm run db:init\nnpm run build\nnpm start\n```\n\n\u003e **Note**: `./scripts/*` scripts are only available in the development environment. For global installs (`npm install -g`), use the `commandmate` CLI.\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eComparison\u003c/strong\u003e\u003c/summary\u003e\n\n| Feature | CommandMate | Remote Control (Official) | Happy Coder | claude-squad | Omnara |\n|---------|:-----------:|:------------------------:|:-----------:|:------------:|:------:|\n| Auto Yes Mode | Yes | No | No | Yes (TUI only) | No |\n| Git Worktree Management | Yes | No | No | Yes (TUI only) | No |\n| Parallel Sessions | Yes | **No (1 only)** | Yes | Yes | No |\n| Mobile Web UI | Yes | Yes (claude.ai) | Yes | **No** | Yes |\n| File Viewer | Yes | No | No | No | No |\n| Markdown Editor | Yes | No | No | No | No |\n| Screenshot Instructions | Yes | No | No | Not possible | No |\n| Scheduled Execution | Yes | No | No | No | No |\n| Survives Laptop Close | Yes (daemon) | **No (terminal must stay open)** | Yes | Yes | Yes |\n| Token Authentication | Yes | N/A (Anthropic account) | N/A (app) | No | N/A (cloud) |\n| Free / OSS | Yes | Requires Pro/Max | Free + Paid | Yes | $20/mo |\n| Runs 100% Locally | Yes | Via Anthropic API | Server-routed | Yes | Cloud fallback |\n\n\u003c/details\u003e\n\n---\n\n## Optional Workflow Layer\n\n\u003ca id=\"issue-driven-development\"\u003e\u003c/a\u003e\n\nIf your team wants more structure, CommandMate can also help you standardize\nissue refinement, design review, planning, implementation, and acceptance checks.\nThese workflows build on top of the same CLI sessions and worktrees. They are optional, not required.\n\nCommandMate 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.\n\n```\nDefine Issue → Refine with AI → Review Direction → Generate Plan → Agent Executes\n```\n\n| Step | Command | What happens |\n|------|---------|-------------|\n| Refine the issue | `/issue-enhance` | AI asks clarifying questions and fills in missing details |\n| Review the issue | `/multi-stage-issue-review` | Multi-stage review (consistency, impact scope) with automated fixes |\n| Review the design | `/multi-stage-design-review` | 4-stage review (general → consistency → impact → security) |\n| Plan the work | `/work-plan` | Generates a task breakdown with dependencies |\n| Implement via TDD | `/tdd-impl` | Red-Green-Refactor cycle, automated |\n| Verify acceptance | `/acceptance-test` | Validates all acceptance criteria from the issue |\n| Create the PR | `/create-pr` | Auto-generates title, description, and labels |\n| Dev (full) | `/pm-auto-dev` | TDD implementation → acceptance test → refactoring → progress report |\n| Issue → Dev (full) | `/pm-auto-issue2dev` | Issue review → design review → work plan → TDD → acceptance test → refactoring → progress report |\n| Design → Dev (full) | `/pm-auto-design2dev` | Design review → work plan → TDD → acceptance test → refactoring → progress report |\n\nFor 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.\n\n---\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [CLI Setup Guide](./docs/en/user-guide/cli-setup-guide.md) | Installation and initial setup |\n| [Web App Guide](./docs/en/user-guide/webapp-guide.md) | Basic web app operations |\n| [Quick Start](./docs/en/user-guide/quick-start.md) | Using Claude Code commands |\n| [Concept](./docs/en/concept.md) | Vision and problems solved |\n| [Architecture](./docs/en/architecture.md) | System design |\n| [Deployment Guide](./docs/en/DEPLOYMENT.md) | Production environment setup |\n| [UI/UX Guide](./docs/en/UI_UX_GUIDE.md) | UI implementation details |\n| [Trust \u0026 Safety](./docs/en/TRUST_AND_SAFETY.md) | Security and permissions |\n\n## Contributing\n\nBug reports, feature suggestions, and documentation improvements are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.\n\n## License\n\n[MIT License](./LICENSE) - Copyright (c) 2026 Kewton\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkewton%2Fcommandmate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkewton%2Fcommandmate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkewton%2Fcommandmate/lists"}