Thrum Daemon RPC API

TL;DR: 50+ 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)

Caller Identity

Most RPC fields in this document include a caller_agent_id parameter. Its semantics depend on the transport:

• Unix socket (v0.9.0+): The daemon resolves caller identity via kernel peer credentials (SO_PEERCRED on Linux, LOCAL_PEERPID on macOS). If caller_agent_id is also provided, the daemon cross-checks it against the kernel-verified identity. A mismatch returns unauthenticated_rpc/identity_mismatch. Forged claims cannot succeed. Shared-worktree fallback: when peercred resolves to a worktree hosting multiple co-located agents and the claimed caller_agent_id is also registered in that same worktree, the claim is trusted (the CLI plumbs caller_agent_id from THRUM_NAME / the local identity file on every mutating call, including message.delete). Cross-worktree claims still fail. See Security Model for the full trust stack.
• WebSocket: Peercred is not available. Mutating RPCs require a non-empty caller_agent_id. Strict mode returns unauthenticated_rpc/no_caller_agent_id when it is absent. See Troubleshooting Identity for remediation steps. (G3 note)

Anonymous callers (callers whose CWD does not resolve to a registered agent worktree) may only invoke a hardcoded read-only allowlist of ~30 methods. Mutating RPCs are rejected at the dispatcher before the handler runs. See Security Model for the full allowlist.

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

Notes:

• The role+module conflict check is scoped to the local daemon only. Agents that were registered on a remote daemon and synced into the local DB via origin_daemon are not treated as conflicts — two daemons in a peer mesh can have agents with identical role+module without triggering this error. This fixes the cross-daemon force-delete bug tracked as thrum-mm3l.

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
• only message author can delete: Caller is not the message author; only the agent that sent the message may delete it. Non-author callers receive this error regardless of transport.

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

message.deleteByAgent

Hard-delete all messages authored by a specific agent. The caller must be the same agent as the target — this method cannot be used to delete another agent's messages.

Unix socket only. Not available over WebSocket (structural guard prevents registration on the WebSocket transport).

Request:

Response:

Errors:

• agent_id is required: Missing agent_id field
• unauthorized: Caller identity does not match the target agent_id. Only the agent itself may invoke this method.

message.deleteByScope

Daemon-internal only. This method is not callable from external clients — not from the CLI, WebSocket connections, or external unix-socket callers. It is reserved for internal daemon housekeeping operations. The method is not registered on the WebSocket transport at all.

Errors:

• -32601 (Method not found): Returned to any external caller attempting to invoke this method.

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

Internal RPC only. The thrum subscribe, thrum unsubscribe, and thrum subscriptions CLI commands have been removed. From the CLI, use thrum wait to block until a message arrives. These RPC methods remain available for custom clients (MCP server, WebSocket clients, scripts that talk directly to the daemon socket).

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).

Peer Methods (v0.7.0)

peer.start_pairing

Start a pairing session. Returns a code and address for the joining peer.

Request:

Response:

peer.wait_pairing

Block until the active pairing session completes or times out. Long-poll method.

Request: (none)

Response:

pair.request

Low-level handshake RPC invoked by the joining peer against the listener during thrum peer join. Both sides exchange identity metadata at pairing time so the remote's repo name, hostname, repo path, and git origin URL are stored in peers.json for future routing.

All four identity fields are omitempty — an older peer that does not send them produces empty strings in the remote registry. No re-pairing is required for existing peers.

Request:

Response:

peer.join

Connect to a remote peer using a pairing code.

Request:

Response:

peer.list

List all known peers.

Request: (none)

Response: Array of peer objects:

peer.status

Detailed per-peer health including authentication status.

Request: (none)

Response: Array of peer status objects:

peer.remove

Remove a peer by name or daemon ID.

Request:

Response:

peer.configure

Add or remove proxy agents for a peer.

Request:

Response:

peer.address_changed

Notify this daemon that a remote peer's address has changed.

Request:

Response:

peer.repair

Re-establish a known peer relationship after address drift, without re-pairing. Uses the stored bearer token from peers.json as the trust anchor — no new peercode is required. This RPC is distinct from pair.request: it does not mint a new token and does not require an active pairing session.

Invoked automatically by the reconcile package on boot (ReconcileAll) and inline on dial failure (OnDialError). Can also be triggered manually via thrum peer join --type repair <name>.

Auth: Bearer token in the token field (from the stored peers.json entry). Distinct from the peercode used in pair.request.

Request:

Response (RepairResponse):

Error codes:

When to use: After a peer's address drifts (IP change, port reassignment, daemon restart on a different port) and automatic reconciliation has failed. Use thrum peer join --type repair <name> to trigger manually. This RPC is not valid for peer add — only for peer join.

Agent Methods (v0.8.0)

agent.set-status

Set an agent's operational status. The daemon locates the agent's identity file (including across worktrees) and writes the status directly.

Request:

Response:

Errors:

• invalid status "<value>": must be working, idle, or blocked: Invalid status value

Tmux Methods (v0.7.1)

tmux.create

Create a tmux session for an agent with a clean environment and monitor-silence hooks. Also accepts quickstart fields to register an agent identity in the same call (equivalent to running thrum tmux quickstart).

Request:

Response:

tmux.launch

Start an AI tool inside an existing tmux session. Writes tmux_session and runtime to the agent's identity file.

Request:

Response:

tmux.status

List all tmux-managed sessions with agent info and liveness state. Scans identity files in .thrum/identities/ for agents with tmux_session set, then checks session existence and PID liveness.

Request: (none)

Response:

tmux.kill

Tear down a tmux session and clear tmux_session from all matching identity files.

Request:

Response: null

tmux.send

Send text into a tmux session via send-keys.

Request:

Response: null

tmux.capture

Capture the visible content of a tmux pane.

Request:

Response:

tmux.check-pane

Check a tmux pane state. The daemon's SessionPoller calls this internally every ~10 seconds (2-hash stability window) to classify pane state. Direct invocation is supported but unusual — most callers rely on the poller result rather than invoking this RPC manually.

Request:

Note: The reason field accepted by older clients is now daemon-computed, not client-supplied. Clients that send reason will have it ignored.

Response:

State values:

tmux.restart

Restart a tmux-managed agent session with a context snapshot. The daemon picks between two flows based on force:

• Graceful (default) — sends an @system message asking the agent to save its own snapshot, nudges the pane, and polls for the snapshot file up to restart.graceful_timeout seconds. Falls back to JSONL extraction on timeout.
• Force (force: true) — skips the graceful prompt and extracts directly from the JSONL conversation transcript. Only works for Claude Code (other runtimes don't use the same JSONL format).

Either way, the daemon kills the session, creates a new one, and relaunches.

Request:

Response:

Queue Methods (v0.8.0)

tmux.queue

Submit a command to a tmux session's queue. Commands are dispatched FIFO — one at a time. The daemon sends the command to the pane when it goes silent, detects completion via the next silence event, captures output, and optionally sends an @system inbox message to the requester.

Request:

Response:

Errors:

• session is required: Missing session field
• text is required: Missing text field
• requester is required: Missing requester field

@system messages: When notify_on_complete is true, the daemon sends inbox messages from agent "system" for completion, timeout, cancellation, and interruption events. The message includes the command ID, session name, elapsed time, and captured output (last 500 lines). Timeout warnings are sent when the command exceeds its timeout but is still running — the message includes a thrum tmux cancel hint. On daemon restart, interrupted commands always send notifications regardless of notify_on_complete.

tmux.queue-wait

Long-poll until a queued command reaches a terminal state (completed, cancelled, or interrupted). Polls the database every 500ms.

Request:

Response:

States: queued, sent, completed, timeout_waiting, cancelled, interrupted. Terminal states: completed, cancelled, interrupted.

tmux.queue-status

Show the active command and queued commands for a session.

Request:

Response:

tmux.cancel

Cancel a queued or active command.

Request:

Response:

Monitor Methods (v0.9.0)

Monitor methods are Unix socket only — they're not available over WebSocket or via peer/Telegram dispatchers.

monitor.start

Start a new monitor job. Spawns the child process immediately and persists the spec to the monitors table so it survives daemon restarts.

Request:

Response:

Errors:

• name is required: Missing name field
• match is required: Missing match field
• to is required: Missing to field
• argv is required and must not be empty: Missing or empty argv
• cwd is required: Missing cwd field
• invalid regex: match is not a valid RE2 expression
• debounce below minimum (30s): Debounce window shorter than 30 seconds
• max monitors reached: Already at the 100-monitor limit
• agent not found: Recipient agent name is not registered

monitor.list

List monitor jobs.

Request:

Response:

monitor.show

Full detail on a single monitor job.

Request:

Response:

monitor.stop

Stop a running monitor. Sends SIGTERM, waits 5 seconds, sends SIGKILL if still running. Removes the spec from persistence — the monitor won't respawn.

Request:

Response:

Errors:

• monitor not found: No monitor with given ID
• monitor already stopped: Monitor is not running

monitor.logs

Return the last N bytes of captured stdout+stderr from the child process.

Request:

Response:

Errors:

• monitor not found: No monitor with given ID

monitor.restart

Restart a stopped or dead monitor by respawning its child process from the saved spec.

Request:

Response:

Errors:

• monitor not found: No monitor with given ID
• monitor already running: Monitor is currently active

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 internal subscribe RPC method and Broadcaster

References

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