collaborating-with-claude

name	collaborating-with-claude
description	Delegate tasks to Claude Code CLI for prototyping, debugging, and code review. Supports multi-turn sessions via SESSION_ID.
metadata	{"short-description":"Delegate to Claude Code CLI"}

Collaborating with Claude Code

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

The bridge (scripts/claude_bridge.py) wraps claude --print, streams progress to stderr, returns structured JSON with telemetry, and manages multi-turn continuity via SESSION_ID. Always go through the bridge — don't invoke claude directly — so output parsing 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 ~/.codex/skills/collaborating-with-claude.

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

Bash tool call:
  command: python3 <skill_dir>/scripts/claude_bridge.py --cd "/project" --PROMPT "Analyze auth flow in src/auth/"
  run_in_background: true

run_in_background is a host tool parameter, not a shell argument. Use the task-output view to monitor timestamped stderr progress (session, responses, tools, cost) and the final JSON result.

Safety

Default to read-only delegation: --permission-mode plan (analyze, no edits/commands) or --tools "Read,Glob,Grep". Grant writes only deliberately (acceptEdits/auto), preferably in an isolated worktree. Do not hand secrets, private keys, or production data to Claude. Full permission-mode set and the worktree pattern: cli-reference.md, handoff-patterns.md.

Permissions and network (headless)

Headless claude -p cannot prompt: every gated action is denied on the spot and recorded in permission_denials, which the bridge surfaces (verified). Authority is therefore decided entirely up front via --permission-mode, --tools, and --allowed-tools — get user consent before granting anything beyond read-only.

Network is governed by tool policy, not an OS sandbox: plan mode denies WebFetch/WebSearch too (verified), while an allowed Bash can reach the network freely. Pick the posture per task:

• No network, read-only: --permission-mode plan, or --tools "Read,Glob,Grep".
• Read-only plus targeted web research (verified): --permission-mode dontAsk --tools "Read,Glob,Grep,WebFetch,WebSearch" --allowed-tools "WebFetch(domain:example.com)" --allowed-tools "WebSearch".
• Reads outside --cd are gated as well — grant extra roots with --add-dir.

Host-side approval (the bridge call itself)

Everything above governs the child Claude. The host agent's own permission layer gates the python3 … claude_bridge.py Bash call first — and under classifier-gated auto-approval (Claude Code auto/dontAsk, Codex non-interactive runs), a long-running script that spawns another agent over the codebase pattern-matches "high-risk" and can be denied silently: the delegation never starts. A host permission error instead of bridge JSON means the host blocked the bridge, not that Claude failed.

• Pre-authorize the bridge instead of relying on the classifier. Claude Code host: add "Bash(python3 *collaborating-with-claude*bridge.py*)" to permissions.allow in your settings.json. The wildcard form keeps matching wherever the skill is installed. Sandboxed hosts also need "python3 *collaborating-with-claude*bridge.py*" in sandbox.excludedCommands, because sandbox network policy blocks the child CLI's API traffic even after the command is allowed. Grok host: pass the same rule via --allow. Install and approval runbooks: docs/setup/ in the source repo.
• Codex host: the sandbox is the second gate. Both read-only and workspace-write block shell network, so the child CLI can't reach its API at all. Run the bridge call through an approved escalation, or knowingly grant network for that call.
• Never degrade silently. If the host denies the bridge call, report it and propose the allowlist fix — don't substitute your own answer for the independent second opinion that was requested.

When to use / not use

Use for: second opinions on design, edge cases, or test gaps; proposing or reviewing a unified diff; multi-turn analysis while you implement. Skip for: trivial one-shot edits (do them directly); tasks needing authoritative cited facts (Claude may guess); anything touching secrets or prod data.

Quick start

⚠️ Backticks / $VARS in prompts trigger shell expansion — use a single-quoted heredoc, or --prompt-file for large/generated prompts. See shell-quoting.md.

PROMPT="$(cat <<'EOF'
Review src/auth.py around login() and propose fixes.
OUTPUT: Unified Diff Patch ONLY.
EOF
)"
python3 <skill_dir>/scripts/claude_bridge.py \
  --cd "." --model sonnet --permission-mode plan --PROMPT "$PROMPT" --output-format stream-json

For large or shell-sensitive prompts, write the prompt to a file and pass --prompt-file /tmp/prompt.md (piped via stdin — no argv/quoting limits).

Returns (stdout JSON): { "success": true, "SESSION_ID": "...", "agent_messages": "...", "model": "...", "subtype": "success", "total_cost_usd": 0.03, "usage": {...}, "num_turns": 1 } — plus tools_used / tools_failed / tool_counts / permission_denials / structured_output / is_error when relevant. Check tools_failed and permission_denials before trusting the answer: a denied tool means Claude reasoned without the evidence it asked for. Progress streams to stderr; the bridge exits non-zero on failure.

Multi-turn sessions

Capture SESSION_ID from the first call and pass it back (selectors are mutually exclusive):

# Turn 1
python3 <skill_dir>/scripts/claude_bridge.py \
  --cd "." --model sonnet --PROMPT "Analyze the bug in foo()." --output-format stream-json

# Turn 2 — resume by ID (use the same --cd)
python3 <skill_dir>/scripts/claude_bridge.py \
  --cd "." --model sonnet --SESSION_ID "<id>" --PROMPT "Propose a fix." --output-format stream-json

# Or resume the most recent session in this directory
python3 <skill_dir>/scripts/claude_bridge.py \
  --cd "." --model sonnet --continue --PROMPT "What about edge cases?" --output-format stream-json

Use stream-json or json output to capture SESSION_ID.

Bridge flags

Core: --PROMPT (or --prompt-file) · --cd (required) · --model (alias haiku/sonnet/opus/fable, or full id) · --output-format (text·json·stream-json, default stream-json).

Sessions (mutually exclusive): --SESSION_ID · --session-id <uuid> · --continue; plus --fork-session, --no-session-persistence.

Permissions: --permission-mode (plan·manual·acceptEdits·auto·dontAsk·bypassPermissions) · --tools · --allowed-tools · --disallowed-tools. Footgun: the space in Bash(git diff *) is load-bearing.

Reproducibility & cost: --bare / --safe-mode (skip customizations; --bare needs ANTHROPIC_API_KEY) · --effort (low→max) · --max-budget-usd · --max-turns · --timeout <seconds>.

Context & advanced: --prompt-file · --system-prompt[-file] · --append-system-prompt[-file] · --add-dir · --json-schema · --mcp-config · --settings · --agent/--agents · --return-all-messages · --verbose.

Full semantics in cli-reference.md. Set the host's timeout_ms to 600000 (10 min) when invoking via a command runner.

Tune performance

--model haiku for quick checks, sonnet for routine work, opus or fable for hard tasks; --effort low→max trades depth for speed/cost; --max-budget-usd caps spend. Omit --model to use the CLI default.

Prompting

Quick starters in prompt-template.md; composable XML blocks in prompt-blocks.md; end-to-end recipes in prompt-recipes.md; delegation patterns and principles in patterns.md. In short: point (file:line), don't paste; one objective per run; state the output shape; verify Claude's output before acting.

Verification

• Smoke: python3 <skill_dir>/scripts/claude_bridge.py --help
• Syntax: python3 -m py_compile <skill_dir>/scripts/claude_bridge.py
• Session: run a prompt with --output-format stream-json; confirm JSON has success: true, a SESSION_ID, and telemetry (subtype/total_cost_usd/usage/num_turns); failures exit non-zero.
• Ensure Claude is logged in (claude then /login), or set ANTHROPIC_API_KEY (required for --bare).

Collaboration State Capsule

Keep this updated across turns (referenced by handoff-patterns.md):

[Claude Capsule] Goal: | SID: | Model: | PermMode: | Files: | Last: | Next:

References

• prompt-template.md — quick plain-text starters
• prompt-blocks.md — composable XML blocks
• prompt-recipes.md — end-to-end templates
• prompt-antipatterns.md — common mistakes
• patterns.md — when to delegate + prompt patterns
• handoff-patterns.md — read-only / worktree / synthesis
• parallel.md — parallel runs and worktree isolation
• cli-reference.md — verified Claude CLI flags + event schema
• shell-quoting.md — safe heredoc prompts