Quick Start
bashpython scripts/claude_bridge.py --cd "/path/to/project" --PROMPT "Analyze auth flow"
Output: JSON with success, SESSION_ID, agent_messages, stream_file
(the raw Claude JSONL stream), and optional all_messages, stderr, or error.
Runtime Contract
- Default execution uses
claude -pand does not force--safe-mode,--bare,--disable-slash-commands, or--strict-mcp-config. - Claude Code therefore keeps its normal loading path for trusted-workspace customizations such as
CLAUDE.md, skills, plugins, MCP servers, custom commands, and rules. claude -pskips the interactive trust dialog and silently ignores invalid settings files, so use this only in workspaces you already trust and whose.claudesettings already validate.- The bridge requests
stream-json, persists each record immediately, and only treats Claude's finalresultrecord as a completed answer. Intermediateassistantrecords never mask a failed or incomplete turn. - On Windows the PROMPT is delivered through stdin when
clauderesolves to a.cmd/.batshim, so the prompt never passes through cmd.exe quoting and cannot hit the command-line length limit.
Parameters
textusage: claude_bridge.py [-h] --PROMPT PROMPT --cd CD [--SESSION_ID SESSION_ID] [--model MODEL] [--permission-mode {,acceptEdits,auto,bypassPermissions,manual,dontAsk,plan}] [--dangerously-skip-permissions] [--timeout TIMEOUT] [--stream-file STREAM_FILE] [--return-all-messages] {mcp,plugin} ... options: --PROMPT PROMPT Instruction for the task to send to Claude Code. --cd CD Workspace root for Claude Code (cwd + --add-dir). --SESSION_ID SESSION_ID Resume a conversation by session UUID. --model MODEL Claude model override. Aliases resolve against the active endpoint. --permission-mode ... Claude permission mode override. --dangerously-skip-permissions Bypass Claude permission checks. --timeout TIMEOUT Bridge-level timeout in seconds. Omit for no bridge deadline. --stream-file STREAM_FILE Raw Claude stream-json JSONL destination. --return-all-messages Include parsed stream records in the result. subcommands: mcp Thin passthrough to `claude mcp`. plugin Thin passthrough to `claude plugin`.
Sessions
Capture SESSION_ID from the first successful response and reuse it for follow-ups.
SESSION_ID is empty when a run never established a session (claude produced no stream output):
resume only with an id the bridge actually returned.
bash# New Claude session python scripts/claude_bridge.py --cd "/project" --PROMPT "Inspect failing tests" # Resume the same Claude session python scripts/claude_bridge.py --cd "/project" --SESSION_ID "uuid-from-response" --PROMPT "Now propose the fix"
Passthrough
bashpython scripts/claude_bridge.py mcp list python scripts/claude_bridge.py plugin list


