commandmate 0.2.9 → 0.2.10

package/README.md

@@ -1,26 +1,156 @@
 # 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)
 
-> "Never miss a prompt — your development companion."
-> "Lightweight. Self-contained. Run Claude Code from anywhere."
+<!-- TODO: Add a 30-second demo GIF here to boost adoption -->
+<!-- Example: ![CommandMate Demo](./docs/assets/demo.gif) -->
+
+> **Your AI coding companion — never miss a prompt, work from anywhere.**
+
+- **Detect prompt/confirmation state** in real-time
+- **Send instructions from mobile or desktop** — no need to sit at your PC
+- **Manage sessions per Git worktree** — run parallel tasks with ease
+
+```bash
+npm install -g commandmate
+```
 
 ![Desktop view](./docs/images/screenshot-desktop.png)
 
+## Table of Contents
+
+- [What is this?](#what-is-this)
+- [Who is this for?](#who-is-this-for)
+- [What makes it unique?](#what-makes-it-unique)
+- [Quick Start](#quick-start-3-steps)
+- [Troubleshooting](#troubleshooting)
+- [How it works](#how-it-works)
+- [Key Features](#key-features)
+- [Use Cases](#use-cases)
+- [Security](#security)
+- [CLI Commands](#cli-commands)
+- [Developer Setup](#developer-setup)
+- [FAQ](#faq)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+
+---
+
 ## What is this?
 
 A development companion tool that manages Claude Code sessions per Git worktree and lets you send instructions from your browser.
 
 During your commute, childcare breaks, or lunch — send the next instruction as easily as replying to an email, and keep your side projects moving forward.
 
-## What it is NOT
+## Who is this for?
+
+**Great fit:**
+- Developers juggling childcare, commutes, or meetings — can't sit at the PC all day
+- Users who miss Claude Code's input prompts and lose flow
+- Teams using Git worktree for parallel development but finding tmux management tedious
+
+**Not ideal for:**
+- GUI IDE-only workflows (CommandMate is terminal/CLI-based)
+- Multi-user SaaS expectations (CommandMate is designed for local, individual use)
+
+## What makes it unique?
+
+CommandMate is not a terminal replacement. It **complements** Claude Code by focusing on three things:
+
+- **Prompt detection** — know instantly when Claude Code needs your input
+- **Response UI** — reply from any browser, including your phone
+- **Worktree organization** — manage multiple sessions in one place
+
+Supports **Claude Code**, **Codex CLI**, and **Gemini CLI**. Built with the Strategy pattern for extensibility — adding new CLI tools is straightforward.
+
+---
+
+## Quick Start (3 Steps)
+
+**Prerequisites:** macOS / Linux, Node.js v20+, npm, git, tmux, openssl
+
+> Windows is not supported due to the tmux dependency. WSL2 has not been tested.
+
+```bash
+# 1. Install
+npm install -g commandmate
+
+# 2. Initialize (dependency check, environment setup, DB init)
+commandmate init
+
+# 3. Start
+commandmate start --daemon
+```
+
+Open http://localhost:3000 in your browser.
+
+**Useful commands:**
+
+```bash
+commandmate status    # Check server status
+commandmate stop      # Stop the server
+```
+
+See the [CLI Setup Guide](./docs/en/user-guide/cli-setup-guide.md) for details.
+
+---
+
+## Troubleshooting
+
+**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"
 
-- It is not a terminal replacement. It **complements** Claude Code
-- It does not replicate all CLI features — it specializes in "never missing a prompt/confirmation and responding immediately"
+# 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`
 
-## Target Users
+---
 
-Developers with Claude Code experience who want to continue personal projects alongside their day job.
+## How it works
+
+CommandMate treats Claude Code (CLI) as a managed "execution session", making its state (running / waiting for input / idle) visible through a web UI.
+
+```mermaid
+flowchart LR
+    A["Browser / Phone"] -->|HTTP| B["CommandMate Server"]
+    B --> C["Session Manager"]
+    C -->|"spawn / attach"| D["tmux sessions<br/>(per worktree)"]
+    D --> E["Claude Code CLI"]
+    C <-->|"read / write"| F[("Local DB<br/>& State")]
+```
+
+Each Git worktree gets its own tmux session, so you can run multiple tasks in parallel without interference.
+
+---
 
 ## Key Features
 
@@ -31,11 +161,14 @@ Developers with Claude Code experience who want to continue personal projects al
 - **File viewer** — Browse worktree files from the browser with file operations (move, copy, delete)
 - **File timestamps** — Display file creation time in the file tree
 - **Auto Yes mode** — Control automatic approval with a confirmation dialog
-- **Repository removal** — Remove repositories from app management (actual files are not deleted)
+- **Repository management** — Remove repositories from app management (actual files are not deleted)
 - **Clone URL registration** — Clone and register repositories by specifying HTTPS/SSH URLs
-- **Claude Code optimized** — Optimized for Claude Code session management
+- **Multi-CLI support** — Optimized for Claude Code, with Codex CLI and Gemini CLI support
 - **Responsive UI** — Two-column layout on desktop, tab-based layout on mobile
 
+<details>
+<summary>Screenshots</summary>
+
 ### Worktree Detail View (Message / Console / History)
 
 | Desktop | Mobile (History) | Mobile (Terminal) |
@@ -46,45 +179,106 @@ Developers with Claude Code experience who want to continue personal projects al
 
 ![Mobile view](./docs/images/screenshot-mobile.png)
 
-## Quick Start
+</details>
 
-### Prerequisites
+---
 
-- macOS / Linux (Windows not supported due to tmux dependency)
-- Node.js v20+, npm, git, tmux, openssl
-- Claude CLI (optional)
+## Use Cases
 
-### Installation
+### 1. Commute — pick up where you left off
 
-```bash
-npm install -g commandmate
-```
+- **Morning:** Kick off a task with Claude Code before leaving
+- **Commute:** Check status on your phone, send the next instruction
+- **Evening:** Review the results and merge when you get home
 
-### Setup and Launch
+### 2. Childcare — 5-minute windows add up
 
-```bash
-commandmate init              # Dependency check, environment setup, DB initialization
-commandmate start --daemon    # Start in background
-```
+- Split tasks across worktrees so each runs independently
+- Check which sessions are waiting via CommandMate
+- In a 5-minute break, send the next instruction and keep things moving
 
-Open http://localhost:3000 in your browser.
+### 3. Parallel development — one UI for all your worktrees
+
+- No need to juggle tmux panes manually
+- See status of all worktrees at a glance in the sidebar
+- Focus on decisions, not terminal management
+
+---
+
+## Security
+
+CommandMate runs **entirely locally** — the app, database, and sessions all stay on your machine. The only external communication is Claude CLI's own API calls.
+
+**Recommended setup:**
+- Use on `localhost` or within the same LAN
+- For remote access, use a VPN or authenticated reverse proxy (Basic Auth, OIDC, etc.)
+- Enabling external access via `commandmate init` sets `CM_BIND=0.0.0.0` — access from the same LAN at `http://<your-PC-IP>:3000`
+
+**Do NOT:**
+- Expose to the internet without authentication (never bind `0.0.0.0` without a reverse proxy)
+
+See the [Security Guide](./docs/security-guide.md) and [Trust & Safety](./docs/en/TRUST_AND_SAFETY.md) for details.
 
-### CLI Commands
+---
+
+## CLI Commands
+
+### 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 |
 
-See the [CLI Setup Guide](./docs/en/user-guide/cli-setup-guide.md) for details.
+### Worktree Parallel Development
 
-### Mobile Access
+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 |
 
-Enabling external access via `commandmate init` sets `CM_BIND=0.0.0.0`. Access from the same LAN at `http://<your PC's IP>:3000`. For external access, we recommend authentication via a reverse proxy. See the [Security Guide](./docs/en/security-guide.md) for details.
+### 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.
+
+---
 
 ## Developer Setup
 
@@ -96,7 +290,8 @@ cd CommandMate
 ./scripts/setup.sh  # Auto-runs dependency check, env setup, build, and launch
 ```
 
-### Manual Setup (for customization)
+<details>
+<summary>Manual Setup (for customization)</summary>
 
 ```bash
 git clone https://github.com/Kewton/CommandMate.git
@@ -113,31 +308,22 @@ npm start
 
 > **Note**: Legacy environment variable names (`MCBD_*`) are still supported for backward compatibility, but using the new names (`CM_*`) is recommended.
 
-## FAQ
-
-**Q: Does everything run locally?**
-A: The app, database, and sessions all run entirely locally. The only external communication is the Claude CLI's own API calls.
+</details>
 
-**Q: How do I access it from my phone outside the house?**
-A: You can use tunneling services like Cloudflare Tunnel. Within your home, simply connect your phone to the same Wi-Fi as your PC.
+---
 
-**Q: What about Claude Code's permissions?**
-A: Claude Code's own permission settings apply as-is. This tool does not expand permissions. See [Trust & Safety](./docs/en/TRUST_AND_SAFETY.md) for details.
+## FAQ
 
-**Q: Does it work on Windows?**
-A: Not currently supported. macOS / Linux is required due to the tmux dependency. WSL2 has not been tested.
+**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. If something goes wrong, you can inspect sessions via tmux commands (see [Troubleshooting](#troubleshooting)).
 
-**Q: Does it support CLI tools other than Claude Code?**
-A: It supports Claude Code and Codex CLI. Thanks to the extensible Strategy pattern design, additional tools can be added in the future.
+**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.
 
-**Q: Session start fails after updating Claude CLI. What should I do?**
-A: If you switch between npm and standalone versions of Claude CLI, the path may change. CommandMate will automatically detect the new path on the next session start attempt. If you want to specify a custom path, set the `CLAUDE_PATH` environment variable in `.env` (e.g., `CLAUDE_PATH=/opt/homebrew/bin/claude`).
-
-**Q: Sessions fail to start when launching CommandMate from within Claude Code. Why?**
-A: Claude Code sets the `CLAUDECODE=1` environment variable to prevent nested sessions. CommandMate automatically removes this variable from tmux sessions, so sessions should start normally. If the issue persists, manually run `tmux set-environment -g -u CLAUDECODE` to clear it from tmux's global environment.
+---
 
 ## Documentation
 

package/dist/server/src/lib/auto-yes-manager.js

@@ -25,7 +25,7 @@ exports.stopAllAutoYesPolling = stopAllAutoYesPolling;
 const cli_session_1 = require("./cli-session");
 const prompt_detector_1 = require("./prompt-detector");
 const auto_yes_resolver_1 = require("./auto-yes-resolver");
-const tmux_1 = require("./tmux");
+const prompt_answer_sender_1 = require("./prompt-answer-sender");
 const manager_1 = require("./cli-tools/manager");
 const cli_patterns_1 = require("./cli-patterns");
 const auto_yes_config_1 = require("../config/auto-yes-config");
@@ -261,64 +261,15 @@ async function pollAutoYes(worktreeId, cliToolId) {
         const manager = manager_1.CLIToolManager.getInstance();
         const cliTool = manager.getTool(cliToolId);
         const sessionName = cliTool.getSessionName(worktreeId);
-        // Issue #193: Claude Code AskUserQuestion uses cursor-based navigation
-        // (Arrow/Space/Enter), not number input. Detect multi-choice and send
-        // appropriate key sequence instead of typing the number.
-        const isClaudeMultiChoice = cliToolId === 'claude'
-            && promptDetection.promptData?.type === 'multiple_choice'
-            && /^\d+$/.test(answer);
-        if (isClaudeMultiChoice && promptDetection.promptData?.type === 'multiple_choice') {
-            const targetNum = parseInt(answer, 10);
-            const mcOptions = promptDetection.promptData.options;
-            const defaultOption = mcOptions.find(o => o.isDefault);
-            const defaultNum = defaultOption?.number ?? 1;
-            const offset = targetNum - defaultNum;
-            // Detect multi-select (checkbox) prompts by checking for [ ] in option labels.
-            const isMultiSelect = mcOptions.some(o => /^\[[ x]\] /.test(o.label));
-            if (isMultiSelect) {
-                // Multi-select: toggle checkbox, then navigate to "Next" and submit
-                const checkboxCount = mcOptions.filter(o => /^\[[ x]\] /.test(o.label)).length;
-                const keys = [];
-                // 1. Navigate to target option
-                if (offset > 0) {
-                    for (let i = 0; i < offset; i++)
-                        keys.push('Down');
-                }
-                else if (offset < 0) {
-                    for (let i = 0; i < Math.abs(offset); i++)
-                        keys.push('Up');
-                }
-                // 2. Space to toggle checkbox
-                keys.push('Space');
-                // 3. Navigate to "Next" button (positioned right after all checkbox options)
-                const downToNext = checkboxCount - targetNum + 1;
-                for (let i = 0; i < downToNext; i++)
-                    keys.push('Down');
-                // 4. Enter to submit
-                keys.push('Enter');
-                await (0, tmux_1.sendSpecialKeys)(sessionName, keys);
-            }
-            else {
-                // Single-select: navigate and Enter to select
-                const keys = [];
-                if (offset > 0) {
-                    for (let i = 0; i < offset; i++)
-                        keys.push('Down');
-                }
-                else if (offset < 0) {
-                    for (let i = 0; i < Math.abs(offset); i++)
-                        keys.push('Up');
-                }
-                keys.push('Enter');
-                await (0, tmux_1.sendSpecialKeys)(sessionName, keys);
-            }
-        }
-        else {
-            // Standard CLI prompt: send text + Enter (y/n, Approve?, etc.)
-            await (0, tmux_1.sendKeys)(sessionName, answer, false);
-            await new Promise(resolve => setTimeout(resolve, 100));
-            await (0, tmux_1.sendKeys)(sessionName, '', true);
-        }
+        // Issue #287 Bug2: Uses shared sendPromptAnswer() to unify logic
+        // with route.ts, including cursor-key navigation for Claude Code
+        // multiple-choice prompts and fallback handling.
+        await (0, prompt_answer_sender_1.sendPromptAnswer)({
+            sessionName,
+            answer,
+            cliToolId,
+            promptData: promptDetection.promptData,
+        });
         // 6. Update timestamp
         updateLastServerResponseTimestamp(worktreeId, Date.now());
         // 7. Reset error count on success

package/dist/server/src/lib/prompt-answer-sender.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Shared prompt answer sender for cursor-key and text-based tmux input.
+ *
+ * Issue #287 Bug2: Extracted from route.ts and auto-yes-manager.ts to
+ * eliminate code duplication and ensure consistent behavior (including
+ * the promptType/defaultOptionNumber fallback introduced in Bug1).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendPromptAnswer = sendPromptAnswer;
+const tmux_1 = require("./tmux");
+/** Regex pattern to detect checkbox-style multi-select options */
+const CHECKBOX_OPTION_PATTERN = /^\[[ x]\] /;
+/**
+ * Build navigation key array for cursor movement.
+ * @param offset - positive = Down, negative = Up
+ */
+function buildNavigationKeys(offset) {
+    if (offset === 0)
+        return [];
+    const direction = offset > 0 ? 'Down' : 'Up';
+    return Array.from({ length: Math.abs(offset) }, () => direction);
+}
+/**
+ * Send an answer to a tmux session, using cursor-key navigation for
+ * Claude Code multiple-choice prompts and text input for everything else.
+ *
+ * This function unifies the logic previously duplicated in:
+ * - src/app/api/worktrees/[id]/prompt-response/route.ts (L114-187)
+ * - src/lib/auto-yes-manager.ts (L340-399)
+ */
+async function sendPromptAnswer(params) {
+    const { sessionName, answer, cliToolId, promptData, fallbackPromptType, fallbackDefaultOptionNumber } = params;
+    // Determine if this is a Claude Code multiple-choice prompt requiring cursor navigation
+    const isClaudeMultiChoice = cliToolId === 'claude'
+        && (promptData?.type === 'multiple_choice' || fallbackPromptType === 'multiple_choice')
+        && /^\d+$/.test(answer);
+    if (isClaudeMultiChoice) {
+        const targetNum = parseInt(answer, 10);
+        let defaultNum;
+        let mcOptions = null;
+        if (promptData?.type === 'multiple_choice') {
+            // Primary path: use fresh promptData
+            mcOptions = promptData.options;
+            const defaultOption = mcOptions.find(o => o.isDefault);
+            defaultNum = defaultOption?.number ?? 1;
+        }
+        else {
+            // Fallback path (Issue #287): promptData is undefined or type mismatch, use fallback fields
+            defaultNum = fallbackDefaultOptionNumber ?? 1;
+        }
+        const offset = targetNum - defaultNum;
+        // Detect multi-select (checkbox) prompts by checking for [ ] in option labels.
+        // Multi-select prompts require: Space to toggle checkbox -> navigate to "Next" -> Enter.
+        // Single-select prompts require: navigate to option -> Enter.
+        // Note: multi-select detection is only possible when promptData succeeded (mcOptions available).
+        const isMultiSelect = mcOptions !== null && mcOptions.some(o => CHECKBOX_OPTION_PATTERN.test(o.label));
+        if (isMultiSelect && mcOptions !== null) {
+            // Multi-select: toggle checkbox, then navigate to "Next" and submit
+            const checkboxCount = mcOptions.filter(o => CHECKBOX_OPTION_PATTERN.test(o.label)).length;
+            const keys = [
+                ...buildNavigationKeys(offset), // 1. Navigate to target option
+                'Space', // 2. Toggle checkbox
+            ];
+            // 3. Navigate to "Next" button (positioned right after all checkbox options)
+            const downToNext = checkboxCount - targetNum + 1;
+            keys.push(...buildNavigationKeys(downToNext));
+            // 4. Enter to submit
+            keys.push('Enter');
+            await (0, tmux_1.sendSpecialKeys)(sessionName, keys);
+        }
+        else {
+            // Single-select: navigate and Enter to select
+            const keys = [
+                ...buildNavigationKeys(offset),
+                'Enter',
+            ];
+            await (0, tmux_1.sendSpecialKeys)(sessionName, keys);
+        }
+    }
+    else {
+        // Standard CLI prompt: send text + Enter (y/n, Approve?, etc.)
+        await (0, tmux_1.sendKeys)(sessionName, answer, false);
+        // Wait a moment for the input to be processed
+        await new Promise(resolve => setTimeout(resolve, 100));
+        // Send Enter
+        await (0, tmux_1.sendKeys)(sessionName, '', true);
+    }
+}

package/dist/server/src/lib/prompt-detector.js

@@ -561,6 +561,15 @@ function detectMultipleChoicePrompt(output, options) {
             collectedOptions.unshift({ number, label, isDefault: false });
             continue;
         }
+        // [Issue #287 Bug3] User input prompt barrier:
+        // When no options have been collected yet and the line starts with ❯ (U+276F)
+        // but did NOT match DEFAULT_OPTION_PATTERN above, this line is a Claude Code
+        // user input prompt (e.g., "❯ 1", "❯ /command") or idle prompt ("❯").
+        // Anything above this line in the scrollback is historical conversation text,
+        // not an active prompt. Stop scanning to prevent false positives.
+        if (collectedOptions.length === 0 && line.startsWith('\u276F')) {
+            return noPromptResult(output);
+        }
         // Non-option line handling
         if (collectedOptions.length > 0 && line && !SEPARATOR_LINE_PATTERN.test(line)) {
             // [MF-001 / Issue #256] Check if line is a question-like line BEFORE

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commandmate",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "Git worktree management with Claude CLI and tmux sessions",
   "repository": {
     "type": "git",