code-context-control 2.28.0__py3-none-any.whl

cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Command modules for the C3 CLI."""

cli/commands/common.py

@@ -0,0 +1,312 @@
+"""Shared lightweight CLI command handlers."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class CommandDeps:
+    load_config: object
+    print_header: object
+    print_savings: object
+    count_tokens: object
+    format_token_count: object
+    CodeIndex: object
+    CodeCompressor: object
+    CompressionProtocol: object
+    SessionManager: object
+    HAS_RICH: bool
+    Table: object
+    console: object
+    __file__: str
+
+
+def cmd_index(args, deps: CommandDeps):
+    """Rebuild the code index."""
+    config = deps.load_config()
+    project_path = config.get("project_path", ".")
+
+    deps.print_header("Rebuilding Code Index")
+    indexer = deps.CodeIndex(project_path)
+    result = indexer.build_index(max_files=args.max_files or 500)
+
+    if deps.HAS_RICH:
+        table = deps.Table(title="Index Results")
+        table.add_column("Metric", style="cyan")
+        table.add_column("Value", style="green")
+        table.add_row("Files Indexed", str(result["files_indexed"]))
+        table.add_row("Chunks Created", str(result["chunks_created"]))
+        table.add_row("Unique Symbols", str(result["unique_symbols"]))
+        deps.console.print(table)
+    else:
+        print(f"  Files: {result['files_indexed']}, Chunks: {result['chunks_created']}, Symbols: {result['unique_symbols']}")
+
+
+def cmd_compress(args, deps: CommandDeps):
+    """Compress a file and show results."""
+    config = deps.load_config()
+    mode = args.mode or "smart"
+
+    compressor = deps.CodeCompressor(str(Path(config.get("project_path", ".")) / ".c3/cache"))
+    result = compressor.compress_file(args.file, mode)
+
+    if "error" in result:
+        print(f"Error: {result['error']}")
+        return
+
+    deps.print_header(f"Compressed: {args.file} (mode: {result.get('mode', mode)})")
+    deps.print_savings(result)
+
+    if args.output:
+        print(f"\n--- Compressed Output ---\n{result['compressed']}")
+
+
+def cmd_context(args, deps: CommandDeps):
+    """Get relevant context for a query."""
+    config = deps.load_config()
+    project_path = config.get("project_path", ".")
+
+    indexer = deps.CodeIndex(project_path)
+    context = indexer.get_context(
+        args.query,
+        top_k=args.top_k or 5,
+        max_tokens=args.max_tokens or 4000,
+    )
+
+    if args.pipe:
+        print(context)
+    else:
+        deps.print_header(f"Context for: {args.query}")
+        tokens = deps.count_tokens(context)
+        print(f"  Context tokens: {deps.format_token_count(tokens)}")
+        print(f"\n{context}")
+
+
+def cmd_encode(args, deps: CommandDeps):
+    """Encode text to compressed format."""
+    config = deps.load_config()
+    protocol = deps.CompressionProtocol(config.get("project_path", "."))
+
+    text = " ".join(args.text)
+    result = protocol.encode(text)
+
+    if args.pipe:
+        print(result["compressed"])
+    else:
+        deps.print_header("Compression Protocol - Encode")
+        print(f"  Original:   {result['original']}")
+        print(f"  Compressed: {result['compressed']}")
+        deps.print_savings(result)
+
+
+def cmd_decode(args, deps: CommandDeps):
+    """Decode compressed text back to readable format."""
+    config = deps.load_config()
+    protocol = deps.CompressionProtocol(config.get("project_path", "."))
+
+    text = " ".join(args.text)
+    decoded = protocol.decode(text)
+    print(decoded)
+
+
+def cmd_session(args, deps: CommandDeps):
+    """Session management commands."""
+    config = deps.load_config()
+    sm = deps.SessionManager(config.get("project_path", "."))
+
+    if args.session_cmd == "start":
+        desc = " ".join(args.extra) if args.extra else ""
+        result = sm.start_session(desc)
+        print(f"Session started: {result['session_id']}")
+
+    elif args.session_cmd == "save":
+        summary = " ".join(args.extra) if args.extra else ""
+        result = sm.save_session(summary)
+        if "error" in result:
+            print(f"Error: {result['error']}")
+        else:
+            print(f"Session {result['session_id']} saved ({result['decisions']} decisions, {result['files']} files)")
+
+    elif args.session_cmd == "load":
+        session_id = args.extra[0] if args.extra else "latest"
+        session = sm.load_session(session_id)
+        if "error" in session:
+            print(f"Error: {session['error']}")
+        else:
+            print(json.dumps(session, indent=2))
+
+    elif args.session_cmd == "list":
+        sessions = sm.list_sessions()
+        if deps.HAS_RICH:
+            table = deps.Table(title="Session History")
+            table.add_column("ID", style="cyan")
+            table.add_column("Date", style="green")
+            table.add_column("Summary", style="white")
+            table.add_column("Decisions", style="yellow")
+            for session in sessions:
+                table.add_row(session["id"], session["started"], session["summary"][:60], str(session["decisions"]))
+            deps.console.print(table)
+        else:
+            for session in sessions:
+                print(f"  {session['id']} | {session['started']} | {session['summary'][:50]} | {session['decisions']} decisions")
+
+    elif args.session_cmd == "context":
+        context = sm.get_session_context()
+        print(context)
+
+
+def cmd_claudemd(args, deps: CommandDeps):
+    """Instructions file generation commands."""
+    config = deps.load_config()
+    project_path = config.get("project_path", ".")
+    sm = deps.SessionManager(project_path)
+
+    from core.ide import get_profile as _get_profile
+    from core.ide import load_ide_config
+    from services.claude_md import ClaudeMdManager
+    from services.memory import MemoryStore
+
+    ide_name = load_ide_config(project_path)
+    profile = _get_profile(ide_name)
+    instructions_file = profile.instructions_file or "CLAUDE.md"
+
+    if args.claudemd_cmd in ("generate", "save"):
+        indexer = deps.CodeIndex(project_path)
+        indexer._load_index()
+        memory = MemoryStore(project_path)
+        claude_md = ClaudeMdManager(
+            project_path,
+            sm,
+            indexer,
+            memory,
+            instructions_file=instructions_file,
+            line_limit=profile.instructions_line_limit or 200,
+            supports_hooks=profile.supports_hooks,
+            supports_clear=profile.supports_clear,
+        )
+
+        mode = "nano" if getattr(args, "nano", False) else "compact"
+        gen = claude_md.generate(mode=mode)
+        content = gen.get("content", "")
+        tokens = gen.get("tokens", 0)
+        mode_label = " [nano]" if mode == "nano" else ""
+
+        if args.claudemd_cmd == "generate":
+            deps.print_header(f"Generated {instructions_file}{mode_label} ({deps.format_token_count(tokens)} tokens)")
+            print(content)
+        else:
+            output_path = Path(project_path) / instructions_file
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            if output_path.exists():
+                existing = output_path.read_text(encoding="utf-8", errors="replace")
+                if "# User Notes" in existing:
+                    user_section = existing[existing.index("# User Notes"):]
+                    content += f"\n\n{user_section}"
+            output_path.write_text(content, encoding="utf-8")
+            print(f"{instructions_file} saved to {output_path} ({tokens} tokens)")
+
+    elif args.claudemd_cmd == "check":
+        indexer = deps.CodeIndex(project_path)
+        indexer._load_index()
+        memory = MemoryStore(project_path)
+        claude_md = ClaudeMdManager(
+            project_path,
+            sm,
+            indexer,
+            memory,
+            instructions_file=instructions_file,
+            line_limit=profile.instructions_line_limit or 200,
+            supports_hooks=profile.supports_hooks,
+            supports_clear=profile.supports_clear,
+        )
+        result = claude_md.check_staleness()
+        deps.print_header(f"{instructions_file} Health - {result['status'].upper()}")
+        if "lines" in result:
+            print(f"  Size: {result['lines']} lines, {result['tokens']} tokens")
+        for issue in result.get("issues", []):
+            icon = {"error": "[ERROR]", "warning": "[WARN]", "info": "[INFO]"}.get(issue["severity"], "[?]")
+            print(f"  {icon} {issue['message']}")
+
+
+def cmd_stats(args, deps: CommandDeps):
+    """Show comprehensive stats."""
+    config = deps.load_config()
+    project_path = config.get("project_path", ".")
+
+    deps.print_header("C3 Statistics")
+    indexer = deps.CodeIndex(project_path)
+    idx_stats = indexer.get_stats()
+    protocol = deps.CompressionProtocol(project_path)
+    proto_stats = protocol.get_stats()
+
+    if deps.HAS_RICH:
+        table = deps.Table(title="System Overview")
+        table.add_column("Component", style="cyan")
+        table.add_column("Metric", style="white")
+        table.add_column("Value", style="green")
+
+        table.add_row("Index", "Files Indexed", str(idx_stats.get("files_indexed", 0)))
+        table.add_row("Index", "Total Chunks", str(idx_stats.get("total_chunks", 0)))
+        table.add_row("Index", "Codebase Tokens", deps.format_token_count(idx_stats.get("total_tokens_in_codebase", 0)))
+        table.add_row("Index", "Index Size", f"{idx_stats.get('index_size_kb', 0)} KB")
+        table.add_row("Protocol", "Built-in Codes", str(proto_stats.get("built_in_actions", 0) + proto_stats.get("built_in_terms", 0)))
+        table.add_row("Protocol", "Custom Terms", str(proto_stats.get("custom_terms", 0)))
+
+        deps.console.print(table)
+    else:
+        print(f"  Index: {idx_stats.get('files_indexed', 0)} files, {idx_stats.get('total_chunks', 0)} chunks")
+        print(f"  Codebase: {deps.format_token_count(idx_stats.get('total_tokens_in_codebase', 0))} tokens")
+        print(f"  Protocol: {proto_stats.get('total_codes', 0)} compression codes")
+
+
+def cmd_optimize(args, deps: CommandDeps):
+    """Show optimization suggestions."""
+    config = deps.load_config()
+    sm = deps.SessionManager(config.get("project_path", "."))
+
+    deps.print_header("Optimization Suggestions")
+    suggestions = sm.get_optimization_suggestions()
+    for i, suggestion in enumerate(suggestions, 1):
+        print(f"  {i}. {suggestion}")
+
+
+def cmd_pipe(args, deps: CommandDeps):
+    """All-in-one pipeline: get context + output for piping to Claude."""
+    config = deps.load_config()
+    project_path = config.get("project_path", ".")
+    query = " ".join(args.query)
+
+    indexer = deps.CodeIndex(project_path)
+    context = indexer.get_context(query, top_k=args.top_k or 5, max_tokens=args.max_tokens or 4000)
+
+    sm = deps.SessionManager(project_path)
+    session_context = sm.get_session_context(n_sessions=2)
+
+    output_parts = []
+    if session_context and "No previous" not in session_context:
+        output_parts.append(session_context)
+
+    output_parts.append(context)
+    output_parts.append(f"\n## Task\n{query}")
+    print("\n\n".join(output_parts))
+
+
+def cmd_ui(args, deps: CommandDeps):
+    """Launch the web UI."""
+    server_path = Path(deps.__file__).parent / "server.py"
+    spec = importlib.util.spec_from_file_location("server", str(server_path))
+    server = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(server)
+
+    project_path = args.project_path or "."
+    server.run_server(
+        project_path,
+        port=args.port,
+        open_browser=not args.no_browser,
+        silent=args.silent,
+        nano=args.nano,
+    )

cli/commands/parser.py

@@ -0,0 +1,286 @@
+"""Argument parser construction for the C3 CLI."""
+
+from __future__ import annotations
+
+import argparse
+
+
+def build_parser(version: str, parse_cli_ide_arg):
+    parser = argparse.ArgumentParser(
+        prog="c3",
+        description="Claude Code Companion - Reduce token usage with local intelligence",
+    )
+    parser.add_argument("--version", "-v", action="version", version=f"c3 version {version}")
+    subparsers = parser.add_subparsers(dest="command")
+
+    p_init = subparsers.add_parser("init", help="Initialize C3 for a project")
+    p_init.add_argument("project_path", nargs="?", default=".")
+    p_init.add_argument("--force", action="store_true", help="Skip prompts and apply update non-interactively")
+    p_init.add_argument("--clear", action="store_true", help="Remove all C3 files and exit without rebuilding")
+    p_init.add_argument("--ide", default="auto", type=parse_cli_ide_arg, metavar="{auto,claude,vscode,cursor,codex,gemini,antigravity}", help="Target IDE for MCP config (default: auto-detect)")
+    p_init.add_argument("--mcp-mode", choices=["direct", "proxy"], default="direct", help="Default MCP mode if install is selected during init (default: direct)")
+    p_init.add_argument("--git", action="store_true", help="Initialize a local Git repository during init/update")
+    p_init.add_argument("--permissions", choices=["read-only", "c3-strict", "standard", "permissive"], default=None, help="Apply Claude Code permission tier (Claude Code only, used with --force)")
+    p_init.add_argument("--include-mcp-wildcard", action="store_true", help="Add mcp__* wildcard so non-C3 MCP servers don't prompt per-call")
+
+    p_index = subparsers.add_parser("index", help="Rebuild code index")
+    p_index.add_argument("--max-files", type=int, default=500)
+
+    p_compress = subparsers.add_parser("compress", help="Compress a file")
+    p_compress.add_argument("file", help="File to compress")
+    p_compress.add_argument("--mode", choices=["map", "dense_map", "smart", "diff"], default="smart")
+    p_compress.add_argument("--output", "-o", action="store_true", help="Show compressed output")
+
+    p_context = subparsers.add_parser("context", help="Get relevant context for a query")
+    p_context.add_argument("query", help="What you want to do")
+    p_context.add_argument("--top-k", type=int, default=5)
+    p_context.add_argument("--max-tokens", type=int, default=4000)
+    p_context.add_argument("--pipe", action="store_true", help="Raw output for piping")
+
+    p_encode = subparsers.add_parser("encode", help="Encode text to compressed format")
+    p_encode.add_argument("text", nargs="+")
+    p_encode.add_argument("--pipe", action="store_true")
+
+    p_decode = subparsers.add_parser("decode", help="Decode compressed format")
+    p_decode.add_argument("text", nargs="+")
+
+    p_session = subparsers.add_parser("session", help="Session management")
+    p_session.add_argument("session_cmd", choices=["start", "save", "load", "list", "context"])
+    p_session.add_argument("extra", nargs="*")
+
+    p_claudemd = subparsers.add_parser("claudemd", help="CLAUDE.md management")
+    p_claudemd.add_argument("claudemd_cmd", choices=["generate", "save", "check"])
+    p_claudemd.add_argument("--nano", action="store_true", help="Generate nano mode (~250 tokens) instead of full compact mode")
+
+    subparsers.add_parser("stats", help="Show statistics")
+
+    p_benchmark = subparsers.add_parser("benchmark", help="Run with/without-C3 workflow benchmark")
+    p_benchmark.add_argument("project_path", nargs="?", default=".")
+    p_benchmark.add_argument("--sample-size", type=int, default=25, help="Number of files for compression benchmark")
+    p_benchmark.add_argument("--min-tokens", type=int, default=200, help="Prefer files with at least this many tokens")
+    p_benchmark.add_argument("--top-k", type=int, default=5, help="Top-k files for retrieval benchmarks")
+    p_benchmark.add_argument("--max-tokens", type=int, default=4000, help="Max tokens in C3 retrieval context")
+    p_benchmark.add_argument("--json", action="store_true", help="Emit JSON report to stdout")
+    p_benchmark.add_argument("--output", help="Write JSON report to this path (relative to project)")
+    p_benchmark.add_argument("--html-output", help="Write HTML report to this path (relative to project)")
+    p_benchmark.add_argument("--no-html", action="store_true", help="Do not generate the HTML benchmark report")
+    p_benchmark.add_argument("--system-name", help="System/AI identifier for this benchmark run (e.g. codex, claude, cursor)")
+    p_benchmark.add_argument("--system-label", help="Display label for the benchmark system (e.g. OpenAI Codex)")
+    p_benchmark.add_argument("--system-version", help="Optional system version/build label for the benchmark output")
+
+    p_session_bench = subparsers.add_parser("session-benchmark", help="Run real-world session workflow benchmark")
+    p_session_bench.add_argument("project_path", nargs="?", default=".")
+    p_session_bench.add_argument("--sample-size", type=int, default=15, help="Number of files to sample")
+    p_session_bench.add_argument("--min-tokens", type=int, default=200, help="Prefer files with at least this many tokens")
+    p_session_bench.add_argument("--json", action="store_true", help="Emit JSON report to stdout")
+    p_session_bench.add_argument("--output", help="Write JSON report to this path")
+    p_session_bench.add_argument("--html-output", help="Write HTML report to this path")
+
+    subparsers.add_parser("optimize", help="Show optimization suggestions")
+
+    p_pipe = subparsers.add_parser("pipe", help="All-in-one pipeline for Claude")
+    p_pipe.add_argument("query", nargs="+")
+    p_pipe.add_argument("--top-k", type=int, default=5)
+    p_pipe.add_argument("--max-tokens", type=int, default=4000)
+
+    p_install_mcp = subparsers.add_parser("install-mcp", help="Generate MCP config for your IDE")
+    p_install_mcp.add_argument("targets", nargs="*", help="Optional project path and/or IDE shorthand (for example: `claude` or `. codex`)")
+    p_install_mcp.add_argument("--ide", default="auto", type=parse_cli_ide_arg, metavar="{auto,claude,vscode,cursor,codex,gemini,antigravity}", help="Target IDE (default: auto-detect)")
+    p_install_mcp.add_argument("--mcp-mode", choices=["direct", "proxy"], default="direct", help="MCP entrypoint mode (default: direct)")
+    p_install_mcp.add_argument("--permissions", choices=["read-only", "c3-strict", "standard", "permissive"], default=None, help="Apply Claude Code permission tier (Claude Code only)")
+    p_install_mcp.add_argument("--include-mcp-wildcard", action="store_true", help="Add mcp__* wildcard so non-C3 MCP servers don't prompt per-call")
+
+    p_mcp_install = subparsers.add_parser("mcp-install", help="Alias for install-mcp")
+    p_mcp_install.add_argument("targets", nargs="*", help="Optional project path and/or IDE shorthand")
+    p_mcp_install.add_argument("--ide", default="auto", type=parse_cli_ide_arg, metavar="{auto,claude,vscode,cursor,codex,gemini,antigravity}", help="Target IDE (default: auto-detect)")
+    p_mcp_install.add_argument("--mcp-mode", choices=["direct", "proxy"], default="direct", help="MCP entrypoint mode (default: direct)")
+    p_mcp_install.add_argument("--permissions", choices=["read-only", "c3-strict", "standard", "permissive"], default=None, help="Apply Claude Code permission tier (Claude Code only)")
+    p_mcp_install.add_argument("--include-mcp-wildcard", action="store_true", help="Add mcp__* wildcard so non-C3 MCP servers don't prompt per-call")
+
+    p_mcp_remove = subparsers.add_parser("mcp-remove", help="Remove an MCP server from your IDE config")
+    p_mcp_remove.add_argument("name", help="Name of the MCP server to remove (e.g. 'c3')")
+    p_mcp_remove.add_argument("project_path", nargs="?", default=".", help="Project path to resolve IDE and config")
+    p_mcp_remove.add_argument("--ide", default="auto", type=parse_cli_ide_arg, help="Target IDE (default: auto-detect)")
+
+    p_ui = subparsers.add_parser("ui", help="Launch the web dashboard")
+    p_ui.add_argument("project_path", nargs="?", default=".")
+    p_ui.add_argument("--port", type=int, default=3333)
+    p_ui.add_argument("--no-browser", action="store_true")
+    p_ui.add_argument("--silent", action="store_true", help="Hide API request logs in terminal")
+    p_ui.add_argument("--nano", action="store_true", help="Launch minimal mission-control UI")
+
+    p_hub = subparsers.add_parser("hub", help="Launch the Project Hub web dashboard")
+    p_hub.add_argument("--port", type=int, default=3330, help="Port to listen on (default: 3330)")
+    p_hub.add_argument("--no-browser", action="store_true", help="Don't open browser automatically")
+    p_hub.add_argument("--silent", action="store_true", help="Disable browser auto-open and suppress request logs")
+    p_hub.add_argument("--extra-silent", action="store_true", help="Also suppress hub startup banner output")
+    p_hub.add_argument("--install", action="store_true", help="Register as a login/startup service")
+    p_hub.add_argument("--uninstall", action="store_true", help="Remove startup service registration")
+    p_hub.add_argument("--status", action="store_true", help="Show startup service status")
+
+    p_projects = subparsers.add_parser("projects", help="Manage registered C3 projects (CLI)")
+    p_projects.add_argument(
+        "projects_cmd",
+        nargs="?",
+        choices=["list", "add", "remove", "start", "sessions"],
+        default="list",
+        help="Sub-command (default: list)",
+    )
+    p_projects.add_argument(
+        "project_path",
+        nargs="?",
+        default=None,
+        help="Project path (required for add, remove, start)",
+    )
+    p_projects.add_argument("--name", default=None, help="Display name (for add)")
+
+    p_perms = subparsers.add_parser("permissions",
+        help="Manage Claude Code permissions — show | preview <tier> | diff | clean | <tier>")
+    p_perms.add_argument("tier", nargs="?", default="show",
+        help="Action (show/preview/diff/clean) or tier (read-only, c3-strict, standard, permissive). Aliases: strict, unrestricted, readonly.")
+    p_perms.add_argument("target", nargs="?", default=None,
+        help="Target tier for 'preview' or 'diff' subcommands")
+    p_perms.add_argument("--include-mcp-wildcard", action="store_true",
+        help="Include mcp__* wildcard so non-C3 MCP servers don't prompt per-call")
+    p_perms.add_argument("--project-path", default=".",
+        help="Project path (default: current directory)")
+
+    p_e2e = subparsers.add_parser("benchmark-e2e", help="Run end-to-end AI session benchmark (C3 vs baseline)")
+    p_e2e.add_argument("project_path", nargs="?", default=".", help="Project path to benchmark")
+
+    p_e2e_common = p_e2e.add_argument_group("common options")
+    p_e2e_common.add_argument("--providers", default=None, help="Comma-separated: claude,gemini,codex (default: auto-detect)")
+    p_e2e_common.add_argument("--models", default=None, help="Model overrides: claude=sonnet,gemini=gemini-2.5-flash,codex=o3")
+    p_e2e_common.add_argument("--tasks", default="all", help="Task filter: all (default), or comma-separated categories")
+    p_e2e_common.add_argument("--max-tasks", type=int, default=1, help="Max tasks per category (default: 1)")
+    p_e2e_common.add_argument("--timeout", type=int, default=120, help="Per-task timeout in seconds (default: 120)")
+    p_e2e_common.add_argument("--dry-run", action="store_true", help="Show tasks and providers without running")
+    p_e2e_common.add_argument("--verbose", action="store_true", help="Print each result as it completes")
+    p_e2e_common.add_argument("--json", action="store_true", help="Emit JSON report to stdout")
+    p_e2e_common.add_argument("--output", help="Write JSON report to this path")
+    p_e2e_common.add_argument("--html-output", help="Write HTML report to this path")
+
+    p_e2e_adv = p_e2e.add_argument_group("advanced options")
+    p_e2e_adv.add_argument("--no-parallel", action="store_true", help="Run providers sequentially instead of in parallel")
+    p_e2e_adv.add_argument("--judge", default=None, help="Enable AI-as-judge scoring with this CLI (e.g. claude, gemini)")
+    p_e2e_adv.add_argument("--judge-model", default=None, help="Model override for the judge CLI")
+    p_e2e_adv.add_argument("--task-workers", type=int, default=1,
+                           help="Run N tasks concurrently (default: 1). Higher values are faster but may hit rate limits.")
+    p_e2e_adv.add_argument("--no-cache", action="store_true",
+                           help="Ignore cached results and re-run all tasks (cache is enabled by default, TTL=24h)")
+    p_e2e_adv.add_argument("--permission-mode", default="bypassPermissions",
+                           help="Permission mode for AI CLI (default: bypassPermissions). Use 'plan' for read-only mode.")
+    p_e2e_adv.add_argument("--delegate-benchmark", action="store_true",
+                           help="Run delegate backend comparison (Ollama vs Codex) instead of normal e2e benchmark")
+    p_e2e_adv.add_argument("--delegate-types", default=None,
+                           help="Comma-separated delegate task types to benchmark (default: all). E.g. review,diagnose")
+
+    p_terse = subparsers.add_parser("terse", help="Manage the terse-advisor nudge state")
+    p_terse.add_argument(
+        "action",
+        nargs="?",
+        default="status",
+        choices=["dismiss", "later", "reset", "status"],
+        help="dismiss=silence forever, later=snooze 24h, reset=clear state, status=show state (default)",
+    )
+
+    # Unified `c3 bench <tier>` — wraps benchmark / session-benchmark / benchmark-e2e
+    # Legacy commands above kept for backward compatibility.
+    p_bench = subparsers.add_parser(
+        "bench",
+        help="Run C3 benchmarks (unified: quick | session | e2e | delegate | all | dashboard)",
+    )
+    bench_sub = p_bench.add_subparsers(dest="bench_tier")
+
+    p_bq = bench_sub.add_parser("quick", help="Local synthetic benchmark (no AI calls) [Synthetic]")
+    p_bq.add_argument("project_path", nargs="?", default=".")
+    p_bq.add_argument("--sample-size", type=int, default=25)
+    p_bq.add_argument("--min-tokens", type=int, default=200)
+    p_bq.add_argument("--top-k", type=int, default=5)
+    p_bq.add_argument("--max-tokens", type=int, default=4000)
+    p_bq.add_argument("--json", action="store_true")
+    p_bq.add_argument("--output")
+    p_bq.add_argument("--html-output")
+    p_bq.add_argument("--no-html", action="store_true")
+    p_bq.add_argument("--system-name")
+    p_bq.add_argument("--system-label")
+    p_bq.add_argument("--system-version")
+
+    p_bs = bench_sub.add_parser("session", help="Workflow scenario benchmark (6 scenarios) [Synthetic]")
+    p_bs.add_argument("project_path", nargs="?", default=".")
+    p_bs.add_argument("--sample-size", type=int, default=15)
+    p_bs.add_argument("--min-tokens", type=int, default=200)
+    p_bs.add_argument("--json", action="store_true")
+    p_bs.add_argument("--output")
+    p_bs.add_argument("--html-output")
+
+    p_be = bench_sub.add_parser("e2e", help="End-to-end AI benchmark (real claude/gemini/codex) [Live AI]")
+    p_be.add_argument("project_path", nargs="?", default=".")
+    p_be.add_argument("--providers", default=None, help="Comma-separated: claude,gemini,codex (default: auto-detect)")
+    p_be.add_argument("--models", default=None, help="Model overrides: claude=sonnet,gemini=gemini-2.5-flash,codex=o3")
+    p_be.add_argument("--tasks", default="all", help="Task filter: all (default), or comma-separated categories")
+    p_be.add_argument("--max-tasks", type=int, default=1)
+    p_be.add_argument("--timeout", type=int, default=120)
+    p_be.add_argument("--dry-run", action="store_true")
+    p_be.add_argument("--verbose", action="store_true")
+    p_be.add_argument("--json", action="store_true")
+    p_be.add_argument("--output")
+    p_be.add_argument("--html-output")
+    p_be.add_argument("--no-parallel", action="store_true")
+    p_be.add_argument("--judge", default=None)
+    p_be.add_argument("--judge-model", default=None)
+    p_be.add_argument("--task-workers", type=int, default=1)
+    p_be.add_argument("--no-cache", action="store_true")
+    p_be.add_argument("--permission-mode", default="bypassPermissions")
+
+    p_bd = bench_sub.add_parser("delegate", help="Delegate backend comparison (Ollama vs Codex) [Live AI]")
+    p_bd.add_argument("project_path", nargs="?", default=".")
+    p_bd.add_argument("--delegate-types", default=None, help="Comma-separated delegate task types (default: all)")
+    p_bd.add_argument("--verbose", action="store_true")
+    p_bd.add_argument("--json", action="store_true")
+    p_bd.add_argument("--output")
+
+    p_ba = bench_sub.add_parser("all", help="Run full benchmark suite (quick + session + e2e + dashboard)")
+    p_ba.add_argument("project_path", nargs="?", default=".")
+    p_ba.add_argument("--skip-e2e", action="store_true", help="Skip the e2e benchmark (slow; requires AI CLIs)")
+    p_ba.add_argument("--sample-size", type=int, default=15)
+    p_ba.add_argument("--min-tokens", type=int, default=200)
+    p_ba.add_argument("--max-tasks", type=int, default=1)
+    p_ba.add_argument("--timeout", type=int, default=120)
+    p_ba.add_argument("--providers", default=None)
+
+    p_bdash = bench_sub.add_parser("dashboard", help="Regenerate unified HTML dashboard")
+    p_bdash.add_argument("project_path", nargs="?", default=".")
+    p_bdash.add_argument("--open", action="store_true", help="Open in browser after generating")
+
+    p_bext = bench_sub.add_parser("external",
+        help="External benchmark suites (Aider Polyglot / SWE-bench) [External]")
+    p_bext.add_argument("project_path", nargs="?", default=".")
+    p_bext.add_argument("--suite", choices=["aider-polyglot", "swe-bench-lite"],
+        default="aider-polyglot",
+        help="External benchmark suite (default: aider-polyglot)")
+    p_bext.add_argument("--path", default=None,
+        help="Path to the benchmark corpus (aider-polyglot: repo dir; swe-bench-lite: unused)")
+    p_bext.add_argument("--dataset", default=None,
+        help="swe-bench-lite: path to swe_bench_lite.jsonl or HF dataset id "
+             "(default: princeton-nlp/SWE-bench_Lite)")
+    p_bext.add_argument("--agent", choices=["aider"], default="aider",
+        help="swe-bench-lite: agent to generate patches (default: aider)")
+    p_bext.add_argument("--languages", default="python",
+        help="aider-polyglot: python,javascript,go,rust,java,cpp (default: python)")
+    p_bext.add_argument("--max-exercises", type=int, default=5,
+        help="aider-polyglot: max exercises per language (default: 5)")
+    p_bext.add_argument("--max-tasks", type=int, default=5,
+        help="swe-bench-lite: max instances to run (default: 5)")
+    p_bext.add_argument("--model", default="gpt-4o-mini",
+        help="Model ID to pass to the agent (default: gpt-4o-mini)")
+    p_bext.add_argument("--timeout", type=int, default=300,
+        help="Per-task agent timeout in seconds (default: 300)")
+    p_bext.add_argument("--docker-eval", action="store_true",
+        help="swe-bench-lite: run the official Docker-based evaluation after patch generation")
+    p_bext.add_argument("--verbose", action="store_true",
+        help="Print each task result as it completes")
+    p_bext.add_argument("--dry-run", action="store_true",
+        help="Validate setup (CLIs, datasets) without running the agent")
+
+    return parser