code-context-control 2.129.2__py3-none-any.whl → 2.136.0__py3-none-any.whl

cli/_hook_utils.py

@@ -392,20 +392,28 @@ def record_unlocked_files(
 #            hookSpecificOutput.hookEventName is REQUIRED. Unknown keys are a
 #            hard deserialization error, not a warning, so emitting the Claude
 #            shape makes Codex discard the whole hook response.
+#   grok   — Grok Build: native tool names and tagged results on the way in
+#            (core/grok_payload.translate); context only under
+#            hookSpecificOutput, and Stop context would keep the agent working.
 HOST_CLAUDE = "claude"
 HOST_GEMINI = "gemini"
 HOST_CODEX = "codex"
+HOST_GROK = "grok"
 
 
 def detect_host(data: dict, explicit_host: str | None = None) -> str:
     """Use the hook's explicit host or wire identity, never its parent's env."""
     named = explicit_host or (data.get("_c3_host") if isinstance(data, dict) else None)
     aliases = {"claude-code": HOST_CLAUDE, "claude": HOST_CLAUDE,
-               "codex": HOST_CODEX, "gemini": HOST_GEMINI, "antigravity": HOST_GEMINI}
+               "codex": HOST_CODEX, "gemini": HOST_GEMINI, "antigravity": HOST_GEMINI,
+               "grok": HOST_GROK, "grok-build": HOST_GROK}
     if named in aliases:
         return aliases[named]
     if not isinstance(data, dict):
         return HOST_CLAUDE
+    from core.grok_payload import is_grok_payload
+    if is_grok_payload(data):
+        return HOST_GROK
     if data.get("turn_id"):
         return HOST_CODEX
     response = data.get("tool_response")

cli/c3.py

@@ -91,7 +91,7 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.129.2"
+__version__ = "2.136.0"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):
@@ -316,7 +316,7 @@ _BASH_STANDARD = _BASH_READONLY + [
     "Bash(pip:*)", "Bash(pip3:*)", "Bash(npm:*)", "Bash(node:*)",
     "Bash(cargo:*)", "Bash(go:*)",
     # AI CLIs
-    "Bash(claude:*)", "Bash(codex:*)", "Bash(gemini:*)",
+    "Bash(claude:*)", "Bash(codex:*)", "Bash(gemini:*)", "Bash(grok:*)",
     # Utilities
     "Bash(timeout:*)", "Bash(time:*)", "Bash(curl:*)", "Bash(gh:*)",
     "Bash(for:*)", "Bash(do:*)", "Bash(done:*)",
@@ -755,6 +755,7 @@ def _select_init_ide(default_ide: str) -> str:
         "Cursor       — .cursor/mcp.json",
         "Codex        — .codex/config.toml + AGENTS.md",
         "Antigravity  — ~/.gemini/antigravity/mcp_config.json + AGENTS.md",
+        "Grok Build   — .grok/config.toml + .grok/hooks + AGENTS.md",
     ]
     selected = _prompt_choice("Step 1/3 — Choose IDE profile", choices)
     mapping = {
@@ -764,6 +765,7 @@ def _select_init_ide(default_ide: str) -> str:
         choices[3]: "cursor",
         choices[4]: "codex",
         choices[5]: "antigravity",
+        choices[6]: "grok",
     }
     chosen = mapping.get(selected or "", normalize_ide_name(default_ide) if default_ide != "auto" else "auto")
     print(f"  IDE profile: {chosen}")
@@ -1034,7 +1036,7 @@ def _parse_cli_ide_arg(value: str) -> str:
     normalized = normalize_ide_name(raw)
     if normalized not in PROFILES:
         raise argparse.ArgumentTypeError(
-            "Unsupported IDE. Use one of: auto, claude, vscode, cursor, codex, antigravity."
+            "Unsupported IDE. Use one of: auto, claude, vscode, cursor, codex, antigravity, grok."
         )
     return normalized
 
@@ -1569,6 +1571,51 @@ def cmd_shell_eval(args):
         sys.exit(1)
 
 
+def cmd_delegate_eval(args):
+    """Grade c3_delegate answers per target and name the cheapest passing tier.
+
+    Live by default (every case goes to the real backend and costs what that
+    backend costs); --replay grades a recorded run instead. Exit status 1 when
+    a --floor is given and a target's core pass rate falls under it. See
+    docs/delegate-eval.md.
+    """
+    from services.bench import delegate_eval as de
+
+    targets = [t.strip() for t in (args.targets or "").split(",") if t.strip()]
+    case_ids = [c.strip() for c in (args.cases or "").split(",") if c.strip()]
+    overrides = json.loads(args.config) if getattr(args, "config", None) else None
+    if overrides is not None and not isinstance(overrides, dict):
+        raise RuntimeError("--config must be a JSON object")
+
+    def progress(res):
+        if not args.json:
+            cost = "" if res.cost_usd is None else f" ${res.cost_usd:.4f}"
+            print(f"  {res.target:<16} {res.id:<28} {res.status}{cost} "
+                  f"{res.wall_ms / 1000:.1f}s", flush=True)
+
+    try:
+        report = de.run_suite(
+            args.suite, targets=targets or None, replay=args.replay, record=args.record,
+            case_ids=case_ids or None, floor=args.floor if args.floor is not None else de.DEFAULT_FLOOR,
+            allow_write_delegation=args.allow_write_delegation, delegate_overrides=overrides,
+            progress=progress)
+    except (FileNotFoundError, ValueError) as e:
+        raise RuntimeError(str(e))
+
+    if args.json:
+        print(json.dumps(report.to_dict(), indent=2))
+    else:
+        print(report.render())
+        if args.record and report.mode == "live":
+            print(f"recorded: {args.record}")
+    if args.floor is not None:
+        under = [t for t, a in report.aggregates.items()
+                 if a["pass_rate_core"] is None or a["pass_rate_core"] < args.floor]
+        if under:
+            print(f"under floor {args.floor}: {', '.join(under)}", file=sys.stderr)
+            sys.exit(1)
+
+
 def cmd_map_eval(args):
     """Run the file-map gold suite and compare it to its baseline.
 
@@ -4333,9 +4380,9 @@ _C3_HOOKLESS_WORKFLOW = _adapt_workflow_for_ide(
 
 _COPILOT_INSTRUCTIONS_CONTENT = _VSCODE_SESSION_INIT + "\n\n" + _C3_HOOKLESS_WORKFLOW
 
-from services.codex_integration import CODEX_WORKFLOW
+from services.agents_workflow import AGENTS_MD_WORKFLOW
 
-_AGENTS_MD_CONTENT = CODEX_WORKFLOW
+_AGENTS_MD_CONTENT = AGENTS_MD_WORKFLOW
 
 _TERSE_SKILL_CONTENT = """\
 # /terse — Terse Output Mode
@@ -4544,7 +4591,7 @@ def _ensure_instruction_workflow(instructions_path: Path, template: str,
 
 def _ensure_codex_agents_workflow(agents_md_path: Path,
                                   project_path: str = "") -> str:
-    """Ensure AGENTS.md contains the mandatory C3 workflow for Codex sessions."""
+    """Ensure AGENTS.md contains the mandatory C3 workflow (Codex and Grok Build read it)."""
     from services.claude_md import write_c3_instruction_doc
     existing = agents_md_path.read_text(encoding="utf-8") if agents_md_path.exists() else None
     rendered = write_c3_instruction_doc(agents_md_path, _AGENTS_MD_CONTENT, project_path or None)
@@ -4888,8 +4935,15 @@ def _uninstall_mcp_all(project_path: str, include_global: bool = True):
                 except Exception as e:
                     print(f"  Warning: Could not update {mcp_config_path}: {e}")
 
+        # Grok Build: C3 owns the whole .grok/hooks/c3.json, so it is deleted
+        # rather than stripped (its Windows commands are encoded and would not
+        # match the settings scanner anyway).
+        if ide_name == "grok":
+            from services.grok_integration import remove_hooks as remove_grok_hooks
+            if remove_grok_hooks(target):
+                print(f"  Deleted {target / profile.settings_path}")
         # Per-host hooks and settings; remove only C3-owned handlers.
-        if profile.supports_hooks and profile.settings_path:
+        elif profile.supports_hooks and profile.settings_path:
             settings_path = target / profile.settings_path
             if settings_path.exists():
                 try:
@@ -4970,7 +5024,7 @@ def _uninstall_mcp_all(project_path: str, include_global: bool = True):
             print(f"  Warning: Could not update {legacy_cfg}: {e}")
 
     # Final pass: clean up empty IDE directories (.claude, .codex, .gemini, .vscode, .github)
-    dirs_to_check = [".claude", ".codex", ".gemini", ".vscode", ".github"]
+    dirs_to_check = [".claude", ".codex", ".grok", ".gemini", ".vscode", ".github"]
     for dname in dirs_to_check:
         dpath = target / dname
         if dpath.exists() and dpath.is_dir():
@@ -5011,7 +5065,7 @@ back to native tools as the task progresses.
 - **Filter**: `c3_filter(text=...)` — for terminal output >10 lines
 - **Shell**: `c3_shell(cmd, timeout=60)` — structured shell exec (tests/git/build). Auto-filters output, logs git mutations to the ledger. Native Bash for interactive/TTY only
 - **Memory**: `c3_memory(action='recall')` — full recall. `index` + `fetch` for token-efficient two-step retrieval
-- **Delegate**: `c3_delegate(task, backend='ollama|codex|gemini|claude|auto')` — offload to other models
+- **Delegate**: `c3_delegate(task, task_type, context|file_path)` — your own provider one tier down (default `backend='host'`, `tier='small'`; Claude Code: Haiku) for bounded answers: summarize a diff/log, explain a function, triage a traceback. `scout=true` lets it look files up itself. Multi-step work: the `c3-scout` (haiku) / `c3-worker` (sonnet) subagents
 - **Local CI** (v2.79.0+): `c3_ci(action='inspect|run|rerun|failures')` — run THIS repo's real `.github/workflows` here instead of pushing for feedback. `run` executes in `needs` order; `failures` gives {file,line,message}; `rerun` retries only what failed. Only `FULL_CI_PASS` means safe to push — `PARTIAL_PASS` means something did not run (other OS, unsupported action, or your selection).
 - **Bitbucket** (v2.30.0+, when `c3 bitbucket login` has run): `c3_bitbucket(action='list_prs|get_pr|merge_pr|...')` — self-hosted Bitbucket Data Center / Server. Token in OS keyring; mutating actions auto-log to the edit ledger.
 - **Cross-project** (v2.31.0+): `c3_project(action='list|scan|search|read|edit|...', project='<name|path>')` — discover and operate on OTHER c3-installed projects. Reads run freely; writes (edit/shell/memory) need `allow_write=true`.
@@ -5466,6 +5520,12 @@ def cmd_install_mcp(args):
                 toml_entries["startup_timeout_sec"] = 30
                 toml_entries["tool_timeout_sec"] = 60
                 toml_entries["args"] += ["--host", "codex"]
+            elif profile.name == "grok":
+                # Grok's default startup timeout is 30s; a cold C3 index build can
+                # exceed it. Its tool timeout already defaults to 6000s.
+                toml_entries["enabled"] = True
+                toml_entries["startup_timeout_sec"] = 60
+                toml_entries["args"] += ["--host", "grok"]
             _upsert_toml_section(
                 mcp_config_path,
                 f"{profile.config_key}.c3",
@@ -5517,6 +5577,13 @@ def cmd_install_mcp(args):
         from services.codex_integration import install_hooks
         hook_state = install_hooks(target, sys.executable, cli_dir / "hook_dispatch.py")
         print(f"Codex hooks installed; active: {hook_state['active']}. {hook_state['activation']}")
+    if profile.name == "grok":
+        from services.grok_integration import install_hooks as install_grok_hooks
+        grok_hooks = install_grok_hooks(target, sys.executable, cli_dir / "hook_dispatch.py")
+        from services.artifact_defs import note_pending_write
+        note_pending_write(target, profile.settings_path, "install_mcp")
+        print(f"Wrote {target / profile.settings_path}")
+        print(f"Grok Build: {grok_hooks['activation']}")
     if profile.name == "claude-code" and profile.supports_hooks and profile.settings_path:
         settings_dir = target / Path(profile.settings_path).parent
         settings_dir.mkdir(parents=True, exist_ok=True)
@@ -5812,8 +5879,8 @@ def cmd_install_mcp(args):
         print(f"Wrote {vscode_settings_path}")
         print("  Copilot: C3 instructions linked for code gen, review, and test generation")
 
-    # ── Codex AGENTS.md enforcement file ──────────────────────
-    if profile.name == "codex":
+    # ── Codex / Grok Build AGENTS.md enforcement file ────────────
+    if profile.name in ("codex", "grok"):
         agents_md_path = target / "AGENTS.md"
         agents_state = _ensure_codex_agents_workflow(agents_md_path,
                                                      str(target))
@@ -5824,6 +5891,7 @@ def cmd_install_mcp(args):
         else:
             print(f"Kept  {agents_md_path}  (C3 workflow present)")
 
+    if profile.name == "codex":
         # Warn about a common conflict: global Codex config disables c3.
         global_codex_cfg = Path(os.environ.get("CODEX_HOME") or Path.home() / ".codex") / "config.toml"
         global_enabled = _toml_section_bool_value(global_codex_cfg, "mcp_servers.c3", "enabled")
@@ -5855,6 +5923,20 @@ def cmd_install_mcp(args):
         except Exception as e:
             print(f"Warning: Could not install /terse skill: {e}")
 
+    # ── Downshift subagents (c3-scout on haiku, c3-worker on sonnet) ──
+    if profile.name == "claude-code" and not getattr(args, "no_agents", False):
+        try:
+            from services.delegate_agents import install_delegate_agents
+            for path, action in install_delegate_agents(target):
+                if action == "skipped":
+                    print(f"Kept  {path}  (no C3 marker: yours, left untouched)")
+                elif action == "kept":
+                    print(f"Kept  {path}  (subagent up to date)")
+                else:
+                    print(f"{action.capitalize()} {path}  (subagent)")
+        except Exception as e:
+            print(f"Warning: Could not install c3-scout/c3-worker subagents: {e}")
+
     print(f"IDE: {profile.display_name}")
     print(f"MCP Mode: {mcp_mode}")
     print(f"Server: {server_script}")
@@ -9303,7 +9385,10 @@ def _launch_tui() -> None:
 
 
 def cmd_doctor(args):
-    from services.codex_integration import diagnose
+    if getattr(args, "ide", "codex") == "grok":
+        from services.grok_integration import diagnose
+    else:
+        from services.codex_integration import diagnose
     print(json.dumps(diagnose(Path(args.project_path).resolve()), indent=2))
 
 
@@ -9354,6 +9439,7 @@ def main():
         "search-eval": cmd_search_eval,
         "shell-eval": cmd_shell_eval,
         "map-eval": cmd_map_eval,
+        "delegate-eval": cmd_delegate_eval,
         "benchmark": cmd_benchmark,
         "session-benchmark": cmd_session_benchmark,
         "benchmark-e2e": cmd_benchmark_e2e,

cli/commands/parser.py

@@ -17,15 +17,15 @@ def build_parser(version: str, parse_cli_ide_arg):
     )
     subparsers = parser.add_subparsers(dest="command")
 
-    p_doctor = subparsers.add_parser("doctor", help="Inspect native Codex integration without a model call")
+    p_doctor = subparsers.add_parser("doctor", help="Inspect native Codex or Grok Build integration without a model call")
     p_doctor.add_argument("project_path", nargs="?", default=".")
-    p_doctor.add_argument("--ide", choices=["codex"], default="codex")
+    p_doctor.add_argument("--ide", choices=["codex", "grok"], default="codex")
 
     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,antigravity}", help="Target IDE for MCP config (default: auto-detect)")
+    p_init.add_argument("--ide", default="auto", type=parse_cli_ide_arg, metavar="{auto,claude,vscode,cursor,codex,antigravity,grok}", 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("--no-embed", action="store_true", help="Skip building the semantic embedding index during init")
@@ -89,6 +89,26 @@ def build_parser(version: str, parse_cli_ide_arg):
                             help='With --update-baseline: JSON object of metric ceilings, e.g. \'{"tokens_p95": 4000}\'')
     p_map_eval.add_argument("--json", action="store_true", help="Emit the full report as JSON")
 
+    p_delegate_eval = subparsers.add_parser(
+        "delegate-eval", help="Grade c3_delegate answers per backend/tier (docs/delegate-eval.md)")
+    p_delegate_eval.add_argument("--suite", default="gold",
+                                 help="'gold' (bundled) or a .jsonl path")
+    p_delegate_eval.add_argument("--targets", default="",
+                                 help="Comma-separated backend[:tier] list, e.g. 'claude:small,claude:medium'")
+    p_delegate_eval.add_argument("--cases", default="", help="Comma-separated case ids (default: all)")
+    p_delegate_eval.add_argument("--replay", default=None,
+                                 help="Grade a recorded run instead of calling backends")
+    p_delegate_eval.add_argument("--record", default=None, help="Write the live answers to this JSON file")
+    p_delegate_eval.add_argument("--floor", type=float, default=None,
+                                 help="Core pass-rate floor; exit 1 when a target falls under it")
+    p_delegate_eval.add_argument("--allow-write-delegation", action="store_true",
+                                 help="Pass allow_write_delegation=true (needed for write-capable backends "
+                                      "when Access Guard rules exist)")
+    p_delegate_eval.add_argument("--config", default=None,
+                                 help='JSON object merged over the delegate config for this run, '
+                                      'e.g. \'{"allow_model_fallback": false}\'')
+    p_delegate_eval.add_argument("--json", action="store_true", help="Emit the full report as JSON")
+
     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", "smart", "structure", "outline"], default="map",
@@ -153,19 +173,21 @@ def build_parser(version: str, parse_cli_ide_arg):
 
     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,antigravity}", help="Target IDE (default: auto-detect)")
+    p_install_mcp.add_argument("--ide", default="auto", type=parse_cli_ide_arg, metavar="{auto,claude,vscode,cursor,codex,antigravity,grok}", 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("--global-fallback", action="store_true", help="Also install the machine-wide Codex fallback")
     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_install_mcp.add_argument("--no-agents", action="store_true", help="Do not write the c3-scout/c3-worker subagents to .claude/agents (Claude Code only)")
 
     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,antigravity}", help="Target IDE (default: auto-detect)")
+    p_mcp_install.add_argument("--ide", default="auto", type=parse_cli_ide_arg, metavar="{auto,claude,vscode,cursor,codex,antigravity,grok}", 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("--global-fallback", action="store_true", help="Also install the machine-wide Codex fallback")
     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_install.add_argument("--no-agents", action="store_true", help="Do not write the c3-scout/c3-worker subagents to .claude/agents (Claude Code only)")
 
     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')")

cli/docs.html

@@ -789,7 +789,7 @@
       <h1 id="overview">Code <span>Companion</span></h1>
       <div class="subtitle">
         A local code intelligence system that reduces AI coding assistant token usage through compression,
-        indexing, and persistent memory. Works with <strong>Claude Code</strong>, <strong>Google Antigravity</strong>,
+        indexing, and persistent memory. Works with <strong>Claude Code</strong>, <strong>OpenAI Codex</strong>, <strong>Grok Build</strong>, <strong>Google Antigravity</strong>,
         <strong>VS Code Copilot</strong>, and <strong>Cursor</strong> via MCP. Available as an <strong>MCP
           server</strong>,
         <strong>CLI</strong>, and <strong>web dashboard</strong>.
@@ -958,7 +958,9 @@ c3 init /path/to/your/project</code></pre>
               <code>.github/copilot-instructions.md</code> (hard enforcement language) and
               <code>.vscode/settings.json</code> (Copilot instruction links). For Codex, generates
               <code>AGENTS.md</code> with the C3 session protocol. Use <code>--ide vscode</code>,
-              <code>--ide cursor</code>, or <code>--ide codex</code> to override IDE detection.
+              <code>--ide cursor</code>, <code>--ide codex</code>, or <code>--ide grok</code> to override IDE detection.
+              For Grok Build, writes <code>.grok/config.toml</code>, <code>.grok/hooks/c3.json</code> and
+              <code>AGENTS.md</code>.
             </div>
           </div>
         </div>
@@ -968,7 +970,9 @@ c3 init /path/to/your/project</code></pre>
             <div class="step-desc">Open your IDE in the project. For Claude Code, run <code>/mcp</code> to verify C3
               tools appear. For Google Antigravity, the MCP tools will be loaded based on your config.
               For VS Code, check MCP tools in the Copilot agent panel. For Codex, the <code>.codex/config.toml</code> is
-              picked up automatically on next session start.</div>
+              picked up automatically on next session start. For Grok Build, launch <code>grok --trust</code> once in
+              the project (Grok ignores project MCP servers, hooks and <code>AGENTS.md</code> in an untrusted folder),
+              then run <code>c3 doctor --ide grok</code>.</div>
           </div>
         </div>
       </div>
@@ -1016,8 +1020,16 @@ c3 init /path/to/your/project</code></pre>
           <td><strong>OpenAI Codex</strong></td>
           <td><code>.codex/config.toml</code></td>
           <td><code>AGENTS.md</code></td>
-          <td>—</td>
-          <td>No</td>
+          <td><code>.codex/hooks.json</code></td>
+          <td>Yes</td>
+          <td>Yes</td>
+        </tr>
+        <tr>
+          <td><strong>Grok Build</strong></td>
+          <td><code>.grok/config.toml</code></td>
+          <td><code>AGENTS.md</code></td>
+          <td><code>.grok/hooks/c3.json</code></td>
+          <td>Yes (after <code>grok --trust</code>)</td>
           <td>No</td>
         </tr>
         <tr>
@@ -1050,11 +1062,13 @@ python cli/c3.py install-mcp /path/to/project --ide vscode
 python cli/c3.py install-mcp /path/to/project --ide cursor
 python cli/c3.py install-mcp /path/to/project --ide claude
 python cli/c3.py install-mcp /path/to/project --ide codex
+python cli/c3.py install-mcp /path/to/project --ide grok
 python cli/c3.py install-mcp /path/to/project --ide antigravity
 
 # IDE shorthand when already inside the project directory
 python cli/c3.py install-mcp claude
 python cli/c3.py install-mcp codex
+python cli/c3.py install-mcp grok
 python cli/c3.py install-mcp . antigravity</code></pre>
 
       <p><code>--git</code> runs a local-only <code>git init</code>. It does not create remotes or connect to GitHub,
@@ -1111,6 +1125,32 @@ python cli/c3.py install-mcp . antigravity</code></pre>
         </li>
       </ul>
 
+      <p><strong>Grok Build</strong> &mdash; <code>install-mcp --ide grok</code> (and <code>c3 init --ide grok</code>)
+        configure xAI's <code>grok</code> CLI. Everything is project-local:</p>
+      <ul>
+        <li><code>.grok/config.toml</code> &mdash; a <code>[mcp_servers.c3]</code> table (the same TOML shape as Codex)
+          with <code>--host grok</code> and <code>startup_timeout_sec = 60</code>. Other servers and keys are kept.
+          Auto-detected when <code>.grok/config.toml</code> or a <code>.grok/</code> directory exists.
+        </li>
+        <li><code>.grok/hooks/c3.json</code> &mdash; C3's handlers for PreToolUse, PostToolUse, SessionStart,
+          PreCompact, Stop and SessionEnd. C3 owns the whole file. On Windows each command is a
+          <code>powershell.exe -NoLogo -NoProfile -NonInteractive -EncodedCommand</code> line so it runs under
+          whichever shell Grok picks.
+        </li>
+        <li><code>AGENTS.md</code> &mdash; shared with Codex and Antigravity; only the C3 block is refreshed.</li>
+        <li><strong>Folder trust</strong> &mdash; Grok loads none of these until the folder is trusted. Launch
+          <code>grok --trust</code> once in the project (or run <code>/hooks-trust</code> inside Grok). C3 never
+          writes <code>~/.grok/trusted_folders.toml</code> or <code>~/.grok/config.toml</code>;
+          <code>c3 doctor --ide grok</code> reports the CLI version, hook install and trust state.
+        </li>
+        <li><strong>Limitations</strong> &mdash; C3 tools are reached through Grok's <code>search_tool</code> /
+          <code>use_tool</code> and appear as <code>c3__c3_search</code> and so on; PreToolUse hints reach the model
+          after the call runs (denies still block before it); there is no prompt-time memory recall; Stop-hook output
+          is never emitted; with both <code>AGENTS.md</code> and <code>CLAUDE.md</code> present, Grok loads the C3
+          block twice. Full guide: <code>docs/grok-native.md</code>.
+        </li>
+      </ul>
+
       <h3>Graceful Degradation</h3>
       <p>All core C3 tools (search, compress, file_map, memory, sessions) work identically in every IDE. Claude-specific
         features degrade gracefully:</p>
@@ -1118,7 +1158,7 @@ python cli/c3.py install-mcp . antigravity</code></pre>
         <li><strong>Transcript search</strong> — returns a helpful message suggesting <code>c3_memory(action='recall')</code> or
           <code>c3_memory(action='query')</code> as alternatives
         </li>
-        <li><strong>Hooks</strong> — only installed for Claude Code; VS Code, Cursor, and Codex use hard-language
+        <li><strong>Hooks</strong> — installed for Claude Code, Codex and Grok Build; VS Code and Cursor use hard-language
           workflow instructions in their instructions file instead</li>
         <li><strong>Instructions file</strong> — <code>c3_claudemd_generate</code> writes to the IDE-appropriate file
           (CLAUDE.md, copilot-instructions.md, .cursorrules, AGENTS.md, or GEMINI.md). All IDEs use MANDATORY/NEVER
@@ -2053,10 +2093,12 @@ c3 ui /path/to/your/project --silent         # Hide API request logs in terminal
           <div class="tab-name"><span class="badge badge-green">11</span> Settings</div>
           <div class="tab-desc">Project info (editable name, tech stack, description), quick actions (rebuild index,
             save instructions file), project data management (view sizes and item counts per .c3/ category, clear
-            actions), instructions file management, and MCP management: target IDE selector (Claude/Gemini/VS
-            Code/Cursor/Codex/Antigravity), custom MCP add form, installed MCP cards, and per-card trash removal.
+            actions), instructions file management, and MCP management: target IDE selector (Claude/VS
+            Code/Cursor/Codex/Grok Build/Antigravity), custom MCP add form, installed MCP cards, and per-card trash removal.
             Removing <code>c3</code> can also clean related IDE files/hooks. Includes IDE selector for C3 MCP
-            installation and optimization suggestions.</div>
+            installation and optimization suggestions. Delegate backend sections (Codex, Gemini, Grok Build) hold each
+            backend's enable switch, model, timeouts and auto-routed task types; the Grok Build section adds max turns
+            and the write-mode switch (<code>grok_allow_write</code>).</div>
         </div>
       </div>
 
@@ -2595,13 +2637,13 @@ c3 ui /path/to/your/project --silent         # Hide API request logs in terminal
       </p>
 
       <h3>Project Setup</h3>
-          <pre><code>c3 init &lt;project_path&gt; [--ide auto|claude|vscode|cursor|codex|gemini] [--force]
+          <pre><code>c3 init &lt;project_path&gt; [--ide auto|claude|vscode|cursor|codex|grok|antigravity] [--force]
                                            # Initialize C3: builds index, creates config, generates instructions file,
                                            # and automatically installs the MCP config for your IDE.
                                            # Re-running on an existing project now migrates config defaults and
                                            # refreshes instruction workflow files (Update / Clear / Reset options).
 c3 index [--max-files 500]                 # Rebuild the code index
-c3 install-mcp [project_path] [ide] [--ide auto|claude|vscode|cursor|codex|gemini]  # (Re-)generate MCP config manually
+c3 install-mcp [project_path] [ide] [--ide auto|claude|vscode|cursor|codex|grok|antigravity]  # (Re-)generate MCP config manually
 c3 ui [project_path] [--port 3333] [--nano] [--silent]   # Launch web dashboard (full or nano)</code></pre>
 
       <h3>Compression &amp; Search</h3>
@@ -2652,7 +2694,7 @@ c3 session load | claude --resume</code></pre>
 
       <div class="arch">
         <pre>
-  <strong>IDE</strong> (Claude Code / VS Code Copilot / Cursor / Codex / Gemini CLI)
+  <strong>IDE</strong> (Claude Code / VS Code Copilot / Cursor / Codex / Grok Build / Antigravity)
        | MCP Protocol (IDE-specific config file)
        v
   <strong>MCP Proxy</strong> ──── Dynamic tool filtering + context injection (optional, opt-in via MCP config)
@@ -2872,7 +2914,7 @@ c3 session load | claude --resume</code></pre>
     protocol.py          # Compression protocol encoder/decoder
   core/
     __init__.py          # Token counting utilities
-    ide.py               # IDE profile registry (Claude Code, VS Code, Cursor, Codex) + auto-detection
+    ide.py               # IDE profile registry (Claude Code, VS Code, Cursor, Codex, Antigravity, Grok Build) + auto-detection
     config.py            # Hybrid, proxy, delegate, and agent configuration loaders
   install.bat            # Windows installer
   install.sh             # Linux/macOS installer
@@ -3023,8 +3065,11 @@ c3 session load | claude --resume</code></pre>
         <ul>
           <li>Make sure the MCP config file exists (<code>.mcp.json</code> for Claude Code,
             <code>.vscode/mcp.json</code> for VS Code, <code>.cursor/mcp.json</code> for Cursor,
-            <code>.codex/config.toml</code> for Codex)
+            <code>.codex/config.toml</code> for Codex, <code>.grok/config.toml</code> for Grok Build)
           </li>
+          <li>For Grok Build, trust the folder first (<code>grok --trust</code> or <code>/hooks-trust</code>), then
+            check <code>c3 doctor --ide grok</code>, <code>grok mcp doctor c3 --json</code> and <code>grok inspect</code>.
+            Run <code>/hooks</code> inside Grok to see whether C3's hooks loaded.</li>
           <li>Check that the Python path in the config is correct (<code>"command"</code> field for JSON configs;
             <code>command</code> key for Codex TOML)
           </li>

cli/guide/getting-started.html

@@ -174,7 +174,11 @@ c3 init</code></pre>
           </tr>
           <tr>
             <td><code>AGENTS.md</code></td>
-            <td>Instructions for Codex sessions</td>
+            <td>Instructions for Codex, Grok Build and Antigravity sessions</td>
+          </tr>
+          <tr>
+            <td><code>.grok/config.toml</code>, <code>.grok/hooks/c3.json</code></td>
+            <td>Grok Build only: project MCP entry and C3's hooks (written by <code>--ide grok</code>)</td>
           </tr>
         </tbody>
       </table>
@@ -231,6 +235,12 @@ c3 init</code></pre>
       <pre><code>c3 install-mcp antigravity</code></pre>
       <p>Updates the user-global <code>~/.gemini/antigravity/mcp_config.json</code> and <code>AGENTS.md</code>.</p>
 
+      <h3>Grok Build</h3>
+      <pre><code>c3 install-mcp grok
+grok --trust
+c3 doctor --ide grok</code></pre>
+      <p>Updates <code>.grok/config.toml</code> (<code>[mcp_servers.c3]</code>), writes C3's hooks to <code>.grok/hooks/c3.json</code>, and refreshes the C3 block in <code>AGENTS.md</code>. Grok loads none of them until the folder is trusted, so launch <code>grok --trust</code> once in the project (or run <code>/hooks-trust</code> inside Grok). C3 never writes Grok's trust store or <code>~/.grok/config.toml</code>. In Grok, C3's tools are reached through <code>search_tool</code> / <code>use_tool</code> as <code>c3__c3_search</code> and so on. Details and limitations: <code>docs/grok-native.md</code>.</p>
+
       <p><em>The Gemini CLI profile was removed in v2.52 — use Antigravity instead. <code>c3 uninstall</code> still cleans up legacy <code>.gemini/settings.json</code> and <code>GEMINI.md</code> files.</em></p>
 
       <h3>All IDEs at once</h3>