# Collaborating With Claude

> Delegate tasks to Claude Code CLI for prototyping, debugging, and code review. Supports multi-turn sessions via SESSION_ID.

- Skill: `appautomaton/collaborating-with-claude` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add appautomaton/collaborating-with-claude`
- Raw SKILL.md: https://api.skillmd.com/api/skills/appautomaton/collaborating-with-claude/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: appautomaton (https://skillmd.com/u/appautomaton)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/appautomaton/collaborating-with-claude

---


# 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:

```text
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](references/cli-reference.md), [handoff-patterns.md](references/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/](https://github.com/appautomaton/agent-designer/tree/main/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](references/shell-quoting.md).

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

```bash
# 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](references/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](assets/prompt-template.md); composable XML blocks in [prompt-blocks.md](references/prompt-blocks.md); end-to-end recipes in [prompt-recipes.md](references/prompt-recipes.md); delegation patterns and principles in [patterns.md](references/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](references/handoff-patterns.md)):

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

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