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

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

Path	Purpose
CLAUDE.md	Claude orchestrator rules
AGENTS.md	Grok-side rules
.team/team.json	Roster + routing
.team/PLAN.md etc.	Shared blackboard
bin/grok-ask	Channelized headless Grok (consult/worker)
bin/grok-workflow	Launch named project workflows
.grok/workflows/	Rhai multi-agent panels
.claude/skills/	council, grok-run
dev-docs/refs/code/	Cloned reference sources

Workflows

Name	Use
audit-plan	Multi-dimension plan critique
verify-diff	Parallel review + adversarial verify
research-panel	Multi-angle research + cross-check
council-round	Advocate / skeptic / pragmatist meeting
survey-refs	Survey dev-docs/refs/code/*

./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)

Feature	How
Cancel without killing Claude	Each run registers .team/bridge/runs/<run_id>.json (pid/pgid). bin/gc-run-cancel <run_id> sends SIGTERM/KILL to the child process group only.
Compact handoff	GC_COMPACT=1 or --compact → stdout is short status + handoff path; full body in .team/bridge/handoffs/*.xml as <agent-output>.
First-event / fatal timeout	GC_FIRST_EVENT_TIMEOUT=45 (default). No output → FAILED(first_event) / rc 125. Fatal stderr patterns kill early.
Default model	grok-4.5 via bridge (override -m). Independent of Claude/DeepSeek.
Workflow debug	GC_DEBUG=1 ./bin/grok-workflow --debug <name> '…' streams to the same debug window.
Graceful cancel (P2)	SIGINT/SIGTERM to the bridge cancels the isolated grok process group → Grok run: FAILED(cancelled) (rc 130). No orphan. GC_SIGINT_MODE=cancel|cancel_then_exit (2nd signal = hard kill). Cancel is terminal: skips sandbox/resume retries.
Audit serialization	logs/<channel>.jsonl appends are fcntl.flock-serialized — concurrent writers never interleave.
Full subprocess capture	GC_LOG_DEBUG=1 + --debug → $GC_BRIDGE_DEBUG_DIR/cam_debug_*.log (0700; default /tmp/grok-bridge-debug) with full command + raw stdout/stderr + rc.

./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.