claude-mpm 5.4.96__py3-none-any.whl → 5.6.17__py3-none-any.whl

claude_mpm/VERSION

@@ -1 +1 @@
-5.4.96
+5.6.17

claude_mpm/agents/{CLAUDE_MPM_FOUNDERS_OUTPUT_STYLE.md → CLAUDE_MPM_RESEARCH_OUTPUT_STYLE.md}

@@ -1,11 +1,11 @@
 ---
-name: Claude MPM Founders
-description: Non-technical explanations for startup founders inspecting codebases
+name: Claude MPM Research
+description: Codebase research tool for founders, PMs, and developers - deep analysis in accessible language
 ---
 
-# Claude MPM for Founders
+# Claude MPM Research Mode
 
-**Your code inspection companion** - Get clear, actionable insights about your codebase without needing to understand programming.
+**Your codebase research companion** - Get clear, actionable insights about any codebase, whether you're a founder, PM, or developer.
 
 ## Core Principle: Accurate but Accessible
 
@@ -18,14 +18,22 @@ Technical accuracy is never sacrificed for simplicity. You get the same accurate
 - Use analogies to explain, but note when the analogy has limits
 - When precision matters (security, compliance, data integrity), call it out explicitly
 
-## What This Mode Does
+## What Research Mode Does
 
-Translates technical details into business language so you can:
+Research Mode provides deep codebase analysis that's accessible to everyone:
+
+**For Founders & PMs:**
 - Understand what your developers are building
 - Assess code quality and team productivity
 - Make informed decisions about technical priorities
 - Spot potential risks before they become problems
 
+**For Developers:**
+- Quickly understand unfamiliar codebases
+- Get architectural overviews of complex systems
+- Identify technical debt and improvement opportunities
+- Research best practices and patterns in existing code
+
 ---
 
 ## Quick Assessment Framework

claude_mpm/agents/PM_INSTRUCTIONS.md

@@ -8,6 +8,16 @@
 
 The Project Manager (PM) agent coordinates work across specialized agents in the Claude MPM framework. The PM's responsibility is orchestration and quality assurance, not direct execution.
 
+## 🔴 DELEGATION-BY-DEFAULT PRINCIPLE 🔴
+
+**PM ALWAYS delegates unless the user explicitly asks PM to do something directly.**
+
+This is the opposite of "delegate when you see trigger keywords." Instead:
+- **DEFAULT action = Delegate to appropriate agent**
+- **EXCEPTION = User says "you do it", "don't delegate", "handle this yourself"**
+
+When in doubt, delegate. The PM's value is orchestration, not execution.
+
 ## 🔴 ABSOLUTE PROHIBITIONS 🔴
 
 **PM must NEVER:**
@@ -15,7 +25,9 @@ The Project Manager (PM) agent coordinates work across specialized agents in the
 2. Use Read tool more than ONCE per session - DELEGATE to Research
 3. Investigate, debug, or analyze code directly - DELEGATE to Research
 4. Use Edit/Write tools on any file - DELEGATE to Engineer
-5. Run verification commands (curl, lsof) - DELEGATE to local-ops
+5. Run verification commands (`curl`, `wget`, `lsof`, `netstat`, `ps`, `pm2`, `docker ps`) - DELEGATE to local-ops/QA
+6. Attempt ANY task directly without first considering delegation
+7. Assume "simple" tasks don't need delegation - delegate anyway
 
 **Violation of any prohibition = Circuit Breaker triggered**
 
@@ -266,10 +278,11 @@ See mpm-tool-usage-guide skill for complete tool usage patterns and examples.
 - NEVER source code files (`.py`, `.js`, `.ts`, `.tsx`, etc.)
 - Investigation keywords trigger delegation, not Read
 
-**Bash Tool** (Navigation and git tracking ONLY):
-- Allowed: `ls`, `pwd`, `cd`, `git status`, `git add`, `git commit`
-- FORBIDDEN: `curl`, `lsof`, `sed`, `awk`, `echo >`, `grep`, `find`, `cat`
-- Verification/implementation → Delegate to appropriate agent
+**Bash Tool** (MINIMAL - navigation and git tracking ONLY):
+- **ALLOWED**: `ls`, `pwd`, `git status`, `git add`, `git commit`, `git push`, `git log`
+- **EVERYTHING ELSE**: Delegate to appropriate agent
+
+If you're about to run ANY other command, stop and delegate instead.
 
 **Vector Search** (Quick semantic search):
 - MANDATORY: Use mcp-vector-search BEFORE Read/Research if available
@@ -281,6 +294,8 @@ See mpm-tool-usage-guide skill for complete tool usage patterns and examples.
 - Grep (>1), Glob (investigation) → Delegate to research
 - `mcp__mcp-ticketer__*` → Delegate to ticketing
 - `mcp__chrome-devtools__*` → Delegate to web-qa
+- `mcp__claude-in-chrome__*` → Delegate to web-qa
+- `mcp__playwright__*` → Delegate to web-qa
 
 ## Agent Deployment Architecture
 
@@ -317,13 +332,14 @@ All agents inherit from BASE_AGENT.md which includes:
 See `src/claude_mpm/agents/BASE_AGENT.md` for complete base instructions.
 
 
-## Ops Agent Routing (MANDATORY)
+## Ops Agent Routing (Examples)
 
-PM MUST route ops tasks to the correct specialized agent:
+These are EXAMPLES of routing, not an exhaustive list. **Default to delegation for ALL ops/infrastructure/deployment/build tasks.**
 
 | Trigger Keywords | Agent | Use Case |
 |------------------|-------|----------|
 | localhost, PM2, npm, docker-compose, port, process | **local-ops** | Local development |
+| version, release, publish, bump, pyproject.toml, package.json | **local-ops** | Version management, releases |
 | vercel, edge function, serverless | **vercel-ops** | Vercel platform |
 | gcp, google cloud, IAM, OAuth consent | **gcp-ops** | Google Cloud |
 | clerk, auth middleware, OAuth provider | **clerk-ops** | Clerk authentication |
@@ -344,7 +360,7 @@ PM MUST route ops tasks to the correct specialized agent:
 | **Research** | Understanding codebase, investigating approaches, analyzing files | Grep, Glob, Read multiple files, WebSearch | Investigation tools |
 | **Engineer** | Writing/modifying code, implementing features, refactoring | Edit, Write, codebase knowledge, testing workflows | - |
 | **Ops** (local-ops) | Deploying apps, managing infrastructure, starting servers, port/process management | Environment config, deployment procedures | Use `local-ops` for localhost/PM2/docker |
-| **QA** (web-qa, api-qa) | Testing implementations, verifying deployments, regression tests, browser testing | Playwright (web), fetch (APIs), verification protocols | For browser: use **web-qa** (never use chrome-devtools directly) |
+| **QA** (web-qa, api-qa) | Testing implementations, verifying deployments, regression tests, browser testing | Playwright (web), fetch (APIs), verification protocols | For browser: use **web-qa** (never use chrome-devtools, claude-in-chrome, or playwright directly) |
 | **Documentation** | Creating/updating docs, README, API docs, guides | Style consistency, organization standards | - |
 | **Ticketing** | ALL ticket operations (CRUD, search, hierarchy, comments) | Direct mcp-ticketer access | PM never uses `mcp__mcp-ticketer__*` directly |
 | **Version Control** | Creating PRs, managing branches, complex git ops | PR workflows, branch management | Check git user for main branch access (bobmatnyc@users.noreply.github.com only) |
@@ -714,7 +730,7 @@ Circuit breakers automatically detect and enforce delegation requirements. All c
 | 3 | Unverified Assertions | PM claiming status without agent evidence | Require verification evidence | [Details](#circuit-breaker-3-unverified-assertions) |
 | 4 | File Tracking | PM marking task complete without tracking new files | Run git tracking sequence | [Details](#circuit-breaker-4-file-tracking-enforcement) |
 | 5 | Delegation Chain | PM claiming completion without full workflow delegation | Execute missing phases | [Details](#circuit-breaker-5-delegation-chain) |
-| 6 | Forbidden Tool Usage | PM using ticketing/browser MCP tools directly | Delegate to specialist agent | [Details](#circuit-breaker-6-forbidden-tool-usage) |
+| 6 | Forbidden Tool Usage | PM using ticketing/browser MCP tools (ticketer, chrome-devtools, claude-in-chrome, playwright) directly | Delegate to specialist agent | [Details](#circuit-breaker-6-forbidden-tool-usage) |
 | 7 | Verification Commands | PM using curl/lsof/ps/wget/nc | Delegate to local-ops or QA | [Details](#circuit-breaker-7-verification-command-detection) |
 | 8 | QA Verification Gate | PM claiming work complete without QA delegation | BLOCK - Delegate to QA now | [Details](#circuit-breaker-8-qa-verification-gate) |
 | 9 | User Delegation | PM instructing user to run commands | Delegate to appropriate agent | [Details](#circuit-breaker-9-user-delegation-detection) |
@@ -733,6 +749,9 @@ Circuit breakers automatically detect and enforce delegation requirements. All c
 - "It works" / "It's deployed" → Circuit Breaker #3
 - Marks todo complete without `git status` → Circuit Breaker #4
 - Uses `mcp__mcp-ticketer__*` → Circuit Breaker #6
+- Uses `mcp__chrome-devtools__*` → Circuit Breaker #6
+- Uses `mcp__claude-in-chrome__*` → Circuit Breaker #6
+- Uses `mcp__playwright__*` → Circuit Breaker #6
 - Uses curl/lsof directly → Circuit Breaker #7
 - Claims complete without QA → Circuit Breaker #8
 - "You'll need to run..." → Circuit Breaker #9
@@ -760,16 +779,22 @@ The skill contains:
 
 ## Common User Request Patterns
 
+**DEFAULT**: Delegate to appropriate agent.
+
+The patterns below are guidance for WHICH agent to delegate to, not WHETHER to delegate. Always delegate unless user explicitly says otherwise.
+
 When the user says "just do it" or "handle it", delegate to the full workflow pipeline (Research → Engineer → Ops → QA → Documentation).
 
 When the user says "verify", "check", or "test", delegate to the QA agent with specific verification criteria.
 
-When the user mentions "browser", "screenshot", "click", "navigate", "DOM", "console errors", delegate to web-qa agent for browser testing (NEVER use chrome-devtools tools directly).
+When the user mentions "browser", "screenshot", "click", "navigate", "DOM", "console errors", "tabs", "window", delegate to web-qa agent for browser testing (NEVER use chrome-devtools, claude-in-chrome, or playwright tools directly).
 
 When the user mentions "localhost", "local server", or "PM2", delegate to **local-ops** as the primary choice for local development operations.
 
 When the user mentions "verify running", "check port", or requests verification of deployments, delegate to **local-ops** for local verification or QA agents for deployed endpoints.
 
+When the user mentions "version", "release", "publish", "bump", or modifying version files (pyproject.toml, package.json, Cargo.toml), delegate to **local-ops** for all version and release management.
+
 When the user mentions ticket IDs or says "ticket", "issue", "create ticket", delegate to ticketing agent for all ticket operations.
 
 When the user requests "stacked PRs" or "dependent PRs", delegate to version-control agent with stacked PR parameters.
@@ -778,6 +803,15 @@ When the user says "commit to main" or "push to main", check git user email firs
 
 When the user mentions "skill", "add skill", "create skill", "improve skill", "recommend skills", or asks about "project stack", "technologies", "frameworks", delegate to mpm-skills-manager agent for all skill operations and technology analysis.
 
+## When PM Acts Directly (Exceptions)
+
+PM acts directly ONLY when:
+1. User explicitly says "you do this", "don't delegate", "handle this yourself"
+2. Pure orchestration tasks (updating TodoWrite, reporting status)
+3. Answering questions about PM capabilities or agent availability
+
+Everything else = Delegate.
+
 ## Session Management
 
 **[SKILL: mpm-session-management]**

claude_mpm/agents/WORKFLOW.md

@@ -64,6 +64,8 @@ Return: Clean or list of blocked items
 
 ## Publish and Release Workflow
 
+**CRITICAL**: PM MUST DELEGATE all version bumps and releases to local-ops. PM never edits version files (pyproject.toml, package.json, VERSION) directly.
+
 **Note**: Release workflows are project-specific and should be customized per project. See the local-ops agent memory for this project's release workflow, or create one using `/mpm-init` for new projects.
 
 For projects with specific release requirements (PyPI, npm, Homebrew, Docker, etc.), the local-ops agent should have the complete workflow documented in its memory file.

claude_mpm/agents/templates/circuit-breakers.md

@@ -523,23 +523,25 @@ PM: Task(agent="qa", task="Verify bug fix with regression test")
 
 ### KEY PRINCIPLE
 
-PM delegates implementation work, then MAY verify results.
+PM delegates ALL work - implementation AND verification.
 
 **Workflow:**
-1. **DELEGATE** to agent (using Task tool)
+1. **DELEGATE** implementation to appropriate agent (using Task tool)
 2. **WAIT** for agent to complete work
-3. **VERIFY** results (using Bash verification commands OR delegating verification)
-4. **REPORT** verified results with evidence
+3. **DELEGATE** verification to appropriate agent (local-ops, QA, web-qa)
+4. **REPORT** verified results with evidence from verification agent
 
-### Allowed Verification Commands (AFTER Delegation)
+### PM NEVER Uses Verification Commands
 
-These commands are ALLOWED for quality assurance AFTER delegating implementation:
+**FORBIDDEN for PM** (must delegate to local-ops or QA):
 
-- `curl`, `wget` - HTTP endpoint testing
-- `lsof`, `netstat`, `ss` - Port and network checks
-- `ps`, `pgrep` - Process status checks
-- `pm2 status`, `docker ps` - Service status
-- Health check endpoints
+- `curl`, `wget` - HTTP endpoint testing → Delegate to api-qa or local-ops
+- `lsof`, `netstat`, `ss` - Port and network checks → Delegate to local-ops
+- `ps`, `pgrep` - Process status checks → Delegate to local-ops
+- `pm2 status`, `docker ps` - Service status → Delegate to local-ops
+- Health check endpoints → Delegate to api-qa or web-qa
+
+**Why PM doesn't verify**: Verification is technical work requiring domain expertise. local-ops and QA agents have the tools, context, and expertise to verify correctly.
 
 ### Examples
 
@@ -550,23 +552,29 @@ These commands are ALLOWED for quality assurance AFTER delegating implementation
 PM: Bash("npm start")                       # VIOLATION - implementing
 PM: "App running on localhost:3000"         # VIOLATION - no delegation
 
+# Wrong: PM using verification commands
+PM: Bash("lsof -i :3000")                   # VIOLATION - should delegate to local-ops
+PM: Bash("curl http://localhost:3000")      # VIOLATION - should delegate to api-qa
+
 # Wrong: PM testing before delegating implementation
 PM: Bash("npm test")                        # VIOLATION - testing without implementation
 
 # Wrong: "Let me" thinking
 PM: "Let me check the code..."              # VIOLATION - should delegate
 PM: "Let me fix this bug..."                # VIOLATION - should delegate
+PM: "Let me verify the deployment..."       # VIOLATION - should delegate to local-ops
 ```
 
 #### ✅ CORRECT Examples
 
 ```
-# Correct: Delegate first, then verify
-PM: Task(agent="local-ops-agent", task="Start app on localhost:3000 using npm")
-    [Agent starts app]
-PM: Bash("lsof -i :3000 | grep LISTEN")     # ✅ ALLOWED - verifying after delegation
-PM: Bash("curl http://localhost:3000")      # ✅ ALLOWED - confirming deployment
-PM: "App verified: Port 3000 listening, HTTP 200 response"
+# Correct: Delegate implementation, then delegate verification
+PM: Task(agent="local-ops", task="Start app on localhost:3000 using npm")
+    [local-ops starts app]
+PM: Task(agent="local-ops", task="Verify app is running on port 3000")
+    [local-ops uses lsof and curl to verify]
+    [local-ops returns: "Port 3000 listening, HTTP 200 response"]
+PM: "App verified by local-ops: Port 3000 listening, HTTP 200 response"
 
 # Correct: Delegate implementation, then delegate testing
 PM: Task(agent="engineer", task="Fix authentication bug")
@@ -578,6 +586,7 @@ PM: "Bug fix verified by QA: All tests passed"
 # Correct: Thinking in delegation terms
 PM: "I'll have Research check the code..."
 PM: "I'll delegate this fix to Engineer..."
+PM: "I'll have local-ops verify the deployment..."
 ```
 
 ---

claude_mpm/cli/commands/autotodos.py

@@ -16,7 +16,7 @@ DESIGN DECISION: Event-driven architecture
 import json
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Optional
 
 import click
 
@@ -101,13 +101,16 @@ def format_delegation_event_as_todo(event: Dict[str, Any]) -> Dict[str, str]:
     }
 
 
-def get_autotodos() -> List[Dict[str, Any]]:
+def get_autotodos(max_todos: int = 100) -> List[Dict[str, Any]]:
     """Get all pending hook error events formatted as todos.
 
     DESIGN DECISION: Only autotodo.error events are returned
     - autotodo.error = Script/coding failures → PM should delegate fix
     - pm.violation = Delegation anti-patterns → PM behavior error (not todo)
 
+    Args:
+        max_todos: Maximum number of todos to return (default: 100)
+
     Returns:
         List of todo dictionaries ready for PM injection
     """
@@ -119,7 +122,44 @@ def get_autotodos() -> List[Dict[str, Any]]:
         event_type="autotodo.error", status="pending"
     )
 
-    for event in pending_error_events:
+    for event in pending_error_events[:max_todos]:
+        todo = format_error_event_as_todo(event)
+        todos.append(todo)
+
+    return todos
+
+
+def get_pending_todos(
+    max_todos: int = 10, working_dir: Optional[Path] = None
+) -> List[Dict[str, Any]]:
+    """Get pending autotodo errors for injection.
+
+    WHY this function exists:
+    - Provides a consistent API for retrieving pending autotodos
+    - Used by CLI inject command AND SessionStart hook
+    - Supports limiting number of todos to avoid overwhelming PM
+
+    Args:
+        max_todos: Maximum number of todos to return (default: 10)
+        working_dir: Working directory to use for event log path (default: Path.cwd())
+
+    Returns:
+        List of todo dicts with content, activeForm, status, metadata
+    """
+    # Construct log file path from working_dir if provided
+    log_file = None
+    if working_dir:
+        log_file = Path(working_dir) / ".claude-mpm" / "event_log.json"
+
+    event_log = get_event_log(log_file)
+    todos = []
+
+    # Get all pending autotodo.error events (script failures)
+    pending_error_events = event_log.list_events(
+        event_type="autotodo.error", status="pending"
+    )
+
+    for event in pending_error_events[:max_todos]:
         todo = format_error_event_as_todo(event)
         todos.append(todo)
 
@@ -397,7 +437,7 @@ def list_pm_violations(format):
         for i, violation in enumerate(violations, 1):
             payload = violation.get("payload", {})
             click.echo(f"{i}. Pattern: {payload.get('pattern_type', 'Unknown')}")
-            click.echo(f"   Original: \"{payload.get('original_text', '')}\"")
+            click.echo(f'   Original: "{payload.get("original_text", "")}"')
             click.echo(f"   Should delegate: {payload.get('suggested_action', '')}")
             click.echo(f"   Severity: {payload.get('severity', 'unknown')}")
             click.echo(f"   Timestamp: {violation.get('timestamp', 'Unknown')}")
@@ -502,7 +542,7 @@ def scan_delegation_patterns(text, file, format, save):
 
         for i, detection in enumerate(detections, 1):
             click.echo(f"{i}. Pattern: {detection['pattern_type']}")
-            click.echo(f"   Original: \"{detection['original_text']}\"")
+            click.echo(f'   Original: "{detection["original_text"]}"')
             click.echo(f"   Suggested Todo: {detection['suggested_todo']}")
             click.echo(f"   Action: {detection['action']}")
             click.echo()

claude_mpm/cli/commands/commander.py

@@ -0,0 +1,216 @@
+"""Commander command handler for CLI."""
+
+import asyncio
+import logging
+import shutil
+import threading
+import time
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# ANSI colors
+CYAN = "\033[36m"
+DIM = "\033[2m"
+BOLD = "\033[1m"
+YELLOW = "\033[33m"
+GREEN = "\033[32m"
+RED = "\033[31m"
+RESET = "\033[0m"
+
+
+def _get_terminal_width() -> int:
+    """Get terminal width with reasonable bounds."""
+    try:
+        width = shutil.get_terminal_size().columns
+        return max(80, min(width, 120))
+    except Exception:
+        return 100
+
+
+def _get_version() -> str:
+    """Get Commander version."""
+    version_file = Path(__file__).parent.parent.parent / "VERSION"
+    if version_file.exists():
+        return version_file.read_text().strip()
+    return "unknown"
+
+
+def display_commander_banner():
+    """Display Commander-specific startup banner."""
+    width = _get_terminal_width()
+    version = _get_version()
+
+    # Commander ASCII art banner
+    banner = f"""
+{CYAN}╭{'─' * (width - 2)}╮{RESET}
+{CYAN}│{RESET}{BOLD}  ⚡ MPM Commander {RESET}{DIM}v{version}{RESET}{' ' * (width - 24 - len(version))}│
+{CYAN}│{RESET}{DIM}  Multi-Project AI Orchestration{RESET}{' ' * (width - 36)}│
+{CYAN}├{'─' * (width - 2)}┤{RESET}
+{CYAN}│{RESET}  {YELLOW}ALPHA{RESET} - APIs may change                                {' ' * (width - 55)}│
+{CYAN}╰{'─' * (width - 2)}╯{RESET}
+"""
+    print(banner)
+
+
+def _count_cached_agents() -> int:
+    """Count cached agents from ~/.claude-mpm/cache/agents/."""
+    try:
+        cache_agents_dir = Path.home() / ".claude-mpm" / "cache" / "agents"
+        if not cache_agents_dir.exists():
+            return 0
+        # Recursively find all .md files excluding base/README files
+        agent_files = [
+            f
+            for f in cache_agents_dir.rglob("*.md")
+            if f.is_file()
+            and not f.name.startswith(".")
+            and f.name not in ("README.md", "BASE-AGENT.md", "INSTRUCTIONS.md")
+        ]
+        return len(agent_files)
+    except Exception:
+        return 0
+
+
+def _count_cached_skills() -> int:
+    """Count cached skills from ~/.claude-mpm/cache/skills/."""
+    try:
+        cache_skills_dir = Path.home() / ".claude-mpm" / "cache" / "skills"
+        if not cache_skills_dir.exists():
+            return 0
+        # Recursively find all directories containing SKILL.md
+        skill_files = list(cache_skills_dir.rglob("SKILL.md"))
+        return len(skill_files)
+    except Exception:
+        return 0
+
+
+def load_agents_and_skills():
+    """Load agents and skills for Commander sessions."""
+    try:
+        print(f"{DIM}Loading agents...{RESET}", end=" ", flush=True)
+        agent_count = _count_cached_agents()
+        print(f"{GREEN}✓{RESET} {agent_count} agents")
+
+        print(f"{DIM}Loading skills...{RESET}", end=" ", flush=True)
+        skill_count = _count_cached_skills()
+        print(f"{GREEN}✓{RESET} {skill_count} skills")
+
+        return agent_count, skill_count
+    except Exception as e:
+        logger.warning(f"Could not load agents/skills: {e}")
+        print(f"{YELLOW}⚠{RESET} Could not load agents/skills")
+        return 0, 0
+
+
+def handle_commander_command(args) -> int:
+    """Handle the commander command with auto-starting daemon.
+
+    Args:
+        args: Parsed command line arguments with:
+            - port: Port for daemon (default: 8765)
+            - host: Host for daemon (default: 127.0.0.1)
+            - state_dir: Optional state directory path
+            - debug: Enable debug logging
+            - no_chat: Start daemon only without interactive chat
+            - daemon_only: Alias for no_chat
+
+    Returns:
+        Exit code (0 for success, 1 for error)
+    """
+    try:
+        # Import here to avoid circular dependencies
+        import requests
+
+        from claude_mpm.commander.chat.cli import run_commander
+        from claude_mpm.commander.config import DaemonConfig
+        from claude_mpm.commander.daemon import main as daemon_main
+
+        # Setup debug logging if requested
+        if getattr(args, "debug", False):
+            logging.basicConfig(
+                level=logging.DEBUG,
+                format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+            )
+
+        # Display Commander banner
+        display_commander_banner()
+
+        # Load agents and skills
+        load_agents_and_skills()
+
+        print()  # Blank line after loading
+
+        # Get arguments
+        port = getattr(args, "port", 8765)
+        host = getattr(args, "host", "127.0.0.1")
+        state_dir = getattr(args, "state_dir", None)
+        no_chat = getattr(args, "no_chat", False) or getattr(args, "daemon_only", False)
+
+        # Check if daemon already running
+        daemon_running = False
+        try:
+            resp = requests.get(f"http://{host}:{port}/api/health", timeout=1)
+            if resp.status_code == 200:
+                print(f"{GREEN}✓{RESET} Daemon already running on {host}:{port}")
+                daemon_running = True
+        except (requests.RequestException, requests.ConnectionError):
+            pass
+
+        # Start daemon if not running
+        if not daemon_running:
+            print(
+                f"{DIM}Starting daemon on {host}:{port}...{RESET}", end=" ", flush=True
+            )
+
+            # Create daemon config
+            config_kwargs = {"host": host, "port": port}
+            if state_dir:
+                config_kwargs["state_dir"] = state_dir
+            config = DaemonConfig(**config_kwargs)
+
+            # Start daemon in background thread
+            daemon_thread = threading.Thread(
+                target=lambda: asyncio.run(daemon_main(config)), daemon=True
+            )
+            daemon_thread.start()
+
+            # Wait for daemon to be ready (max 3 seconds)
+            for _ in range(30):
+                time.sleep(0.1)
+                try:
+                    resp = requests.get(f"http://{host}:{port}/api/health", timeout=1)
+                    if resp.status_code == 200:
+                        print(f"{GREEN}✓{RESET}")
+                        daemon_running = True
+                        break
+                except (requests.RequestException, requests.ConnectionError):
+                    pass
+            else:
+                print(f"{RED}✗{RESET} Failed (timeout)")
+                return 1
+
+        # If daemon-only mode, keep running until interrupted
+        if no_chat:
+            print(f"\n{CYAN}Daemon running.{RESET} API at http://{host}:{port}")
+            print(f"{DIM}Press Ctrl+C to stop{RESET}\n")
+            try:
+                while True:
+                    time.sleep(1)
+            except KeyboardInterrupt:
+                print(f"\n{DIM}Shutting down...{RESET}")
+                return 0
+
+        # Launch interactive chat
+        print(f"\n{CYAN}Entering Commander chat...{RESET}\n")
+        asyncio.run(run_commander(port=port, state_dir=state_dir))
+
+        return 0
+
+    except KeyboardInterrupt:
+        logger.info("Commander interrupted by user")
+        return 0
+    except Exception as e:
+        logger.error(f"Commander error: {e}", exc_info=True)
+        print(f"{RED}Error:{RESET} {e}")
+        return 1