collaborating-with-claude

star 120

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

appautomaton By appautomaton schedule Updated 6/13/2026
play_arrow Run Skill in Manus View GitHub

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.

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

Bash tool call:
  command: python3 skills/collaborating-with-claude/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 on 2.1.176). 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.

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 skills/collaborating-with-claude/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 skills/collaborating-with-claude/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 skills/collaborating-with-claude/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 skills/collaborating-with-claude/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 (default·plan·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 skills/collaborating-with-claude/scripts/claude_bridge.py --help
  • Syntax: python3 -m py_compile skills/collaborating-with-claude/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

Install via CLI
npx skills add https://github.com/appautomaton/agent-designer --skill collaborating-with-claude
Repository Details
star Stars 120
call_split Forks 17
navigation Branch main
article Path SKILL.md
More from Creator
appautomaton
appautomaton Explore all skills →