55 lines
2.9 KiB
Markdown
55 lines
2.9 KiB
Markdown
# 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 |