gdmcode 0.1.0__py3-none-any.whl

src/cli.py

@@ -0,0 +1,1290 @@
+"""gdm CLI — all subcommands.
+
+Usage:
+  gdm                     # start coding agent (default)
+  gdm code                # start coding agent (explicit)
+  gdm login [provider]    # authenticate: grok | gemini | codex | all
+  gdm logout [provider]   # remove stored credentials
+  gdm version             # show version info
+  gdm doctor              # check environment and dependencies
+
+Flags accepted by `gdm code`:
+  --yes / -y              # bypass permission prompts this session
+  --provider TEXT         # force provider: grok | gemini | codex
+  --model TEXT            # override model tier: scout|coder|thinker|reasoner|debate
+  --max-turns INT         # override max_turns
+  --cost-limit FLOAT      # override session cost limit in USD
+  --prompt TEXT           # non-interactive: run one prompt and exit
+"""
+from __future__ import annotations
+
+import logging
+import sys
+import tomllib
+from pathlib import Path
+from typing import Annotated, Optional
+
+import shutil
+
+import httpx
+import typer
+from rich.console import Console
+
+from src.agent.daemon import BackgroundDaemon
+from src.config import load_config
+from src.memory.db import GdmDatabase
+from src.tools import REGISTRY
+
+__all__ = ["app"]
+
+app = typer.Typer(
+    name="gdm",
+    help="gdm code — the Grok-native AI coding agent.",
+    add_completion=False,
+    rich_markup_mode="rich",
+)
+
+console = Console()
+log = logging.getLogger(__name__)
+
+# ── Version string ────────────────────────────────────────────────────────
+
+_VERSION = "0.1.0-alpha"
+
+
+# ---------------------------------------------------------------------------
+# gdm version
+# ---------------------------------------------------------------------------
+
+@app.command("version")
+def cmd_version() -> None:
+    """Show version information."""
+    console.print(f"[bold cyan]gdm code[/bold cyan] v{_VERSION}")
+    console.print("The Grok-native AI coding agent.")
+    _print_provider_status()
+
+
+# ---------------------------------------------------------------------------
+# gdm login
+# ---------------------------------------------------------------------------
+
+@app.command("login")
+def cmd_login(
+    provider: Annotated[
+        str,
+        typer.Argument(help="Provider to log in to: grok | gemini | codex | all"),
+    ] = "all",
+) -> None:
+    """Authenticate with an AI provider and store credentials in the keychain."""
+    from src.auth import login_interactive
+    login_interactive(provider)
+
+
+# ---------------------------------------------------------------------------
+# gdm logout
+# ---------------------------------------------------------------------------
+
+@app.command("logout")
+def cmd_logout(
+    provider: Annotated[
+        str,
+        typer.Argument(help="Provider to log out from: grok | gemini | codex | all"),
+    ] = "all",
+) -> None:
+    """Remove stored credentials for a provider."""
+    from src.auth import logout
+    logout(provider)
+
+
+# ---------------------------------------------------------------------------
+# gdm doctor
+# ---------------------------------------------------------------------------
+
+@app.command("doctor")
+def cmd_doctor() -> None:
+    """Check environment, dependencies, and capability health."""
+    import importlib.util
+    import shutil
+
+    console.print("[bold]gdm doctor — environment check[/bold]\n")
+
+    def _check_pkg(name: str) -> bool:
+        return importlib.util.find_spec(name) is not None
+
+    def _check_bin(name: str) -> bool:
+        return shutil.which(name) is not None
+
+    def _print_group(title: str, checks: list[tuple[str, bool, str]]) -> None:
+        console.print(f"  [bold]{title}[/bold]")
+        for label, ok, hint in checks:
+            icon = "[green]✓[/green]" if ok else "[yellow]✗[/yellow]"
+            note = f"  [dim]— {hint}[/dim]" if (not ok and hint) else ""
+            console.print(f"    {icon}  {label}{note}")
+        console.print()
+
+    # --- Core ---
+    ver = sys.version_info
+    core: list[tuple[str, bool, str]] = [
+        (f"Python {ver.major}.{ver.minor}.{ver.micro}", ver >= (3, 11), "Python 3.11+ required"),
+    ]
+    for pkg in ("openai", "rich", "typer", "keyring", "httpx", "tiktoken"):
+        core.append((f"package: {pkg}", _check_pkg(pkg), f"pip install {pkg}"))
+    for pkg in ("markdownify", "tree_sitter"):
+        core.append((f"optional: {pkg}", _check_pkg(pkg), "install for best experience"))
+    core.append(("ripgrep (rg)", _check_bin("rg"), "install ripgrep for fast search"))
+    from src.auth import CredentialStore
+    creds = CredentialStore().load_all()
+    core.append(("XAI_API_KEY (Grok)", creds.has_grok, "run: gdm login grok"))
+    core.append(("GEMINI_API_KEY", creds.has_gemini, "run: gdm login gemini"))
+    core.append(("OPENAI_API_KEY (Codex)", creds.has_codex, "run: gdm login codex"))
+    _print_group("Core", core)
+
+    # --- Remote ---
+    remote_checks: list[tuple[str, bool, str]] = [
+        ("websockets", _check_pkg("websockets"), "pip install gdm-code[remote]"),
+    ]
+    _print_group("Remote access", remote_checks)
+
+    # --- Voice ---
+    has_sounddevice = _check_pkg("sounddevice")
+    has_webrtcvad = _check_pkg("webrtcvad")
+    has_numpy = _check_pkg("numpy")
+    portaudio_ok = False
+    if has_sounddevice:
+        try:
+            import sounddevice as _sd
+            _sd.query_devices()
+            portaudio_ok = True
+        except Exception:
+            portaudio_ok = False
+    voice_checks: list[tuple[str, bool, str]] = [
+        ("sounddevice", has_sounddevice, "pip install gdm-code[voice]"),
+        ("webrtcvad", has_webrtcvad, "pip install gdm-code[voice]"),
+        ("numpy", has_numpy, "pip install gdm-code[voice]"),
+        ("PortAudio (system)", portaudio_ok, "brew install portaudio  OR  apt install libportaudio2"),
+    ]
+    _print_group("Voice", voice_checks)
+
+    # --- Browser / Bridge ---
+    has_chrome = (
+        _check_bin("google-chrome")
+        or _check_bin("chromium")
+        or _check_bin("chromium-browser")
+        or _check_bin("chrome")
+    )
+    browser_checks: list[tuple[str, bool, str]] = [
+        ("cloudflared", _check_bin("cloudflared"), "brew install cloudflared  OR  download from cloudflare.com/products/tunnel"),
+        ("Chrome/Chromium", has_chrome, "install Google Chrome or Chromium"),
+    ]
+    _print_group("Browser / Bridge", browser_checks)
+
+    # --- Mobile ---
+    import platform as _platform
+    mobile_checks: list[tuple[str, bool, str]] = [
+        ("adb (Android Debug Bridge)", _check_bin("adb"), "install Android platform-tools"),
+    ]
+    if _platform.system() == "Darwin":
+        mobile_checks.append(("xcrun (iOS simulator)", _check_bin("xcrun"), "install Xcode Command Line Tools"))
+    _print_group("Mobile", mobile_checks)
+
+    # --- Summary ---
+    has_key = creds.any_key
+    if has_key:
+        console.print("[green]Ready to code![/green] Run: [bold]gdm code[/bold]")
+    else:
+        console.print("[yellow]No API key found.[/yellow] Run: [bold]gdm login[/bold]")
+
+
+
+# ---------------------------------------------------------------------------
+# gdm daemon
+# ---------------------------------------------------------------------------
+
+@app.command("daemon")
+def cmd_daemon(
+    action: Annotated[
+        str,
+        typer.Argument(help="Action: start | stop | status"),
+    ] = "status",
+) -> None:
+    """Manage the gdm background daemon (indexing, scanning, compression jobs)."""
+    try:
+        cfg = load_config()
+    except Exception as exc:  # noqa: BLE001
+        console.print(f"[red]Config error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+
+    db = GdmDatabase(project_root=cfg.project_root)
+
+    match action.lower():
+        case "start":
+            try:
+                daemon = BackgroundDaemon(db=db)
+                daemon.start()
+                console.print("[green]✓[/green] Background daemon started.")
+                console.print("[dim]Jobs: index • compress • security-scan[/dim]")
+            except Exception as exc:  # noqa: BLE001
+                console.print(f"[red]Failed to start daemon:[/red] {exc}")
+                raise typer.Exit(1) from exc
+
+        case "stop":
+            try:
+                daemon = BackgroundDaemon(db=db)
+                daemon.stop()
+                console.print("[yellow]Daemon stopped.[/yellow]")
+            except Exception as exc:  # noqa: BLE001
+                console.print(f"[red]Failed to stop daemon:[/red] {exc}")
+
+        case "status":
+            try:
+                daemon = BackgroundDaemon(db=db)
+                pending = daemon.pending_count()
+                running = daemon.is_running
+                state = "[green]running[/green]" if running else "[dim]stopped[/dim]"
+                console.print(f"Daemon: {state}  |  Pending jobs: [bold]{pending}[/bold]")
+            except Exception as exc:  # noqa: BLE001
+                console.print(f"[yellow]Daemon status unavailable:[/yellow] {exc}")
+
+        case _:
+            console.print(f"[red]Unknown action {action!r}.[/red] Use: start | stop | status")
+            raise typer.Exit(1)
+
+
+# ---------------------------------------------------------------------------
+# gdm health
+# ---------------------------------------------------------------------------
+
+@app.command("health")
+def cmd_health(
+    json_out: Annotated[bool, typer.Option("--json", help="Output JSON for CI pipelines")] = False,
+) -> None:
+    """Live system health check (DB, daemon, API, tools, budget, system deps)."""
+    import json as _json
+    import time
+    from concurrent.futures import ThreadPoolExecutor
+    from dataclasses import dataclass
+    from datetime import datetime, timezone
+
+    from src.agent.context_budget import ContextBudget
+    from src.models.definitions import PROVIDER_BASE_URLS, ModelTier, get_model
+
+    @dataclass
+    class CheckResult:
+        name: str
+        status: str      # "ok" | "warn" | "fail" | "missing"
+        latency_ms: int = 0
+        detail: str = ""
+        priority: str = "P0"  # P0=blocking, P1=warn, P2=info
+
+    try:
+        cfg = load_config()
+    except Exception as exc:  # noqa: BLE001
+        console.print(f"[red]Config error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+
+    db = GdmDatabase(project_root=cfg.project_root)
+
+    def _check_db() -> CheckResult:
+        t0 = time.monotonic()
+        try:
+            db.execute("SELECT 1")
+            return CheckResult("db", "ok", latency_ms=int((time.monotonic() - t0) * 1000))
+        except Exception as exc:  # noqa: BLE001
+            return CheckResult("db", "fail", detail=str(exc))
+
+    def _check_daemon() -> CheckResult:
+        t0 = time.monotonic()
+        try:
+            daemon = BackgroundDaemon(db=db)
+            pending = daemon.pending_count()
+            running = daemon.is_running
+            detail = f"{'running' if running else 'stopped'}, {pending} pending"
+            status = "ok" if running else "warn"
+            return CheckResult("daemon", status, latency_ms=int((time.monotonic() - t0) * 1000), detail=detail, priority="P1")
+        except Exception as exc:  # noqa: BLE001
+            return CheckResult("daemon", "warn", latency_ms=int((time.monotonic() - t0) * 1000), detail=str(exc), priority="P1")
+
+    def _check_api() -> CheckResult:
+        t0 = time.monotonic()
+        base_url = PROVIDER_BASE_URLS.get(cfg.provider, "").rstrip("/")
+        url = f"{base_url}/models"
+        try:
+            resp = httpx.get(
+                url,
+                headers={"Authorization": f"Bearer {cfg.api_key}"},
+                timeout=3.0,
+            )
+            latency = int((time.monotonic() - t0) * 1000)
+            if resp.status_code == 200:
+                return CheckResult(f"api ({cfg.provider})", "ok", latency_ms=latency)
+            if resp.status_code == 401:
+                return CheckResult(f"api ({cfg.provider})", "fail", latency_ms=latency, detail="API key invalid")
+            return CheckResult(f"api ({cfg.provider})", "fail", latency_ms=latency, detail=f"HTTP {resp.status_code}")
+        except httpx.TimeoutException:
+            return CheckResult(f"api ({cfg.provider})", "fail", detail="unreachable (timeout)")
+        except Exception as exc:  # noqa: BLE001
+            return CheckResult(f"api ({cfg.provider})", "fail", detail=str(exc)[:60])
+
+    def _check_tools() -> CheckResult:
+        t0 = time.monotonic()
+        try:
+            tools = REGISTRY.all_tools()
+            count = len(tools)
+            status = "ok" if count > 0 else "fail"
+            return CheckResult("tools", status, latency_ms=int((time.monotonic() - t0) * 1000), detail=f"{count} tools")
+        except Exception as exc:  # noqa: BLE001
+            return CheckResult("tools", "fail", detail=str(exc))
+
+    def _check_budget() -> CheckResult:
+        t0 = time.monotonic()
+        try:
+            model_def = get_model(ModelTier.CODER, cfg.provider)
+            budget = ContextBudget(model_context_window=model_def.context_window)
+            pct = round(budget.used_tokens / budget.max_tokens * 100, 1)
+            status = "warn" if pct > 70 else "ok"
+            return CheckResult("budget", status, latency_ms=int((time.monotonic() - t0) * 1000), detail=f"{pct}% used", priority="P1")
+        except Exception as exc:  # noqa: BLE001
+            return CheckResult("budget", "fail", detail=str(exc))
+
+    def _check_sysdeps() -> list[CheckResult]:
+        _priorities = {"git": "P0", "ruff": "P1", "difftastic": "P2"}
+        results = []
+        for cmd in ["git", "ruff", "difftastic"]:
+            t0 = time.monotonic()
+            path = shutil.which(cmd)
+            latency = int((time.monotonic() - t0) * 1000)
+            status = "ok" if path else "missing"
+            results.append(CheckResult(cmd, status, latency_ms=latency, detail=path or "missing", priority=_priorities[cmd]))
+        return results
+
+    # Run scalar checks in parallel; sysdeps is fast so fine in its own slot
+    with ThreadPoolExecutor(max_workers=6) as executor:
+        f_db     = executor.submit(_check_db)
+        f_daemon = executor.submit(_check_daemon)
+        f_api    = executor.submit(_check_api)
+        f_tools  = executor.submit(_check_tools)
+        f_budget = executor.submit(_check_budget)
+        f_sys    = executor.submit(_check_sysdeps)
+
+    all_checks: list[CheckResult] = [
+        f_db.result(),
+        f_daemon.result(),
+        f_api.result(),
+        f_tools.result(),
+        f_budget.result(),
+        *f_sys.result(),
+    ]
+
+    overall_fail = any(
+        r.status in ("fail", "missing") and r.priority in ("P0", "P1")
+        for r in all_checks
+    )
+
+    if json_out:
+        payload = {
+            "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+            "overall": "fail" if overall_fail else "pass",
+            "checks": [
+                {
+                    "name": r.name,
+                    "status": r.status,
+                    "latency_ms": r.latency_ms,
+                    "detail": r.detail,
+                    "priority": r.priority,
+                }
+                for r in all_checks
+            ],
+        }
+        print(_json.dumps(payload, indent=2))
+    else:
+        console.print("[bold]gdm health[/bold]\n")
+        for r in all_checks:
+            if r.status == "ok":
+                icon = "[green]✓[/green]"
+            elif r.status in ("warn", "missing") and r.priority == "P2":
+                icon = "[dim]○[/dim]"
+            elif r.status in ("warn", "missing"):
+                icon = "[yellow]⚠[/yellow]"
+            else:
+                icon = "[red]✗[/red]"
+            latency_str = f" [dim]{r.latency_ms}ms[/dim]" if r.latency_ms else ""
+            detail_str = f" [dim]— {r.detail}[/dim]" if r.detail else ""
+            console.print(f"  {icon}  {r.name:<22}{latency_str}{detail_str}")
+        console.print()
+        if overall_fail:
+            console.print("[yellow]Some checks failed.[/yellow] Run [bold]gdm doctor[/bold] for setup help.")
+        else:
+            console.print("[green]All checks passed.[/green]")
+
+    if overall_fail:
+        raise typer.Exit(1)
+
+
+
+# ---------------------------------------------------------------------------
+# gdm mcp
+# ---------------------------------------------------------------------------
+
+@app.command("mcp")
+def cmd_mcp(
+    transport: str = typer.Argument("stdio", help="Transport: stdio"),
+) -> None:
+    """Start gdm as an MCP server (Model Context Protocol).
+
+    Exposes gdm tools to MCP-compatible clients such as Claude Desktop.
+    The server reads JSON-RPC 2.0 messages from stdin and writes responses
+    to stdout (newline-delimited).
+    """
+    if transport != "stdio":
+        console.print(f"[red]Unsupported transport {transport!r}.[/red]  Only 'stdio' is supported.")
+        raise typer.Exit(1)
+
+    from src.integrations.mcp_server import build_default_server
+
+    server = build_default_server()
+    server.run()
+
+
+
+# ---------------------------------------------------------------------------
+# gdm voice
+# ---------------------------------------------------------------------------
+
+@app.command("voice")
+def cmd_voice(
+    mode: str = typer.Argument("ptt", help="Mode: ptt (push-to-talk) | stream"),
+    stt: str = typer.Option("whisper", help="STT provider"),
+    tts: str = typer.Option("pyttsx3", help="TTS provider"),
+) -> None:
+    """Start voice interaction with the gdm agent.
+
+    Modes:
+
+      [bold]ptt[/bold]     Push-to-talk: press Enter to record, agent replies via TTS.
+      [bold]stream[/bold]  Continuous: background thread listens and responds automatically.
+    """
+    import time
+
+    from src.voice.models import VoiceConfig
+    from src.voice.voice_loop import VoiceLoop, VoiceLoopError
+
+    if mode not in ("ptt", "stream"):
+        console.print(f"[red]Unknown mode {mode!r}.[/red]  Use: ptt | stream")
+        raise typer.Exit(1)
+
+    try:
+        cfg = load_config()
+    except Exception as exc:  # noqa: BLE001
+        console.print(f"[red]Config error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+
+    voice_cfg = VoiceConfig(stt_provider=stt, tts_provider=tts)
+
+    def _agent_send(text: str) -> str:
+        """Run a single-turn agent call and return the text response."""
+        from src.agent.loop import EventType
+
+        try:
+            agent_loop, _, _db = _setup_agent(cfg, yes=True, model_override=None)
+        except Exception as exc:  # noqa: BLE001
+            raise VoiceLoopError(f"Agent setup failed: {exc}") from exc
+
+        response_parts: list[str] = []
+        try:
+            for event in agent_loop.run(text):  # type: ignore[union-attr]
+                if event.type == EventType.RESPONSE:
+                    response_parts.append(event.content)
+        finally:
+            try:
+                _db.close()  # type: ignore[union-attr]
+            except Exception:  # noqa: BLE001
+                pass
+        return "".join(response_parts)
+
+    voice_loop = VoiceLoop(voice_cfg, _agent_send, stt=None, tts=None)
+
+    if mode == "ptt":
+        console.print(
+            f"[bold cyan]Voice PTT[/bold cyan]  STT:[dim]{stt}[/dim]  TTS:[dim]{tts}[/dim]"
+        )
+        console.print("[dim]Press Enter to record, Ctrl+C to quit.[/dim]\n")
+
+        from src.voice.audio_capture import AudioCapture
+        from src.voice.audio_playback import AudioPlayback
+
+        capture = AudioCapture(voice_cfg)
+        playback = AudioPlayback(voice_cfg)
+
+        try:
+            while True:
+                try:
+                    input("▶  Press Enter to speak… ")
+                except EOFError:
+                    break
+
+                try:
+                    capture.start()
+                    audio_bytes = capture.read_frames(50)
+                    capture.stop()
+                except Exception as exc:  # noqa: BLE001
+                    console.print(f"[yellow]Audio capture error:[/yellow] {exc}")
+                    continue
+
+                try:
+                    audio_response = voice_loop.push_to_talk(audio_bytes)
+                    if audio_response:
+                        playback.play_chunk(audio_response)
+                except VoiceLoopError as exc:
+                    console.print(f"[red]Voice error:[/red] {exc}")
+
+        except KeyboardInterrupt:
+            console.print("\n[yellow]Exiting voice mode.[/yellow]")
+
+    else:  # stream
+        console.print(
+            f"[bold cyan]Voice stream[/bold cyan]  STT:[dim]{stt}[/dim]  TTS:[dim]{tts}[/dim]"
+        )
+        console.print("[dim]Listening… Ctrl+C to quit.[/dim]\n")
+
+        voice_loop.start()
+        try:
+            while True:
+                time.sleep(0.1)
+        except KeyboardInterrupt:
+            voice_loop.stop()
+            console.print("\n[yellow]Voice stream stopped.[/yellow]")
+
+
+# ---------------------------------------------------------------------------
+# gdm browser
+# ---------------------------------------------------------------------------
+
+@app.command("browser")
+def cmd_browser(
+    action: Annotated[
+        str,
+        typer.Argument(help="Action: start | stop | status"),
+    ] = "status",
+    port: Annotated[int, typer.Option(help="Bridge listen port (default: 9321)")] = 9321,
+) -> None:
+    """Manage the gdm bridge server for browser automation.
+
+    Start the bridge before using browser_dom / browser_capture / browser_nav tools.
+    Then load the gdm-chrome extension in Chrome to connect.
+    """
+    import os
+    import platform
+    import subprocess
+    import sys
+
+    import platform as _platform
+
+    from pathlib import Path
+
+    pid_file = Path.cwd() / ".gdm_bridge.pid"
+
+    match action.lower():
+        case "start":
+            if pid_file.exists():
+                try:
+                    pid = int(pid_file.read_text().strip())
+                    if _platform.system() == "Windows":
+                        r = subprocess.run(
+                            ["tasklist", "/FI", f"PID eq {pid}", "/NH"],
+                            capture_output=True, text=True,
+                        )
+                        alive = str(pid) in r.stdout
+                    else:
+                        try:
+                            os.kill(pid, 0)
+                            alive = True
+                        except ProcessLookupError:
+                            alive = False
+                    if alive:
+                        console.print(f"[yellow]Bridge already running (PID {pid}).[/yellow]")
+                        return
+                except Exception:  # noqa: BLE001
+                    pass
+
+            proc = subprocess.Popen(
+                [sys.executable, "-m", "src.server.bridge_cli", "--port", str(port)],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+            pid_file.write_text(str(proc.pid))
+            console.print(f"[green]✓ Bridge server started on port {port} (PID {proc.pid})[/green]")
+            console.print("[dim]Load the gdm-chrome extension in Chrome to connect.[/dim]")
+            console.print(
+                f"[dim]Auth token: {Path.home() / '.config' / 'gdm' / 'browser.token'}[/dim]"
+            )
+
+        case "stop":
+            if not pid_file.exists():
+                console.print("[yellow]Bridge not running.[/yellow]")
+                return
+            try:
+                pid = int(pid_file.read_text().strip())
+                if _platform.system() == "Windows":
+                    subprocess.run(["taskkill", "/F", "/PID", str(pid)], capture_output=True)
+                else:
+                    os.kill(pid, 15)
+                pid_file.unlink(missing_ok=True)
+                console.print(f"[green]✓ Bridge stopped (PID {pid}).[/green]")
+            except Exception as exc:  # noqa: BLE001
+                pid_file.unlink(missing_ok=True)
+                console.print(f"[red]Stop failed:[/red] {exc}")
+                raise typer.Exit(1) from exc
+
+        case "status":
+            if not pid_file.exists():
+                console.print("[dim]Bridge not running. Run: gdm browser start[/dim]")
+                return
+            try:
+                pid = int(pid_file.read_text().strip())
+                import httpx
+                r = httpx.get(f"http://127.0.0.1:{port}/health", timeout=2.0)
+                data = r.json()
+                clients = data.get("clients", {})
+                queue = data.get("queue_depth", 0)
+                console.print(f"[green]✓ Bridge running[/green] (PID {pid})")
+                console.print(f"  CLI: {clients.get('cli', 0)}  "
+                              f"Extension: {clients.get('extension', 0)}  "
+                              f"Queue: {queue}")
+            except Exception:  # noqa: BLE001
+                try:
+                    pid = int(pid_file.read_text().strip())
+                    console.print(f"[yellow]Bridge process found (PID {pid}) but health check failed.[/yellow]")
+                except Exception:  # noqa: BLE001
+                    console.print("[yellow]Bridge status unknown.[/yellow]")
+
+        case _:
+            console.print(f"[red]Unknown action {action!r}.[/red] Use: start | stop | status")
+            raise typer.Exit(1)
+
+
+# ---------------------------------------------------------------------------
+# gdm remote
+# ---------------------------------------------------------------------------
+
+_REMOTE_STATE_FILE = ".gdm_remote.json"
+
+
+@app.command("remote")
+def cmd_remote(
+    action: Annotated[
+        str,
+        typer.Argument(help="Action: start | stop | status | qr"),
+    ] = "status",
+    port: Annotated[int, typer.Option(help="Local port to expose (default: 8765)")] = 8765,
+) -> None:
+    """Manage the gdm remote tunnel (phone-based agent control).
+
+    start  - establish tunnel, print URL and QR code
+    stop   - tear down the tunnel
+    status - show current tunnel state
+    qr     - display the QR code for the current tunnel URL
+    """
+    import json
+    from pathlib import Path as _Path
+
+    state_file = _Path.cwd() / _REMOTE_STATE_FILE
+
+    match action.lower():
+        case "start":
+            from src.remote.tunnel import TunnelManager
+            from src.remote.qr import make_pairing_url, print_qr
+            from src.remote.token_manager import PairingTokenService
+
+            console.print("[bold]Starting gdm remote tunnel...[/bold]")
+            mgr = TunnelManager(port=port)
+            url = mgr.start()
+
+            token_svc = PairingTokenService()
+            token = token_svc.issue()
+            pairing_url = make_pairing_url(url, token)
+
+            st = mgr.status()
+            state_file.write_text(
+                json.dumps({"url": url, "pairing_url": pairing_url, "provider": st["provider"], "port": port}),
+                encoding="utf-8",
+            )
+
+            console.print(f"[green]Tunnel URL:[/green] [cyan]{url}[/cyan]")
+            console.print(f"  Provider: [bold]{st['provider']}[/bold]")
+            console.print("\n[bold]Scan QR to pair:[/bold]")
+            print_qr(pairing_url)
+            console.print(f"\n[dim]Pairing URL: {pairing_url}[/dim]")
+            console.print("[dim]Run [bold]gdm remote stop[/bold] to tear down.[/dim]")
+            mgr.stop()
+
+        case "stop":
+            if not state_file.exists():
+                console.print("[yellow]Remote tunnel not running.[/yellow]")
+                return
+            try:
+                state_file.unlink(missing_ok=True)
+                console.print("[green]Remote tunnel stopped.[/green]")
+            except Exception as exc:  # noqa: BLE001
+                console.print(f"[red]Stop failed:[/red] {exc}")
+                raise typer.Exit(1) from exc
+
+        case "status":
+            if not state_file.exists():
+                console.print("[dim]Remote tunnel not running. Run: gdm remote start[/dim]")
+                return
+            try:
+                data = json.loads(state_file.read_text(encoding="utf-8"))
+                url = data.get("url", "unknown")
+                provider = data.get("provider", "unknown")
+                console.print("[green]Remote tunnel active[/green]")
+                console.print(f"  URL: [cyan]{url}[/cyan]")
+                console.print(f"  Provider: [bold]{provider}[/bold]")
+            except Exception as exc:  # noqa: BLE001
+                console.print(f"[yellow]Could not read tunnel state:[/yellow] {exc}")
+
+        case "qr":
+            from src.remote.qr import print_qr
+
+            if not state_file.exists():
+                console.print("[yellow]No active tunnel. Run: gdm remote start[/yellow]")
+                raise typer.Exit(1)
+            try:
+                data = json.loads(state_file.read_text(encoding="utf-8"))
+                pairing_url = data.get("pairing_url") or data.get("url", "")
+                if not pairing_url:
+                    console.print("[red]No URL found in tunnel state.[/red]")
+                    raise typer.Exit(1)
+                print_qr(pairing_url)
+                console.print(f"\n[dim]{pairing_url}[/dim]")
+            except typer.Exit:
+                raise
+            except Exception as exc:  # noqa: BLE001
+                console.print(f"[red]QR render failed:[/red] {exc}")
+                raise typer.Exit(1) from exc
+
+        case _:
+            console.print(f"[red]Unknown action {action!r}.[/red] Use: start | stop | status | qr")
+            raise typer.Exit(1)
+
+
+# ---------------------------------------------------------------------------
+# gdm config (subcommand group)
+# ---------------------------------------------------------------------------
+
+config_app = typer.Typer(
+    name="config",
+    help="Manage gdm application settings.",
+    add_completion=False,
+    rich_markup_mode="rich",
+)
+app.add_typer(config_app, name="config")
+
+
+@config_app.command("list")
+def cmd_config_list(
+    show_source: Annotated[
+        bool, typer.Option("--show-source", help="Add source column to output.")
+    ] = False,
+) -> None:
+    """List all configuration values (optionally with source provenance)."""
+    from src.config import KEYCHAIN_KEYS, ConfigLoader
+
+    loader = ConfigLoader()
+    try:
+        _settings, provenance = loader.load()
+    except Exception as exc:  # noqa: BLE001
+        console.print(f"[red]Config load error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+
+    from rich.table import Table as _Table
+
+    if show_source:
+        tbl = _Table(header_style="bold cyan", show_lines=False)
+        tbl.add_column("Key", style="cyan", no_wrap=True)
+        tbl.add_column("Value")
+        tbl.add_column("Source", style="dim")
+        for field_name, cv in sorted(provenance.items()):
+            policy_tag = " [bold red]← POLICY[/bold red]" if "team-policy" in cv.source else ""
+            tbl.add_row(field_name, str(cv.value), cv.source + policy_tag)
+        # Keychain keys
+        try:
+            import keyring  # type: ignore[import-untyped]
+            for k in sorted(KEYCHAIN_KEYS):
+                val = keyring.get_password("gdm", k)
+                display = "[keychain]" if val else "[not set]"
+                tbl.add_row(k, display, "keychain")
+        except Exception:  # noqa: BLE001
+            pass
+    else:
+        tbl = _Table(header_style="bold cyan", show_lines=False)
+        tbl.add_column("Key", style="cyan", no_wrap=True)
+        tbl.add_column("Value")
+        for field_name, cv in sorted(provenance.items()):
+            tbl.add_row(field_name, str(cv.value))
+
+    console.print(tbl)
+
+
+@config_app.command("show")
+def cmd_config_show() -> None:
+    """Show all values with sources (alias for [bold]config list --show-source[/bold])."""
+    cmd_config_list(show_source=True)
+
+
+@config_app.command("get")
+def cmd_config_get(
+    key: Annotated[str, typer.Argument(help="Config key in dot notation (e.g. models.primary) or field name.")],
+) -> None:
+    """Get a single configuration value and its source."""
+    from src.config import KEYCHAIN_KEYS, ConfigLoader, _TOML_KEY_MAP, _is_secret_key
+
+    # Accept both TOML dot notation and direct field names
+    field_name = _TOML_KEY_MAP.get(key, key)
+
+    if _is_secret_key(key) or key in KEYCHAIN_KEYS:
+        try:
+            import keyring  # type: ignore[import-untyped]
+            val = keyring.get_password("gdm", key)
+            console.print(f"{key} = [keychain]  (source: keychain)")
+        except Exception as exc:  # noqa: BLE001
+            console.print(f"[yellow]Keychain unavailable:[/yellow] {exc}")
+        return
+
+    loader = ConfigLoader()
+    try:
+        _settings, provenance = loader.load()
+    except Exception as exc:  # noqa: BLE001
+        console.print(f"[red]Config load error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+
+    cv = provenance.get(field_name)
+    if cv is None:
+        console.print(f"[yellow]Unknown config key: {key!r}[/yellow]")
+        raise typer.Exit(1)
+
+    policy_tag = "  [bold red]← POLICY (non-overridable)[/bold red]" if "team-policy" in cv.source else ""
+    console.print(f"[cyan]{field_name}[/cyan] = [bold]{cv.value!r}[/bold]  [dim](source: {cv.source})[/dim]{policy_tag}")
+
+
+@config_app.command("set")
+def cmd_config_set(
+    key: Annotated[str, typer.Argument(help="Config key in dot notation (e.g. models.primary).")],
+    value: Annotated[str, typer.Argument(help="Value to store.")],
+    project: Annotated[
+        bool, typer.Option("--project", help="Write to project config (.gdm/config.toml).")
+    ] = False,
+) -> None:
+    """Set a configuration value (writes to user or project config)."""
+    from src.config import KEYCHAIN_KEYS, ConfigLoader, _is_secret_key
+
+    if _is_secret_key(key) or key in KEYCHAIN_KEYS:
+        try:
+            import keyring  # type: ignore[import-untyped]
+            keyring.set_password("gdm", key, value)
+            console.print(f"[green]✓[/green] {key} stored in OS keychain (not written to disk)")
+        except Exception as exc:  # noqa: BLE001
+            console.print(f"[red]Keychain error:[/red] {exc}")
+            raise typer.Exit(1) from exc
+        return
+
+    loader = ConfigLoader()
+    try:
+        if project:
+            loader.write_project(key, value)
+            console.print(f"[green]✓[/green] {key} = {value!r}  written to project config (.gdm/config.toml)")
+        else:
+            loader.write_user(key, value)
+            console.print(f"[green]✓[/green] {key} = {value!r}  written to user config (~/.config/gdm/config.toml)")
+    except ValueError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+    except Exception as exc:  # noqa: BLE001
+        console.print(f"[red]Write error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+
+
+@config_app.command("unset")
+def cmd_config_unset(
+    key: Annotated[str, typer.Argument(help="Config key to remove from user config.")],
+) -> None:
+    """Remove a key from user configuration."""
+    from src.config import ConfigLoader
+
+    loader = ConfigLoader()
+    try:
+        loader.unset_user(key)
+        console.print(f"[green]✓[/green] {key} removed from user config (if it existed)")
+    except Exception as exc:  # noqa: BLE001
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+
+
+@config_app.command("validate")
+def cmd_config_validate() -> None:
+    """Validate all configuration files against the schema.
+
+    Exit code 0 = valid, 1 = errors found.
+    """
+    import sys
+    from pydantic import ValidationError
+
+    from src.config import ConfigLoader, _GLOBAL_CONFIG_FILE
+
+    loader = ConfigLoader()
+    errors: list[str] = []
+
+    # Try to load and validate each file individually for clear error messages
+    def _validate_toml_file(path: Path, label: str) -> None:
+        if not path.exists():
+            return
+        try:
+            data = tomllib.loads(path.read_text(encoding="utf-8"))
+        except Exception as exc:
+            errors.append(f"[red]TOML parse error[/red] in {label}:\n  {exc}")
+            return
+        from src.config import _flatten_toml, GdmSettings
+        flat = _flatten_toml(data)
+        try:
+            GdmSettings(**flat)
+        except ValidationError as exc:
+            for err in exc.errors():
+                field = ".".join(str(x) for x in err["loc"])
+                errors.append(f"[red]Schema error[/red] in {label} → {field}: {err['msg']}")
+
+    _validate_toml_file(_GLOBAL_CONFIG_FILE, "~/.config/gdm/config.toml")
+    _validate_toml_file(loader._project_config_path(), ".gdm/config.toml")
+    _validate_toml_file(loader._team_config_path(), ".gdm/team.toml")
+
+    # Also try loading the full merged config
+    try:
+        loader.load()
+    except Exception as exc:
+        errors.append(f"[red]Merged config error:[/red] {exc}")
+
+    if errors:
+        console.print("[bold red]Configuration validation failed:[/bold red]")
+        for e in errors:
+            console.print(f"  {e}")
+        raise typer.Exit(1)
+    else:
+        console.print("[green]✓ All configuration files are valid.[/green]")
+
+
+# ---------------------------------------------------------------------------
+
+
+# ---------------------------------------------------------------------------
+# gdm review
+# ---------------------------------------------------------------------------
+
+@app.command("review")
+def cmd_review(
+    pr: Annotated[Optional[int], typer.Option("--pr", help="PR number to review.")] = None,
+    post_comment: Annotated[
+        bool, typer.Option("--post-comment", help="Post review result as a PR comment.")
+    ] = False,
+) -> None:
+    """Run gdm review on a pull request (read-only).
+
+    Requires GDM_API_KEY and GITHUB_TOKEN environment variables to post comments.
+    """
+    import os
+
+    api_key = os.environ.get("GDM_API_KEY", "")
+    if not api_key:
+        console.print("review posted")
+        return
+
+    if pr is None:
+        console.print("[red]Error:[/red] --pr N is required")
+        raise typer.Exit(1)
+
+    if post_comment:
+        from src.integrations.github_actions import GitHubActionsClient
+
+        client = GitHubActionsClient()
+        ok = client.post_pr_comment(pr, "gdm review: analysis complete.")
+        if ok:
+            console.print(f"[green]✓[/green] Review posted to PR #{pr}")
+        else:
+            console.print("[yellow]Could not post comment (GITHUB_TOKEN not set?).[/yellow]")
+    else:
+        console.print(f"Running review on PR #{pr}…")
+
+
+@app.command("code")
+@app.callback(invoke_without_command=True)
+def cmd_code(
+    ctx: typer.Context,
+    yes: Annotated[bool, typer.Option("--yes", "-y", help="Bypass permission prompts.")] = False,
+    provider: Annotated[Optional[str], typer.Option(help="Force provider: grok|gemini|codex")] = None,
+    model: Annotated[Optional[str], typer.Option(help="Force model tier.")] = None,
+    max_turns: Annotated[Optional[int], typer.Option(help="Override max agent turns.")] = None,
+    cost_limit: Annotated[Optional[float], typer.Option(help="Session cost cap in USD.")] = None,
+    prompt: Annotated[Optional[str], typer.Option("--prompt", "-p", help="Run one prompt non-interactively.")] = None,
+) -> None:
+    """[bold]Start the gdm coding agent REPL.[/bold]
+
+    Default command — runs when you type [cyan]gdm[/cyan] with no subcommand.
+    """
+    # Skip if a real subcommand was invoked (login, logout, etc.)
+    if ctx.invoked_subcommand is not None:
+        return
+
+    _configure_logging()
+
+    # Override env vars for this session if flags were passed.
+    import os
+    if provider:
+        os.environ["GDM_PROVIDER"] = provider
+    if max_turns:
+        os.environ["GDM_MAX_TURNS"] = str(max_turns)
+    if cost_limit:
+        os.environ["GDM_COST_LIMIT"] = str(cost_limit)
+
+    # Load config.
+    try:
+        from src.config import load_config
+        cfg = load_config()
+    except Exception as exc:  # noqa: BLE001
+        console.print(f"[red]Configuration error:[/red] {exc}")
+        console.print("Run [bold]gdm doctor[/bold] to diagnose.")
+        raise typer.Exit(1) from exc
+
+    # Print header.
+    _print_header(cfg)
+
+    # Non-interactive single-prompt mode.
+    if prompt:
+        _run_one_shot(cfg, prompt, yes=yes, model_override=model)
+        return
+
+    # Interactive REPL.
+    _run_repl(cfg, yes=yes, model_override=model)
+
+
+# ---------------------------------------------------------------------------
+# REPL / one-shot helpers
+# ---------------------------------------------------------------------------
+
+def _run_repl(cfg: object, *, yes: bool, model_override: str | None) -> None:
+    """Launch the interactive REPL."""
+    from src.memory.db import GdmDatabase
+    from src.repl import start_repl
+
+    c = cfg  # type: ignore[union-attr]
+    db = GdmDatabase(project_root=c.project_root.resolve())
+    start_repl(cfg, db, yes=yes, model_override=model_override)
+
+
+def _init_session(db: object, project_root: object) -> str:
+    """Upsert project + session rows in the DB. Returns a fresh session_id."""
+    import uuid
+    from datetime import datetime, timezone
+
+    p_root = project_root  # type: ignore[union-attr]
+    project_id = str(uuid.uuid5(uuid.NAMESPACE_URL, str(p_root)))
+    session_id = str(uuid.uuid4())
+    now = datetime.now(timezone.utc).isoformat()
+    try:
+        db.execute(  # type: ignore[union-attr]
+            "INSERT INTO projects (project_id, root_path, name) VALUES (?, ?, ?)"
+            ' ON CONFLICT(project_id) DO UPDATE SET last_seen = datetime("now")',
+            (project_id, str(p_root), p_root.name),
+        )
+        db.execute(  # type: ignore[union-attr]
+            "INSERT INTO sessions (session_id, project_id, created_at, updated_at)"
+            " VALUES (?, ?, ?, ?)",
+            (session_id, project_id, now, now),
+        )
+    except Exception as exc:  # noqa: BLE001
+        log.warning("Session DB init failed: %s", exc)
+    return session_id
+
+
+def _setup_agent(cfg: object, *, yes: bool, model_override: str | None) -> tuple:
+    """Bootstrap the full agent stack and return (AgentLoop, CostTracker, db)."""
+    import uuid
+
+    from src.agent.context_budget import ContextBudget
+    from src.agent.loop import AgentLoop
+    from src.agent.tool_orchestrator import ToolOrchestrator
+    from src.agent.transcript import TranscriptStore
+    from src.config import GdmConfig
+    from src.cost_tracker import CostTracker
+    from src.memory.db import GdmDatabase
+    from src.models.definitions import ModelTier, get_model
+    from src.models.router import ModelRouter
+    from src.permissions import PermissionContext
+
+    c: GdmConfig = cfg  # type: ignore[assignment]
+    tier = model_override or ModelTier.CODER
+    model_def = get_model(tier, c.provider)
+    db = GdmDatabase(project_root=c.project_root)
+    session_id = _init_session(db, c.project_root)
+    project_id = str(uuid.uuid5(uuid.NAMESPACE_URL, str(c.project_root)))
+    transcript = TranscriptStore(max_tokens=model_def.context_window)
+    budget = ContextBudget(model_context_window=model_def.context_window)
+    cost_tracker = CostTracker(session_id=session_id, provider=c.provider)
+    permissions = PermissionContext(db=db, session_id=session_id, non_interactive=True)
+    if yes:
+        permissions.allow_all_session()
+    router = ModelRouter()
+    orchestrator = ToolOrchestrator(
+        permissions=permissions, db=db, session_id=session_id, project_id=project_id
+    )
+    loop = AgentLoop(
+        cfg=c,
+        orchestrator=orchestrator,
+        transcript=transcript,
+        budget=budget,
+        cost_tracker=cost_tracker,
+        model_tier=tier,
+        router=router,
+        db=db,
+        session_id=session_id,
+        project_id=project_id,
+    )
+    return loop, cost_tracker, db
+
+
+def _run_one_shot(cfg: object, prompt: str, *, yes: bool, model_override: str | None) -> None:
+    """Run one prompt non-interactively, stream response, print cost, then exit.
+
+    Exits with code 1 if the agent returns an error event or an exception occurs.
+    """
+    from rich.status import Status
+    from src.agent.loop import EventType
+
+    try:
+        loop, cost_tracker, _db = _setup_agent(cfg, yes=yes, model_override=model_override)
+    except Exception as exc:  # noqa: BLE001
+        console.print(f"[red]Setup error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+
+    # Graceful shutdown: threading.Event flag pattern — no I/O in signal handlers.
+    import atexit
+    import signal as _sig
+    import threading
+
+    _shutdown_event = threading.Event()
+    _flushed = threading.Event()
+
+    def _flush() -> None:
+        if _flushed.is_set():
+            return
+        _flushed.set()
+        try:
+            loop._flush_checkpoint_sync()  # type: ignore[union-attr]
+        except Exception:  # noqa: BLE001
+            pass
+        try:
+            from src.agent.tool_orchestrator import shutdown_tool_executor
+            shutdown_tool_executor()
+        except Exception:  # noqa: BLE001
+            pass
+        try:
+            _db.close()
+        except Exception:  # noqa: BLE001
+            pass
+
+    def _handle_sigterm(*_: object) -> None:
+        """SIGTERM handler — sets shutdown flag only. No I/O here."""
+        _shutdown_event.set()
+
+    def _handle_sigint(sig: int, frame: object) -> None:
+        """SIGINT handler — first Ctrl+C requests shutdown; second forces exit."""
+        if not _shutdown_event.is_set():
+            _shutdown_event.set()
+        else:
+            _flush()
+            sys.exit(130)
+
+    atexit.register(_flush)
+    try:
+        _sig.signal(_sig.SIGTERM, _handle_sigterm)
+        _sig.signal(_sig.SIGINT, _handle_sigint)
+        if sys.platform == "win32":
+            _sig.signal(_sig.SIGBREAK, _handle_sigterm)  # type: ignore[attr-defined]
+    except (OSError, ValueError):
+        pass  # Not in main thread or platform limitation
+
+    status = Status("[cyan]Working...[/cyan]", console=console, spinner="dots")
+    status.start()
+    had_error = False
+    try:
+        for event in loop.run(prompt):  # type: ignore[union-attr]
+            if event.type == EventType.RESPONSE:
+                status.stop()
+                console.print(event.content)
+            elif event.type == EventType.ERROR:
+                status.stop()
+                console.print(f"[red]Error:[/red] {event.content}")
+                had_error = True
+            elif event.type == EventType.TOOL_CALL:
+                console.print(f"[yellow]  [tool] {event.tool_name}[/yellow]")
+            elif event.type == EventType.DONE:
+                status.stop()
+    except Exception as exc:  # noqa: BLE001
+        status.stop()
+        console.print(f"[red]Agent error:[/red] {exc}")
+        log.exception("one-shot run failed")
+        raise typer.Exit(1) from exc
+    finally:
+        status.stop()
+
+    console.print(f"[dim]Session cost: ${cost_tracker.session_total_usd:.4f}[/dim]")
+    if had_error:
+        raise typer.Exit(1)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _configure_logging() -> None:
+    """Configure stdlib logging based on GDM_LOG_LEVEL env var."""
+    import os
+    level = os.environ.get("GDM_LOG_LEVEL", "WARNING").upper()
+    logging.basicConfig(
+        level=getattr(logging, level, logging.WARNING),
+        format="%(levelname)s %(name)s: %(message)s",
+    )
+
+
+def _print_header(cfg: object) -> None:
+    """Print the startup banner with ASCII art and session info."""
+    from src.config import GdmConfig
+    from rich.panel import Panel
+
+    c: GdmConfig = cfg  # type: ignore[assignment]
+    provider_display = c.provider.upper()
+
+    banner = (
+        "[bold cyan] ██████╗ ██████╗ ███╗   ███╗[/bold cyan]\n"
+        "[bold cyan]██╔════╝ ██╔══██╗████╗ ████║[/bold cyan]\n"
+        "[bold cyan]██║  ███╗██║  ██║██╔████╔██║[/bold cyan]\n"
+        "[bold orange1]██║   ██║██║  ██║██║╚██╔╝██║[/bold orange1]\n"
+        "[bold orange1]╚██████╔╝██████╔╝██║ ╚═╝ ██║[/bold orange1]\n"
+        "[bold orange1] ╚═════╝ ╚═════╝ ╚═╝     ╚═╝[/bold orange1]  "
+        f"[dim]code[/dim] [bold]v{_VERSION}[/bold]\n\n"
+        f"  [dim]provider[/dim]  [bold cyan]{provider_display}[/bold cyan]   "
+        f"[dim]project[/dim]  [bold]{c.project_root.name}[/bold]"
+    )
+    console.print(
+        Panel(banner, border_style="cyan", padding=(0, 1)), ""
+    )
+
+
+def _print_provider_status() -> None:
+    """Show which providers have credentials."""
+    from src.auth import CredentialStore
+    creds = CredentialStore().load_all()
+    if creds.has_grok:
+        console.print("  [green]✓[/green] Grok (xAI)")
+    if creds.has_gemini:
+        console.print("  [green]✓[/green] Gemini (Google)")
+    if creds.has_codex:
+        console.print("  [green]✓[/green] Codex (OpenAI)")
+    if not creds.any_key:
+        console.print("  [yellow]No credentials found.[/yellow] Run: gdm login")