grok && claude

Claude Code 主导 + Grok 辅助（grok-ask 双模式 + 项目级 .grok/workflows）。

你
 └─ Claude Code（编排 / 决策 / 集成）
      ├─ bin/grok-ask          consult | worker(-w)
      └─ bin/grok-workflow     → .grok/workflows/*.rhai

Prerequisites

• Claude Code CLI (claude)

• Grok Build CLI (grok login)

• python3, bash

Related MCP server: grok-build-mcp

Quick start

cd "/path/to/grok&&claude"
chmod +x bin/*

# 1) 推荐：一键 compact + 打开 debug 网页 + 调 Grok
./bin/grok-ask-live --no-sandbox -n -c demo -d "$PWD" \
  "用三句话总结本仓库是做什么的。"
# → 浏览器: http://127.0.0.1:8765/  终端: Grok run: SUCCESS + handoff 路径

# 2) 安静模式（不要浏览器）
GC_COMPACT=1 ./bin/grok-ask -c demo -d "$PWD" "..."

# 3) Claude Code 打开本目录后
claude
# 对 Claude 说: 用 ./bin/grok-ask-live 调用 Grok，不要用自己的 Agent 代替

Debug window policy

• Default (grok-ask-live / GC_DEBUG_GUI=1): a pywebview native window opens automatically and auto-closes when no run is active and the feed is idle for GC_DEBUG_IDLE_TIMEOUT seconds (default 15). This mirrors cli-agent-mcp's single window.

• Fall back to a browser tab: GC_DEBUG_WINDOW=0 (or --open). Browser tabs can not be auto-closed; gc-debug-viewer --stop stops the server only.

• Force another tab: GC_DEBUG_FORCE_OPEN=1 or --force-open.

• Never open browser: GC_DEBUG_OPEN=0.

• cli-agent-mcp uses one pywebview window for the whole MCP process; we mirror that with one HTTP+SSE server wrapped in a pywebview window.

Layout

Workflows

./bin/grok-workflow audit-plan '{"plan_path":".team/PLAN.md"}'
./bin/grok-workflow verify-diff '{"target":"HEAD"}'
./bin/grok-workflow research-panel '{"query":"How should Claude invoke Grok workflows?"}'
./bin/grok-workflow council-round '{"topic":"Should worker mode touch main branch?"}'
./bin/grok-workflow survey-refs '{}'

Reference clones

dev-docs/refs/code/
  cli-agent-mcp/       # multi-CLI MCP (user-requested)
  claude-grok-bridge/  # original grok-ask
  claude-team-skill/   # /team plan-audit-execute-verify
  grok-delegation/     # Claude plugin delegation

Re-clone or update:

./scripts/sync-refs.sh   # if present
# or manually git -C dev-docs/refs/code/<repo> pull

MCP deployment (CC-switch / any MCP client)

The bridge can be exposed as an MCP server (grok-mcp) so an MCP client — CC-switch, Claude Code, or any FastMCP host — can drive grok-ask / grok-workflow over the MCP protocol without being inside the repo. This is a thin wrapper: it locates the repo via GC_REPO_ROOT and runs its bin/ scripts, so all signal/cancel/audit/debug logic is reused.

# local smoke (builds the package and runs the server)
uvx --from . grok-mcp

Tools: grok_ask (consult/worker), grok_workflow (run a named workflow), grok_workflows (list), grok_runs (list runs), grok_cancel (cancel a run by id).

CC-switch MCP config (mirrors the cli-agent-mcp pattern; GC_REPO_ROOT must point at a checkout that has bin/ and .team/, and the machine needs the grok CLI installed):

{
  "command": "uvx",
  "args": ["--from", "git+https://github.com/Dragonshock/cli-agent-mcp.git", "grok-mcp"],
  "env": { "GC_REPO_ROOT": "/Users/you/grok&&claude", "GC_DEBUG": "false" },
  "timeout": 6000000
}

Design notes

• Claude owns decisions, integration, and user-facing narrative.

• Grok consult = independent model family, read-only.

• Grok worker = burn Grok credits on long implement/test loops in worktrees.

• Grok workflows = deterministic parallel fan-out + adversarial verification (the unique Grok lever).

See CLAUDE.md for the full operating loop.

P0 / P1 runtime (cancel, compact, timeouts, debug)

./scripts/test-p0-p1.sh   # feasibility suite (P0/P1)
./scripts/test-signals.sh # signal handling + flock + debug-log (P2)

Debug window (see Grok while Claude calls it)

Default headless calls do not open a Grok TUI. To get a cli-agent-mcp-style debug window:

# 1) Start live viewer (pywebview native window — auto-opens, auto-closes when idle)
./bin/gc-debug-viewer --window

# 2) Run Grok with debug streaming (default opens the native window)
GC_DEBUG=1 GC_DEBUG_GUI=1 ./bin/grok-ask -c demo -d "$PWD" \
  "Read README.md and summarize in 5 bullets."

• Streams tool/thinking/text events to http://127.0.0.1:8765/ (served inside the native window)

• Full capture: .team/bridge/debug/<channel>-*.log

• Viewer URL: ./bin/gc-debug-viewer --url (get_gui_url equivalent)

• Per-call override: --debug forces on; --no-debug forces off even if GC_DEBUG=1

• Auto-close: window closes when no run is active and the feed is idle for GC_DEBUG_IDLE_TIMEOUT seconds (default 15)

• Fall back to a browser tab: GC_DEBUG_WINDOW=0 (tabs can't be auto-closed)

• Workflow to verify/implement: .grok/workflows/implement-debug-window.rhai

./bin/grok-workflow implement-debug-window '{}'

Folder trust (Grok Build)

Project workflows under .grok/workflows/ require this directory to be trusted in Grok Build before /workflow <name> or the in-session workflow tool can load them. If you see workflow path is not trusted, trust the folder in Grok settings, then:

# from Claude (preferred product path)
./bin/grok-workflow survey-refs '{}'

# or inside a trusted Grok session
/workflow survey-refs

Static research from clone inventory: dev-docs/research/refs-survey.md.