OpenCode run --format json Event Cheatsheet

opencode run --format json writes one JSON object per line (JSONL) to stdout. Each line has a type field indicating the event type.

Event Types

step_start

Marks the beginning of a processing step.

Fields:

• type: "step_start"
• timestamp: Unix timestamp in milliseconds
• sessionID: Session identifier (format: ses_XXX)
• part.id: Part identifier
• part.sessionID: Session ID (duplicated)
• part.messageID: Message ID
• part.type: "step-start"
• part.snapshot: Git snapshot hash

Example:

{"type":"step_start","timestamp":1767036059338,"sessionID":"ses_494719016ffe85dkDMj0FPRbHK","part":{"id":"prt_b6b8e7ec7001qAZUB7eTENxPpI","sessionID":"ses_494719016ffe85dkDMj0FPRbHK","messageID":"msg_b6b8e702b0012XuEC4bGe0XhKa","type":"step-start","snapshot":"71db24a798b347669c0ebadb2dfad238f991753d"}}

tool_use

Tool invocation event. Emitted when a tool finishes (status == "completed").

Fields:

• type: "tool_use"
• timestamp: Unix timestamp in milliseconds
• sessionID: Session identifier
• part.id: Part identifier
• part.callID: Unique call ID for this tool invocation
• part.tool: Tool name (e.g., “bash”, “read”, “write”, “grep”)
• part.state.status: "completed" (the CLI JSON output does not emit pending/running tool states)
• part.state.input: Tool input parameters
• part.state.output: Tool output (when completed)
• part.state.title: Human-readable description
• part.state.metadata: Additional metadata (exit codes, etc.)
• part.state.time.start: Start timestamp
• part.state.time.end: End timestamp

Example:

{"type":"tool_use","timestamp":1767036061199,"sessionID":"ses_494719016ffe85dkDMj0FPRbHK","part":{"id":"prt_b6b8e85bb001CzBoN2dDlEZJnP","sessionID":"ses_494719016ffe85dkDMj0FPRbHK","messageID":"msg_b6b8e702b0012XuEC4bGe0XhKa","type":"tool","callID":"r9bQWsNLvOrJGIOz","tool":"bash","state":{"status":"completed","input":{"command":"echo hello","description":"Print hello to stdout"},"output":"hello\n","title":"Print hello to stdout","metadata":{"output":"hello\n","exit":0,"description":"Print hello to stdout"},"time":{"start":1767036061123,"end":1767036061173}}}}

text

Text output from the model.

Fields:

• type: "text"
• timestamp: Unix timestamp in milliseconds
• sessionID: Session identifier
• part.id: Part identifier
• part.type: "text"
• part.text: The actual text content
• part.time.start: Start timestamp
• part.time.end: End timestamp

Example:

{"type":"text","timestamp":1767036064268,"sessionID":"ses_494719016ffe85dkDMj0FPRbHK","part":{"id":"prt_b6b8e8ff2002mxSx9LtvAlf8Ng","sessionID":"ses_494719016ffe85dkDMj0FPRbHK","messageID":"msg_b6b8e8627001yM4qKJCXdC7W1L","type":"text","text":"```\nhello\n```","time":{"start":1767036064265,"end":1767036064265}}}

step_finish

Marks the end of a processing step.

Fields:

• type: "step_finish"
• timestamp: Unix timestamp in milliseconds
• sessionID: Session identifier
• part.id: Part identifier
• part.type: "step-finish"
• part.reason: Optional. "stop" (final) or "tool-calls" (continuing) when present.
• part.snapshot: Git snapshot hash
• part.cost: Cost in USD
• part.tokens.input: Input token count
• part.tokens.output: Output token count
• part.tokens.reasoning: Reasoning token count
• part.tokens.cache.read: Cache read tokens
• part.tokens.cache.write: Cache write tokens

Example (final step):

{"type":"step_finish","timestamp":1767036064273,"sessionID":"ses_494719016ffe85dkDMj0FPRbHK","part":{"id":"prt_b6b8e9209001ojZ4ECN1geZISm","sessionID":"ses_494719016ffe85dkDMj0FPRbHK","messageID":"msg_b6b8e8627001yM4qKJCXdC7W1L","type":"step-finish","reason":"stop","snapshot":"09dd05d11a4ac013136c1df10932efc0ad9116e8","cost":0.001,"tokens":{"input":671,"output":8,"reasoning":0,"cache":{"read":21415,"write":0}}}}

Example (tool-calls step):

{"type":"step_finish","timestamp":1767036061205,"sessionID":"ses_494719016ffe85dkDMj0FPRbHK","part":{"id":"prt_b6b8e85fb001L4I3WHMqH6EQNI","sessionID":"ses_494719016ffe85dkDMj0FPRbHK","messageID":"msg_b6b8e702b0012XuEC4bGe0XhKa","type":"step-finish","reason":"tool-calls","snapshot":"ee3406d50c7d9048674bbb1a3e325d82513b74ed","cost":0,"tokens":{"input":21772,"output":110,"reasoning":0,"cache":{"read":0,"write":0}}}}

error

Session error event.

Fields:

• type: "error"
• timestamp: Unix timestamp in milliseconds
• sessionID: Session identifier
• error.name: Error type
• error.data.message: Human-readable error (when available)

Example:

{"type":"error","timestamp":1767036065000,"sessionID":"ses_494719016ffe85dkDMj0FPRbHK","error":{"name":"APIError","data":{"message":"Rate limit exceeded","statusCode":429,"isRetryable":true}}}

Mapping to Untether Events

OpenCode Event	Untether Event	Condition
step_start	StartedEvent	First occurrence
tool_use	ActionEvent(phase="completed")	status == "completed"
text	(accumulate text)	-
step_finish	CompletedEvent	reason == "stop"
step_finish	(ignored)	reason == "tool-calls"
error	CompletedEvent(ok=False)	-

If step_finish omits reason, Untether treats a clean process exit as successful completion and emits CompletedEvent(ok=True) with accumulated usage.

Session ID Format

OpenCode uses session IDs in the format: ses_XXXXXXXXXXXXXXXXXXXX

Example: ses_494719016ffe85dkDMj0FPRbHK

Tool Types

Common tool names in OpenCode:

• bash: Shell command execution
• read: Read file contents
• write: Write file contents
• edit: Edit file contents
• glob: File pattern matching
• grep: Content search
• webfetch: Fetch web content
• websearch: Web search
• task: Spawn sub-agent tasks