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 Takopi Events¶
| OpenCode Event | Takopi 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, Takopi 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