RustFox: Instructions file for Claude Code

CLAUDE.md - RustFox Development Guide

Project Overview

RustFox is a Telegram AI assistant written in Rust. It connects to Telegram as a bot, uses OpenRouter LLM for inference (default model: qwen/qwen3-235b-a22b), provides built-in sandboxed tools (file I/O, command execution), and supports MCP (Model Context Protocol) servers for extensible tool integration. It implements an agentic loop that iterates tool calls until a final text response is produced (max iterations configurable, default 25).

Build & Run

# Build (debug)
cargo build

# Build (release)
cargo build --release

# Run (uses ./config.toml by default)
cargo run

# Run with custom config path
cargo run -- /path/to/config.toml

# Check without building
cargo check

# Format code
cargo fmt

# Lint
cargo clippy

Configuration

Copy config.example.toml to config.toml and fill in credentials. The config.toml file is gitignored and must never be committed. Required fields:

• telegram.bot_token - Telegram Bot API token
• telegram.allowed_user_ids - Whitelist of Telegram user IDs
• openrouter.api_key - OpenRouter API key
• sandbox.allowed_directory - Directory for sandboxed file/command operations

Home directory

RustFox stores all state under a single home directory (default ~/.rustfox), resolved as: RUSTFOX_HOME env (absolute) → [general].home config → ~/.rustfox. Layout: config.toml, rustfox.db, skills/, agents/, workspace/ (the sandbox), artifacts/, user_model.md. Each path can be pinned to an absolute location in config.toml; unset paths fall back to the home default. Run isolated instances with RUSTFOX_HOME=.... See docs/persistent-home-directory.md. Path resolution lives in src/home.rs (Config::resolve writes the resolved absolute paths back into the config). Bundled skills/agents are seed-copied on first run; /update-skills re-syncs them using <home>/skills-lock.json.

Architecture

src/
├── main.rs      # Entry point: logging init, config loading, MCP setup, bot launch
├── config.rs    # TOML config parsing (Config, TelegramConfig, OpenRouterConfig, SandboxConfig, McpServerConfig)
├── llm.rs       # OpenRouter API client (ChatMessage, ToolCall, ToolDefinition, LlmClient)
├── tools.rs     # Built-in tool definitions and execution with sandbox path validation
├── mcp.rs       # MCP client manager (McpManager, McpConnection) for external tool servers
└── bot.rs       # Telegram bot handler: message routing, agentic loop, conversation state