Claude JSON Protocol - Runloop AI Docs

Overview

The Claude adapter connects Broker to a Claude Code CLI subprocess running inside your Devbox. It launches Claude Code with --output-format stream-json and forwards streaming JSONL messages between Broker and the CLI. For the full wire protocol specification, see the Protocol Spec.

Getting started

To try out fully working code examples, check out the axon-broker-agents example repo. Clone the repo and run the test commands. The example will create a Devbox with Claude and start a “hello world” conversation by publishing an Axon event.

git clone https://github.com/runloopai/runloop-examples \
  && cd runloop-examples/axon-broker-agents \
  && bun install \
  && bun run axon_claude_docs.ts

Broker mount configuration

{
  "type": "broker_mount",
  "axon_id": "<axon-id>",
  "protocol": "claude_json"
}

Field	Type	Description
`type`	`string`	Must be `broker_mount`
`axon_id`	`string`	Required. The Axon stream Broker reads from and writes to
`protocol`	`string`	Must be `claude_json`

How Broker uses Claude JSONL

Broker launches Claude Code with --output-format stream-json when the Devbox starts
Claude initializes and sets up the session
Publish query to the Axon to start a turn
Broker translates that event into Claude’s user JSONL input
Claude output is republished to Axon. Event event_type represents the Claude message type to deserialize.

Send a simple message to Claude

Create a Devbox with a Claude Broker mount and send a ‘hello world’ message to Claude.

Create Devbox with Broker

Create an Axon for communication and launch a Devbox with Claude Code mounted via Broker:

// Create Axon for agent communication
const axon = await sdk.axon.create({ name: "claude-session" });

// Create a Devbox with Claude Code agent
const devbox = await sdk.devbox.create({
  mounts: [
    {
      type: "broker_mount",
      axon_id: axon.id,
      protocol: "claude_json",
      launch_args: [],
    },
  ],
  launch_parameters: {
    launch_commands: [
      'curl -fsSL https://claude.ai/install.sh | bash && echo \'export PATH="$HOME/.local/bin:$PATH"\' >> ~/.bash_profile',
    ],
  },
  environment_variables: {
    PATH: "/home/user/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
    ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY || "",
  },
});

Connect to Claude

Open the client connection and complete the handshake before calling send() in the next step so response listeners can be registered first:

import { ClaudeAxonConnection } from "@runloop/remote-agents-sdk/claude";

const conn = new ClaudeAxonConnection(axon, devbox);

await conn.connect();
await conn.initialize();

Print Assistant Response

Subscribe to the Axon stream and print agent responses:

import {
  isClaudeAssistantEvent,
  isClaudeResultEvent,
} from "@runloop/remote-agents-sdk/claude";

conn.onTimelineEvent((event) => {
  if (isClaudeAssistantEvent(event)) {
    for (const block of event.data.message.content) {
      if (block.type === "text") {
        process.stdout.write(block.text);
      }
    }
  }

  if (isClaudeResultEvent(event)) {
    console.log(`\nTurn complete: ${event.data.subtype}`);
  }
});

await conn.send(userPrompt);

Handling control requests from Claude

During a session, Claude may ask the user a question or request permission before taking an action - these arrive as control request events on the Axon stream. When you receive one, you can either prompt your user for input or respond automatically by publishing a control response.

{
  "type": "control_request",
  "request_id": "b0225af1-13c1-4897-9197-49a9f776fe20",
  "request": {
    "subtype": "can_use_tool",
    "tool_name": "AskUserQuestion",
    "input": {
      "questions": [
        {
          "header": "Fave foods",
          "multiSelect": true,
          "options": [
            { "label": "Pizza", "description": "A classic choice — hard to go wrong" },
            { "label": "Sushi", "description": "Fresh fish and rice, endless variety" },
            { "label": "Tacos", "description": "Versatile, flavorful, always a good time" },
            { "label": "Pasta", "description": "Comfort food at its finest" }
          ],
          "question": "What are your favorite foods?"
        }
      ]
    },
    "permission_suggestions": [],
    "tool_use_id": "toolu_019EVn3FjnenHfCsPFhFLFAR"
  }
}

{
  "type": "control_response",
  "response": {
    "subtype": "success",
    "request_id": "b0225af1-13c1-4897-9197-49a9f776fe20",
    "response": {
      "behavior": "allow",
      "updatedInput": {
        "questions": [
          {
            "header": "Fave foods",
            "question": "What are your favorite foods?",
            "multiSelect": true,
            "options": [
              { "label": "Pizza", "description": "A classic choice — hard to go wrong" },
              { "label": "Sushi", "description": "Fresh fish and rice, endless variety" },
              { "label": "Tacos", "description": "Versatile, flavorful, always a good time" },
              { "label": "Pasta", "description": "Comfort food at its finest" }
            ]
          }
        ],
        "answers": {
          "What are your favorite foods?": "Sushi"
        }
      }
    }
  }
}

There are many types of control responses for responding to Claude. See the Protocol Spec for complete details on all available response types and structures.

Interrupt a turn

Stop Claude’s current response by sending an interrupt control request:

await axon.publish({
  event_type: "control_request",
  origin: "USER_EVENT",
  source: "axon_claude",
  payload: JSON.stringify({
    type: "control_request",
    request_id: crypto.randomUUID(),
    request: {
      subtype: "interrupt",
    },
  }),
});

Building a complete integration

The examples above cover basic messaging and interrupts. To build a production-ready integration, you should become familiar with the full set of Claude control request and response types — these are the building blocks for handling every interaction Claude can initiate during a session. Claude may emit control requests for a variety of reasons, including:

Permission requests — Claude asks for approval before executing commands, writing files, or taking other actions
User questions — Claude asks the user for input or clarification
MCP server interactions — Claude requests access to MCP tool servers

Each control request type has a corresponding response structure that your application needs to handle. You can respond automatically (e.g., auto-approving safe commands) or route requests to a human for review. See the Claude JSONL Protocol Spec for the complete reference on all control request and response types, output message formats, and session lifecycle events.

​Overview

​Getting started

​Broker mount configuration

​How Broker uses Claude JSONL

​Send a simple message to Claude

​Handling control requests from Claude

​Interrupt a turn

​Building a complete integration

Overview

Getting started

Broker mount configuration

How Broker uses Claude JSONL

Send a simple message to Claude

Handling control requests from Claude

Interrupt a turn

Building a complete integration