# RPC Mode

RPC mode enables process-to-process communication with Voxcode over a structured JSON-RPC protocol. Use it when you need to integrate Voxcode into a larger system rather than driving it from a terminal.

## Use Cases

- **IDE integrations** — embed AI coding assistance directly into editors
- **Supervisor services** — manage Voxcode as a child process from a daemon
- **Local orchestrators** — coordinate multiple Voxcode instances across a workspace
- **Custom tooling** — build bespoke frontends that drive the agent programmatically

## Protocol

RPC mode uses a JSON-RPC 2.0 message format over stdin/stdout:

```json
{"jsonrpc":"2.0","id":1,"method":"execute","params":{"prompt":"Summarize src/","session":"my-session"}}
```

Responses are streamed as newline-delimited JSON:

```json
{"jsonrpc":"2.0","id":1,"result":{"status":"completed","output":"..."}}
```

## Starting RPC Mode

```bash
vox --rpc
```

The process listens on stdin for JSON-RPC requests and writes responses to stdout. Stderr is reserved for diagnostics.

## Methods

| Method | Description |
|--------|-------------|
| `execute` | Run a single prompt and return the result |
| `session.create` | Create a named session |
| `session.resume` | Resume an existing session by id |
| `session.list` | List available sessions |
| `ping` | Health-check — returns `pong` |

## Lifecycle

1. Start Voxcode with `--rpc`
2. Send requests as JSON lines on stdin
3. Read responses as JSON lines on stdout
4. Close stdin or send a `shutdown` notification to terminate

## Error Handling

Errors follow JSON-RPC 2.0 conventions:

```json
{"jsonrpc":"2.0","id":1,"error":{"code":-32603,"message":"Internal error","data":"..."}}
```

## Related

- [SDK](sdk.md) — higher-level programmatic integration for TypeScript/Node
- [JSON mode](json.md) — single-shot structured output for scripting
