Clawfinger

Clawfinger Plugin

Real-time bridge to the Clawfinger voice gateway. Gives you full control over active phone calls: take over the LLM, inject speech, push context, observe transcripts, and manage call policy.

Available Tools

Status and Observation

Call Control

Context and Instructions

Configuration

WS Bridge

The plugin maintains a persistent WebSocket connection to the gateway at /api/agent/ws. The bridge:

• Auto-reconnects with exponential backoff (1s -> 30s max)
• Sends ping heartbeats every 15s
• Receives all gateway events (turn.*, agent.*, config.*, etc.)
• Handles request_id correlation for takeover turn replies

The bridge starts automatically when the plugin loads and stops when it unloads.

WS Event Envelope Format

All events from the gateway use a nested envelope. The top-level JSON has type, timestamp, session_id, and a data object containing the event-specific fields:

{
  "type": "turn.transcript",
  "timestamp": 1708700000.123,
  "session_id": "abc123def456",
  "data": {
    "transcript": "what the caller actually said"
  }
}

Common event payloads (fields inside data):

Important: Always read event-specific fields from event.data, not from the top level. For example, to get the transcript text: event.data.transcript, not event.transcript.

Takeover Lifecycle

1. Observe — Use clawfinger_status and clawfinger_sessions to see active calls.
2. Inspect — Use clawfinger_call_state to read conversation history and current instructions.
3. Prepare — Optionally use clawfinger_context_set to inject knowledge the LLM should have.
4. Take over — Call clawfinger_takeover with the session ID. The gateway will now route caller transcripts to you instead of the local LLM.
5. Respond — When you receive a turn.request event with a transcript, the bridge sends your reply back with request_id correlation for reliable matching.
6. Release — Call clawfinger_release to hand control back to the local LLM.

During takeover, if you fail to reply within 30 seconds, the gateway falls back to the local LLM for that turn.

Example Workflows

Monitor and inject context

1. clawfinger_status          -> check gateway is healthy
2. clawfinger_sessions        -> get active session IDs
3. clawfinger_call_state      -> read conversation history
4. clawfinger_context_set     -> push relevant knowledge
   (LLM now has your context for all subsequent turns)

Full call takeover

1. clawfinger_sessions        -> find the active session
2. clawfinger_takeover        -> take LLM control
3. clawfinger_turn_wait       -> blocks until caller speaks, returns transcript + request_id
4. clawfinger_turn_reply      -> send your response with the request_id
   (repeat 3-4 for each turn)
5. clawfinger_release         -> hand back to local LLM

Outbound call with greeting

1. clawfinger_instructions_set  -> set instructions for the call
2. clawfinger_dial              -> dial the number
3. clawfinger_sessions          -> find the new session
4. clawfinger_context_set       -> push context for the LLM

Slash Command

All gateway operations are also available as direct /clawfinger subcommands that bypass the LLM: