llm-worker-rs/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code when working with code in this repository.

Development Commands

• Build: cargo build --workspace or cargo check --workspace for quick validation
• Tests: cargo test --workspace (note: tests currently fail due to unsafe environment variable operations)
• Fix warnings: cargo fix --lib -p worker
• Dev environment: Uses Nix flake - run nix develop to enter dev shell with Rust toolchain

Architecture Overview

This is a Rust workspace implementing a multi-LLM worker system with tool calling capabilities. The architecture follows the Core Crate Pattern to avoid circular dependencies:

Workspace Structure

• worker-types: Core type definitions (Tool trait, Message, StreamEvent, hook types) - foundational types used by all other crates
• worker-macros: Procedural macros (#[tool], #[hook]) for automatic Tool and WorkerHook trait implementations
• worker: Main library containing Worker struct, LLM clients, prompt composer, and session management

Key Components

Worker: Central orchestrator that manages LLM interactions, tool execution, and session state. Supports streaming responses via async streams.

LLM Providers: Modular clients in worker/src/llm/ for:

• Anthropic (Claude)
• Google (Gemini)
• OpenAI (GPT)
• xAI (Grok)
• Ollama (local models)

Tool System: Uses #[tool] macro to convert async functions into LLM-callable tools. Tools must return ToolResult<T> and take a single struct argument implementing Deserialize + Serialize + JsonSchema.

Hook System: Uses #[hook] macro to create lifecycle event handlers. Hook functions take HookContext and return (HookContext, HookResult) tuple, supporting events like OnMessageSend, PreToolUse, PostToolUse, and OnTurnCompleted with regex matcher support.

Prompt Management: Handlebars-based templating system for dynamic prompt generation based on roles and context.

MCP Integration: Model Context Protocol support for external tool server communication.

Development Notes

• Edition 2024 Rust with async/await throughout
• Uses tokio for async runtime and reqwest for HTTP clients
• Environment-based configuration for API keys and base URLs
• Session persistence using JSON serialization
• Streaming responses via futures-util streams
• Current test suite has unsafe environment variable operations that need unsafe blocks to compile

Important Patterns

• Error Handling: ToolResult<T> for tools, WorkerError for library operations with automatic conversions
• Streaming: All LLM interactions return StreamEvent streams for real-time UI updates
• Tool Registration: Dynamic tool registration at runtime using boxed trait objects
• Hook Registration: Dynamic hook registration with lifecycle event filtering and regex matching
• Core Crate Pattern: worker-macros references worker-types directly via complete paths to prevent circular dependencies