catclaw: Instructions file for Claude Code

CatClaw — Development Guide

Project Overview

Rust gateway for Claude Code CLI — multi-agent, multi-channel (Discord/Telegram/Slack/TUI), session management with tool approval system.

Architecture

Channel Adapters (Discord/Telegram/Slack) → MsgContext → MessageRouter → SessionManager → ClaudeHandle (claude -p subprocess)
                                                      ↑
                                        WS Server ← TUI/WebUI (GatewayClient)
                                        MCP Server ← Claude CLI (tool calls)

Key Design Patterns

• Hot-reload: Config changes go through WS config.set → gateway applies immediately. Agent tool/approval changes go through agents.reload_tools.
• Shared state: Config uses Arc<RwLock<Config>>, AgentRegistry uses Arc<RwLock<AgentRegistry>>, AdapterFilter uses Vec<Arc<RwLock<AdapterFilter>>>. All hot-reloadable.
• Approval system: PreToolUse hook → WS approval.request → broadcast to TUI + forward to origin channel → user approves/denies → hook receives result.
• Session metadata: JSON in metadata column stores model, channel_id, sender_id. Use SessionRow helper methods.
• Channel adapters: ChannelAdapter trait with send_approval() default method. Discord uses embed+buttons, Telegram uses inline keyboard, Slack uses Block Kit buttons.
• Streaming: ChannelCapabilities.streaming flag. Slack supports native AI streaming (chat.startStream/appendStream/stopStream). Adapters implement optional send_stream_start()/send_stream_append()/send_stream_stop() methods.

Critical Rules

RwLockReadGuard Across Await

NEVER hold a std::sync::RwLockReadGuard across an .await point — it's not Send and will fail to compile inside tokio::spawn. Always extract to a local variable first:

// WRONG: guard lives across await
if let Some(agent) = registry.read().unwrap().get(&id).cloned() {
    do_something(agent).await;  // guard still alive here!
}

// RIGHT: drop guard before await
let agent = registry.read().unwrap().get(&id).cloned();
if let Some(agent) = agent {
    do_something(agent).await;
}