Thrum Daemon RPC API

TL;DR: 26 RPC methods over JSON-RPC 2.0, available on a Unix socket or WebSocket. Most users never need this — the CLI wraps all of it. This reference is for building custom integrations or understanding what's happening under the hood.

Overview

The Thrum daemon exposes a JSON-RPC 2.0 API over Unix socket (.thrum/var/thrum.sock) and WebSocket (ws://localhost:9999). This document describes every available RPC method.

Protocol

JSON-RPC 2.0

All requests and responses follow the JSON-RPC 2.0 specification.

Request format:

{
  "jsonrpc": "2.0",
  "method": "method_name",
  "params": {},
  "id": 1
}

Success response:

{
  "jsonrpc": "2.0",
  "result": {
    /* method-specific result */
  },
  "id": 1
}

Error response:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Error description",
    "data": "Additional error info"
  },
  "id": 1
}

Standard Error Codes

Transports

Both Unix socket and WebSocket expose the same set of methods, with one exception:

• user.register is only available over WebSocket (returns -32001 on Unix socket)

Method Reference

health

Health check and daemon status.

Request:

Response:

Errors:

• No method-specific errors.

agent.register

Register or update an agent identity.

Request:

Response:

Errors:

• invalid request: Malformed JSON params
• role is required: Missing role field
• module is required: Missing module field

agent.list

List registered agents with optional filters.

Request:

Response:

Errors:

• invalid request: Malformed JSON params

agent.whoami

Get current agent identity and active session.

Request:

Response:

Errors:

• resolve identity: Could not determine agent identity from environment or identity file

agent.listContext

List agent work contexts (branch, commits, files, intent, task).

Request:

Response:

Errors:

• invalid request: Malformed JSON params

agent.delete

Delete an agent by name. Removes the identity file, per-agent JSONL message file, and SQLite record. Emits an agent.cleanup event.

Request:

Response:

Errors:

• agent name is required: Missing name field
• invalid agent name: Name does not match validation regex
• agent not found: No agent with given name

agent.cleanup

Detect and optionally remove orphaned agents. An agent is considered orphaned if its identity file is missing, its worktree no longer exists, or it has been inactive beyond the threshold.

Request:

Response:

Errors:

• invalid request: Malformed JSON params

session.start

Start a new work session for an agent. Automatically recovers any orphaned sessions for the same agent.

Request:

Response:

Errors:

• agent_id is required: Missing agent_id field
• agent not found: Agent with given ID is not registered

session.end

End an active work session. Syncs work contexts to JSONL on end.

Request:

Response:

Errors:

• session_id is required: Missing session_id field
• get session: Session ID not found

session.heartbeat

Update session activity timestamp. Optionally add/remove scopes and refs. Extracts git work context if a worktree ref is set.

Request:

Response:

Errors:

• session_id is required: Missing session_id field
• session not found: Session ID does not exist
• session has already ended: Session was previously ended

session.setIntent

Set a free-text intent describing what the agent is working on.

Request:

Response:

Errors:

• session_id is required: Missing session_id field
• session not found: Session ID does not exist
• session has already ended: Session was previously ended

session.setTask

Set the current task identifier for the session.

Request:

Response:

Errors:

• session_id is required: Missing session_id field
• session not found: Session ID does not exist
• session has already ended: Session was previously ended

session.list

List sessions with optional filters.

Request:

Response:

Errors:

• invalid request: Malformed JSON params

message.send

Send a message to the messaging system. Triggers subscription notifications.

Request:

Response:

Errors:

• content is required: Missing content field
• invalid format: Format not one of markdown, plain, json
• no active session found: Agent does not have an active session
• only users can impersonate agents: Non-user tried to use acting_as
• target agent does not exist: acting_as references nonexistent agent

message.get

Retrieve a single message by ID with full details.

Request:

Response:

Errors:

• message_id is required: Missing message_id field
• message not found: No message with given ID

message.list

List messages with filtering, pagination, and sorting.

Request:

Response:

Errors:

• invalid sort_by: Must be "created_at" or "updated_at"
• invalid sort_order: Must be "asc" or "desc"

message.edit

Edit a message's content or structured data. Only the original author can edit.

Request:

Response:

Errors:

• message_id is required: Missing message_id field
• at least one of content or structured must be provided: Neither field given
• message not found: No message with given ID
• cannot edit deleted message: Message was soft-deleted
• only message author can edit: Current agent is not the message author
• no active session found: Agent does not have an active session

message.delete

Soft-delete a message. The message remains in the database and JSONL log but is marked as deleted.

Request:

Response:

Errors:

• message_id is required: Missing message_id field
• message not found: No message with given ID
• message already deleted: Message was already soft-deleted

message.markRead

Batch mark messages as read for the current agent and session. Returns collaboration info (other agents who also read the messages).

Request:

Response:

Errors:

• message_ids is required and must not be empty: Missing or empty message_ids array
• no active session found: Agent does not have an active session

group.create

Create a named group for targeted messaging. Groups can contain agents and roles.

Request:

Response:

Errors:

• name is required: Missing name field
• group already exists: Group with this name already exists

group.delete

Delete a group by name. The @everyone group is protected and cannot be deleted.

Request:

Response:

Errors:

• name is required: Missing name field
• cannot delete protected group: Attempted to delete @everyone
• group not found: No group with given name

group.member.add

Add a member to a group. Members can be agents (by name) or roles.

Request:

Response:

Errors:

• group is required: Missing group field
• member_type is required: Missing member_type field
• member_value is required: Missing member_value field
• group not found: No group with given name
• invalid member_type: Must be "agent" or "role"

group.member.remove

Remove a member from a group.

Request:

Response:

Errors:

• group is required: Missing group field
• member_type is required: Missing member_type field
• member_value is required: Missing member_value field
• group not found: No group with given name
• member not found: Member is not in the group

group.list

List all groups in the system.

Request:

Response:

Errors:

• No method-specific errors.

group.info

Get detailed information about a specific group.

Request:

Response:

Errors:

• name is required: Missing name field
• group not found: No group with given name

group.members

Get members of a group with optional expansion. When expand is true, resolves roles to individual agent IDs.

Request:

Response (without expand):

Response (with expand=true):

Errors:

• name is required: Missing name field
• group not found: No group with given name

subscribe

Subscribe to push notifications for messages matching a scope, mention, or all messages.

Request:

Exactly one of scope, mention_role, or all must be provided.

Response:

Errors:

• at least one of scope, mention_role, or all must be specified: No subscription type given
• no active session found: Agent does not have an active session

unsubscribe

Remove a subscription by ID.

Request:

Response:

Errors:

• subscription_id is required: Missing or zero subscription_id
• no active session found: Agent does not have an active session

subscriptions.list

List all subscriptions for the current session.

Request:

Response:

Errors:

• no active session found: Agent does not have an active session

user.register

Register a human user identity. Only available over WebSocket.

Request:

Response:

Errors:

• -32001 (Transport error): Method called over Unix socket instead of WebSocket
• username is required: Missing username field
• username cannot start with 'agent:' prefix: Namespace conflict
• invalid username format: Does not match [a-zA-Z0-9_-]{1,32}

Notes:

• Registration is idempotent: if the user already exists, returns the existing info with a fresh token and status "existing".

user.identify

Get the current user's identity from git config. Used for browser auto-registration.

Request:

Response:

Errors:

• git config user.name not set: Git user.name is not configured in the repository

Push Notifications

When a message matches a subscription, the daemon sends a JSON-RPC notification (no id field) over the same socket connection:

Notification format:

{
  "jsonrpc": "2.0",
  "method": "notification.message",
  "params": {
    "message_id": "msg_01HXE...",
    "author": {
      "agent_id": "agent:implementer:auth:ABC",
      "role": "implementer",
      "module": "auth"
    },
    "preview": "First 100 chars of message...",
    "scopes": [{ "type": "module", "value": "auth" }],
    "matched_subscription": {
      "subscription_id": 42,
      "match_type": "scope"
    },
    "timestamp": "2026-02-03T10:00:00Z"
  }
}

Match types:

• scope - Message has a scope matching your subscription
• mention - Message mentions your subscribed role
• all - Your "all messages" subscription matched

Client implementation notes:

1. Keep connection open to receive notifications
2. Notifications have no id field (one-way, no response expected)
3. Use message.get to fetch full message content after notification
4. Clients disconnected at notification time will see messages via message.list when reconnecting

sync.status

Get current sync loop status and health. Available when the sync loop is active (requires a remote origin).

Request:

Response:

Notes:

• This method is only registered when the sync loop is initialized (i.e., the repository has a remote origin). Returns method-not-found (-32601) otherwise.

sync.force

Trigger an immediate sync (non-blocking). Available when the sync loop is active (requires a remote origin).

Request:

Response:

Notes:

• This method is only registered when the sync loop is initialized (i.e., the repository has a remote origin). Returns method-not-found (-32601) otherwise.
• The sync loop runs every 60 seconds by default (configurable via --sync-interval).

Using the API

From Command Line

# Using netcat (nc)
echo '{"jsonrpc":"2.0","method":"health","id":1}' | nc -U .thrum/var/thrum.sock

# Using curl (requires HTTP-to-Unix-socket proxy)
# Not directly supported without proxy

From Go Code

import "github.com/leonletto/thrum/internal/daemon"

// Connect to daemon
client, err := daemon.NewClient(".thrum/var/thrum.sock")
if err != nil {
    log.Fatal(err)
}
defer client.Close()

// Call health method
result, err := client.Call("health", map[string]any{})
if err != nil {
    log.Fatal(err)
}

var healthResp daemon.HealthResponse
if err := json.Unmarshal(result, &healthResp); err != nil {
    log.Fatal(err)
}

fmt.Printf("Status: %s\n", healthResp.Status)

From Other Languages

Python Example

import socket
import json

def call_rpc(method, params={}):
    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
    sock.connect('.thrum/var/thrum.sock')

    request = {
        'jsonrpc': '2.0',
        'method': method,
        'params': params,
        'id': 1
    }

    sock.sendall(json.dumps(request).encode() + b'\n')
    response = sock.recv(4096)
    sock.close()

    return json.loads(response)

# Call health method
result = call_rpc('health')
print(result['result']['status'])

Node.js Example

const net = require("net");

function callRPC(method, params = {}) {
  return new Promise((resolve, reject) => {
    const client = net.createConnection(".thrum/var/thrum.sock");

    const request = {
      jsonrpc: "2.0",
      method: method,
      params: params,
      id: 1,
    };

    client.on("connect", () => {
      client.write(JSON.stringify(request) + "\n");
    });

    client.on("data", (data) => {
      const response = JSON.parse(data.toString());
      client.end();
      resolve(response.result);
    });

    client.on("error", reject);
  });
}

// Call health method
callRPC("health").then((result) => {
  console.log("Status:", result.status);
});

Best Practices

Connection Management

1. Reuse connections - Keep the connection open for multiple requests
2. Handle disconnections - Implement retry logic for connection failures
3. Set timeouts - Don't wait forever for responses

Error Handling

1. Check error field - Always check for error in response
2. Handle specific error codes - Different codes require different actions
3. Retry on transient errors - Socket errors, timeouts

Request IDs

1. Use unique IDs - Helps correlate requests and responses
2. Can be strings or numbers - Both are valid per JSON-RPC 2.0
3. Optional for notifications - Omit ID if you don't need a response

Troubleshooting

Connection Refused

# Check if daemon is running
ps aux | grep thrum

# Check socket exists
ls -l .thrum/var/thrum.sock

# Check socket permissions
# Should be: srw------- (0600)

Parse Errors

Common causes:

• Missing newline (\n) at end of request
• Invalid JSON syntax
• Wrong encoding (must be UTF-8)

Method Not Found

• Check method name spelling (case-sensitive)
• Verify daemon version supports the method
• See available methods section above

Next Steps

• WebSocket API — use these methods over WebSocket for real-time browser and agent connections
• Daemon Architecture — how the daemon registers and dispatches these RPC handlers
• Inbox Query Methods — deeper coverage of message.list filtering, pagination, and read-state tracking
• Event Streaming — push notifications via the subscribe method and Broadcaster

References

• JSON-RPC 2.0 Specification
• Daemon Architecture: docs/daemon.md
• Development Guide: docs/development.md