Driving Claude Code headlessly with stream-json

claude -p prints a response and exits. That's fine for scripting a one-shot task, and useless if you want a long-lived session you can talk to. The streaming JSON mode is the other thing: a subprocess you keep open, write JSONL to on stdin, and read JSONL from on stdout.

Starting the process

claude -p \
  --input-format stream-json \
  --output-format stream-json \
  --permission-mode default \
  --permission-prompt-tool stdio

• -p / --print — non-interactive. Required for the stream formats.
• --input-format stream-json — realtime streaming input on stdin, rather than a single prompt argument.
• --output-format stream-json — realtime streaming events on stdout, one JSON object per line.
• --permission-prompt-tool — routes permission prompts to your process instead of a terminal UI. It isn't listed in claude --help; it's the SDK-facing flag, and it's the one that makes the whole thing interesting.

Useful companions: --include-partial-messages for token-level streaming, --replay-user-messages to have your own messages echoed back for acknowledgement, --session-id <uuid> to pin the session ID, --resume <id> to continue an existing one, and --max-budget-usd to cap spend.

Sending a message

Write one JSON object per line to stdin. A user turn looks like this:

{
  "type": "user",
  "message": {
    "role": "user",
    "content": [{ "type": "text", "text": "Refactor the auth module" }]
  }
}

Newline-terminated, no pretty-printing. The process stays alive between turns, so this is a conversation rather than a series of invocations.

What comes back

The permission handshake

This is the part worth the article. When the agent wants to use a tool that needs approval, you get a control_request with subtype: "can_use_tool":

{
  "type": "control_request",
  "request_id": "req_01H...",
  "request": {
    "subtype": "can_use_tool",
    "tool_name": "Bash",
    "description": "Run the test suite",
    "input": { "command": "npm run test", "description": "Run the test suite" },
    "permission_suggestions": [
      { "type": "addRules", "rules": [{ "toolName": "Bash", "ruleContent": "npm run test *" }] }
    ]
  }
}

The session is now blocked. Nothing else will happen until you write a control_response carrying the same request_id:

{
  "type": "control_response",
  "response": {
    "subtype": "success",
    "request_id": "req_01H...",
    "response": { "behavior": "allow", "updatedInput": { "command": "npm run test" } }
  }
}

Three shapes of answer:

• Allow — { "behavior": "allow", "updatedInput": <the input> }. Echo the input back; you can also modify it, which is how you'd implement 'yes, but with --dry-run'.
• Deny — { "behavior": "deny", "message": "..." }. The message goes to Claude, so a specific reason lets it adapt rather than retry the same thing.
• Allow always — allow, plus updatedPermissions set to the permission_suggestions from the request. That's how a 'don't ask again' button works: the CLI proposes the rule, you hand it back.

A minimal driver

import json, subprocess, threading, queue

proc = subprocess.Popen(
    ["claude", "-p",
     "--input-format", "stream-json",
     "--output-format", "stream-json",
     "--permission-mode", "default",
     "--permission-prompt-tool", "stdio"],
    stdin=subprocess.PIPE, stdout=subprocess.PIPE,
    text=True, bufsize=1,
)

def send(obj):
    proc.stdin.write(json.dumps(obj) + "\n")
    proc.stdin.flush()

def approve(request_id, tool_input):
    send({"type": "control_response", "response": {
        "subtype": "success",
        "request_id": request_id,
        "response": {"behavior": "allow", "updatedInput": tool_input},
    }})

send({"type": "user", "message": {
    "role": "user",
    "content": [{"type": "text", "text": "Run the test suite and fix what fails"}],
}})

for line in proc.stdout:
    line = line.strip()
    if not line:
        continue
    try:
        event = json.loads(line)
    except json.JSONDecodeError:
        continue          # partial line; buffer in real code

    kind = event.get("type")

    if kind == "system" and event.get("subtype") == "init":
        print("session:", event.get("session_id"))

    elif kind == "control_request":
        req = event.get("request", {})
        if req.get("subtype") == "can_use_tool":
            print("wants:", req.get("tool_name"), req.get("input"))
            # ---- this is where a human decides ----
            approve(event["request_id"], req.get("input", {}))

    elif kind == "result":
        print("done:", event.get("total_cost_usd"))
        break

Things that bite

• The process blocks on you. A control_request you never answer means the session sits there forever. If your UI can crash or lose focus, you need a story for what happens to in-flight requests — that latency is the whole cost model.
• Failed resume is quiet. --resume with a stale ID produces an is_error result with no init event, then exits. Track whether you ever saw init to tell the difference between 'resumed' and 'never started'.
• Every session is a real process. Ten background sessions are ten claude processes with ten context windows. Start them lazily rather than restoring everything at launch.
• Don't auto-approve to make it smooth. If you're building on this, the value is putting a human in front of the decision faster — not deciding for them. A relay that quietly allows things is a bypassPermissions you didn't tell the user about.

What it's good for

Custom approval UIs, primarily. Once permission requests are structured events rather than terminal prompts, you can put the decision anywhere — a menu bar, a phone, a Slack message, a floating bubble that renders over fullscreen video. That last one is BubbleCode: each chat is one of these subprocesses, and the bubble is the approval surface.

It's also the right substrate for CI integration where you want structured events rather than scraped text, for multi-agent orchestration with real per-session state, and for anything that needs cost and duration per turn from the result event.

What it isn't is a stable public API. Field names have changed between releases. If you ship on it, pin a CLI version, and check claude --version at startup so you fail loudly rather than mysteriously.