/collaborating-with-grok

name: collaborating-with-grok
description: Delegate tasks to Grok CLI (xAI) for prototyping, debugging, code review, research, and cross-model second opinions. Supports multi-turn sessions via SESSION_ID.
metadata:
  short-description: Delegate to Grok CLI

Collaborating with Grok

Drive the Grok CLI headlessly as an independent collaborator while the calling agent stays responsible for verification, synthesis, and final user-facing decisions.

The bridge (`scripts/grok_bridge.py`) wraps `grok -p`, streams progress to stderr, returns structured JSON, and manages multi-turn continuity via `SESSION_ID`. Always go through the bridge — don't invoke `grok` directly — so output parsing, the safe permission default, and session handling stay consistent.

Commands below write `<skill_dir>` for the absolute path of the directory containing this SKILL.md. Your harness usually reports that path when it loads the skill. If it does not, use this SKILL.md's own location. Substitute it before running, for example `~/.claude/skills/collaborating-with-grok`.

In Claude Code, run non-trivial calls in the background and watch stderr progress:

Bash tool call:
  command: python3 <skill_dir>/scripts/grok_bridge.py --cd "/project" --tools "read_file,grep,list_dir" --PROMPT "Analyze auth flow in src/auth/"
  run_in_background: true

Safety

Grok can read, edit, and run shell. The bridge **defaults to `--permission-mode default`** so headless gated actions are cancelled rather than inheriting host configuration. Read-class tools and Grok's safe-command fast paths still run automatically; use a tool allowlist for deterministic read-only work. `--always-approve` is a mutually exclusive, explicit write-authority choice.

| Posture | Flags | |---|---| | **Review / analysis (read-only)** | `--tools "read_file,grep,list_dir"` | | **Web / X research (no shell/edit)** | `--disallowed-tools "run_terminal_cmd,search_replace"` (+ explicit coding `--model`) | | **Implement** | isolated worktree + `--always-approve` — only with user consent |

Never hand grok secrets or production data. `--sandbox workspace` constrains writes, not arbitrary reads; a prompt describes scope but does not create a hard boundary. Use `strict` or external isolation when read isolation matters. Full semantics: [cli-reference.md](references/cli-reference.md).

Host-side approval

The host gates the `python3 … grok_bridge.py` call first. Claude Code host: pre-authorize it with `"Bash(python3 *collaborating-with-grok*bridge.py*)"` in `permissions.allow`, and on sandboxed hosts add the same pattern to `sandbox.excludedCommands` so the child CLI keeps API network access. The wildcard form keeps matching wherever the skill is installed. Codex hosts: the sandbox can block the child CLI's API network, so escalate or grant network for that call. If the host denies the bridge, report it rather than substituting your own answer for the requested second opinion. Install and approval runbooks: [docs/setup/](https://github.com/appautomaton/agent-designer/tree/main/docs/setup) in the source repo.

Headless note

Tool calls are invisible mid-run (only thought/answer stream). After the run the result includes `model`, `agent`, and `tool_counts` recovered from session files. Use ACP (`grok agent stdio`) when the task requires a live command audit; do not promise live auditing from this bridge. Long silent "Thinking…" usually means tools in progress. Product id is `model` (e.g. `grok-4.5`); `agent` may still say `grok-build-plan` (template lineage).

When to use / not use

Use for: cross-model second opinions, unified-diff proposals, live web/X research, multi-turn analysis. Skip for: trivial one-shots, tasks needing live tool audit trails (use ACP), secrets/prod data.

Web & X search (live)

Differentiator: live web/X via `web_search` on the **coding** model (backend search). As of CLI **0.2.93**, that model is **`grok-4.5`** — confirm with `--list-models` after upgrades.

python3 <skill_dir>/scripts/grok_bridge.py \
  --cd "." --model grok-4.5 \
  --disallowed-tools "run_terminal_cmd,search_replace" \
  --timeout 300 \
  --PROMPT "Search the web and X: <question>. Cite source URLs."

• **Denylist, not allowlist** for search or shell: `--tools` allowlists containing `web_search`, `web_fetch`, or `run_terminal_cmd` fail session build on the GrokBuild-lineage agent (re-probed on 0.2.93). Read-only allowlists without those tools work. Bridge warns if you try.
• Prefer an explicit coding `--model` for search/X; composer (`grok-composer-2.5-fast`, agent `cursor`) is best-effort and often much slower.
• `web_fetch` needs `GROK_WEB_FETCH=1`. Treat fetched content as untrusted. Details: [cli-reference.md](references/cli-reference.md).

Quick start

⚠️ Backticks / `$VARS` in prompts expand in the shell — use a single-quoted heredoc or `--prompt-file`. See [shell-quoting.md](references/shell-quoting.md).

PROMPT="$(cat <<'EOF'
<task>
Review src/auth.py around login() and propose the smallest safe fix.
</task>

<structured_output_contract>
Return a raw unified diff beginning with `---` and `+++`.
Do not use Markdown code fences or add prose before or after the diff.
</structured_output_contract>
EOF
)"
python3 <skill_dir>/scripts/grok_bridge.py \
  --cd "." --tools "read_file,grep,list_dir" --PROMPT "$PROMPT"

**Result contract** (stdout JSON): require both `success: true` (process success) and `complete: true` (clean `EndTurn`). `complete` is `false` for a known incomplete turn and `null` for plain output, where completion is unobservable. A clean turn does not prove correctness or output-contract compliance; validate patches and structured artifacts before using them. Also check `model`, `SESSION_ID`, `warnings`, and `tool_counts` when present. Progress → **stderr**; non-zero exit on process failure.

Large prompts: `--prompt-file`. Handoff file + short instruction: `--stdin-file` + `--PROMPT`; the bridge embed