# 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