CrabTalkProtocol
The CrabTalk wire protocols — crabtalk.proto for clients, ext.proto for extensions, dual UDS and TCP transport.
CrabTalk uses two protobuf protocols over two transports. Clients (CLI, gateway) speak crabtalk.proto. Extensions (memory, search) speak ext.proto.
Two protocols
crabtalk.proto (client-daemon)
Used by crabtalk attach, the gateway service, and custom clients:
- Send chat messages to agents
- Stream responses (text deltas, tool calls, completions)
- Manage sessions, config, and agent state
ext.proto (daemon-extension)
Used by extensions (crabtalk-search, custom extensions):
- Capability handshake at startup
- Tool schema registration
- Tool call dispatch and results
- Lifecycle callbacks (BuildAgent, BeforeRun, Compact, EventObserver, AfterRun, Infer, AfterCompact)
Transport
Unix domain socket
The daemon listens on ~/.crabtalk/crabtalk.sock. The CLI connects to this socket by default:
crabtalk attach ──→ crabtalk.sock ──→ crabtalk daemonOverride the socket path:
crabtalk --socket /path/to/custom.sock attachTCP
The daemon also listens on TCP (localhost by default). The port is written to ~/.crabtalk/crabtalk.tcp:
crabtalk attach --tcpTCP is used by the gateway service and enables remote connections.
Extension kinds
| Kind | Protocol | Direction | Example |
|---|---|---|---|
extension | ext.proto (UDS) | Daemon → extension | crabtalk-search |
gateway | crabtalk.proto (TCP) | Service → daemon | crabtalk-telegram |
Capabilities handshake
Extensions declare capabilities at startup via ExtReady:
| Capability | Description |
|---|---|
| Tools | Provides tool schemas that agents can call |
| BuildAgent | Enriches agent config at creation |
| BeforeRun | Injects context before each agent execution |
| Compact | Enhances context compaction prompts |
| EventObserver | Observes agent lifecycle events |
| AfterRun | Runs after each agent execution completes |
| Infer | Requests LLM inference from the daemon |
| AfterCompact | Runs after context compaction completes |
| Query | Responds to structured queries |
Wire format
Both protocols use length-prefixed protobuf 3 frames over the transport. The crabtalk-socket and crabtalk-tcp crates handle framing and codec.
Building on the protocol
Connect directly using the crabtalk-socket crate:
use crabtalk_socket::CrabTalkClient;
let client = CrabTalkClient::connect("/path/to/crabtalk.sock").await?;What's next
- CLI reference — commands that use the protocol
- Event loop — how the daemon processes messages
- Extensions — extension architecture and lifecycle
- Hooks — how hooks compose with extensions