# 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](https://claude.com/claude-code) CLI (`claude`)
- [Grok Build CLI](https://x.ai/cli) (`grok login`)
- `python3`, `bash`

## Quick start

```bash
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/*` |

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

```text
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:

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

```bash
# 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):

```json
{
  "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. |

```bash
./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**:

```bash
# 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`

```bash
./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:

```bash
# 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`](dev-docs/research/refs-survey.md).