# JSON Mode

JSON mode emits structured output suitable for scripting, CI pipelines, and tool integrations.

## Why Use It

- **Reliable machine parsing** — structured JSON output instead of free-form text
- **Stable downstream integrations** — predictable schema for consuming tools
- **CI and pipeline compatibility** — pipe results into jq, GitHub Actions, or custom scripts
- **Deterministic extraction** — extract specific fields (file paths, error counts, summaries) without text scraping

## Basic Usage

```bash
vox --json -p "List changed files and summarize impact"
```

Output includes structured fields:

```json
{
  "success": true,
  "output": "Summary of changes...",
  "files": ["src/index.ts", "src/cli.ts"],
  "session": "session-abc123"
}
```

## Output Structure

The JSON output contains:

| Field | Type | Description |
|-------|------|-------------|
| `success` | boolean | Whether the operation completed without errors |
| `output` | string | The main textual response from the agent |
| `files` | string[] | Files referenced or modified during the session |
| `session` | string | Session identifier for resumption |
| `error` | object | Present only on failure — contains `message` and optional `code` |

## Streaming

Combine with `--stream` to receive incremental JSON chunks as the model generates:

```bash
vox --json --stream -p "Refactor src/parser.ts"
```

Each chunk is a standalone JSON object with a `type` field (`"chunk"`, `"tool_call"`, `"complete"`).

## CI Pipeline Integration

```bash
# Run a code review and check for errors
vox --json -p "Review this PR for bugs" | jq -r '.output'

# Fail pipeline if the agent reports issues
vox --json -p "Check for syntax errors" | jq -e '.success'
```

## Related

- [RPC mode](rpc.md) — persistent connection for process-to-process integration
- [SDK](sdk.md) — programmatic access from TypeScript/Node
