JSON-RPC Protocol

Clawdius uses JSON-RPC for communication between editor extensions and the core engine.

Overview

The clawdius-code binary acts as a JSON-RPC server, communicating with editor extensions over stdio. The protocol follows the JSON-RPC 2.0 specification.

Transport

JSON-RPC messages are exchanged over standard input/output:

Editor Extension (TypeScript)
    │ stdin/stdout
    ▼
clawdius-code Binary
    │ Rust API calls
    ▼
clawdius-core Library

Request Format

{
  "jsonrpc": "2.0",
  "method": "semantic_search",
  "params": {
    "query": "error handling",
    "limit": 10
  },
  "id": 1
}

Response Format

Success

{
  "jsonrpc": "2.0",
  "result": {
    "matches": [...]
  },
  "id": 1
}

Error

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Invalid params"
  },
  "id": 1
}

Standard Methods

JSON-RPC Server (Gateway)

The clawdius-gateway crate provides an HTTP-based JSON-RPC server using jsonrpsee:

clawdius server --host 0.0.0.0 --port 8080

This exposes the same methods over HTTP/WebSocket for remote access.

Library

The jsonrpsee crate provides both server and client implementations:

[workspace.dependencies]
jsonrpsee = { version = "0.24", features = ["server", "client", "ws-client"] }

Error Codes

VSCode Extension Commands

The VSCode extension communicates via JSON-RPC: