Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:The caro project is a Rust-based CLI tool designed to convert natural language descriptions into safe, executable POSIX shell commands using local LLMs. The architecture is fundamentally driven by principles of safety, performance, and modularity. It is designed as a single binary with a library-first approach, ensuring that core logic is reusable and testable outside the CLI context.
The system prioritizes safety by implementing a robust validation pipeline that checks all generated commands against a database of dangerous patterns before execution. It supports multiple LLM backends through a trait-based system and is optimized for local, offline-first execution, with a particular focus on performance on Apple Silicon via MLX.
Sources: CONTRIBUTING.md:16-24, specs/001-create-a-comprehensive/plan.md:29-35, HANDBOOK.md:12-28
Core Architectural Principles
The development and architecture of caro are guided by a set of core values that ensure the project remains robust, secure, and maintainable.
- Safety First, Always: Every feature is designed with a "how could this go wrong?" mindset. Dangerous operations are blocked by default, and user confirmation is required for any potentially risky commands. This principle is reflected in the mandatory safety validation pipeline.
- Library-First Architecture: All core features are implemented as self-contained libraries and exported via
src/lib.rs. The main binary insrc/main.rsacts as an orchestrator, consuming these libraries. This enforces separation of concerns and enhances testability. - Test-Driven Development (TDD): The project follows a strict Red-Green-Refactor cycle. Contract tests are written before implementation to validate public APIs against their specifications. This is a non-negotiable aspect of the development process.
- Spec-Driven Development: Major features are planned in detail within the
specs/directory before implementation begins. This includes defining API contracts, data models, and user scenarios, enabling parallel work and clear goals. - Async-First: The project defaults to asynchronous communication and workflows to respect contributor time zones and enable focused, deep work.
Sources: CONTRIBUTING.md:113-125, specs/002-implement-tdd-green/plan.md:62-74, HANDBOOK.md:31-105
Project Structure
The project is organized as a single Rust binary with a modular src directory. This structure supports the library-first principle, with distinct modules for each core piece of functionality.
This diagram illustrates the high-level directory and module structure.
Core Modules
The application is composed of several distinct modules, each with a specific responsibility.
| Module | Responsibility | Source Files |
|---|---|---|
| CLI | Parses command-line arguments using clap and orchestrates the application flow. | src/main.rs, src/cli/ |
| Models | Defines core data structures like CommandRequest and GeneratedCommand. | src/models/ |
| Backends | Provides a unified interface (CommandGenerator trait) for various LLM inference engines. | src/backends/ |
| Safety | Validates generated commands against a database of dangerous patterns. | src/safety/ |
| Cache | Manages downloading and local caching of Hugging Face models. | src/cache/ |
| Config | Handles user configuration from TOML files, respecting XDG standards. | src/config/ |
| Execution | Captures the user's environment (shell, OS, CWD) to create context-aware commands. | src/execution/ |
| Logging | Implements structured, asynchronous logging using the tracing crate. | src/logging/ |
Sources: specs/001-create-a-comprehensive/tasks.md:43-50, specs/003-implement-core-infrastructure/spec.md:129-168, specs/002-implement-tdd-green/plan.md:88-105
Backend System
The backend system is designed to be extensible, allowing different LLM inference engines to be used for command generation. This is achieved through the CommandGenerator trait.
The diagram below shows the trait and its planned implementations.
A BackendFactory is responsible for selecting and instantiating the appropriate backend based on user configuration or platform defaults. The MLX backend is prioritized for Apple Silicon, while others like Ollama and vLLM provide cross-platform and remote inference capabilities.
Sources: specs/002-implement-tdd-green/plan.md:21-28, 221-228, exports/session-logs/2025-09-13-readme.txt
Safety Validation System
Safety is the cornerstone of caro's architecture. The SafetyValidator module intercepts every command generated by a backend before it is presented to the user or executed.
The validation process follows these steps:
The system uses a database of regex patterns to identify potentially harmful operations, such as rm -rf /, fork bombs, or direct writes to block devices. The risk is categorized into levels (Safe, Moderate, High, Critical), and the system's action is determined by the user's configured SafetyLevel (Strict, Moderate, Permissive).
Sources: CONTRIBUTING.md:127-142, specs/001-create-a-comprehensive/tasks.md:29-32, specs/002-implement-tdd-green/plan.md:16-20
End-to-End Data Flow
The following sequence diagram illustrates the complete workflow from a user's prompt to the final command output.
This flow demonstrates the orchestration of multiple modules to fulfill a single user request, highlighting the separation of concerns and the critical safety checks integrated into the pipeline.
Sources: specs/002-implement-tdd-green/plan.md:144-154, specs/003-implement-core-infrastructure/spec.md:57-81
Data Models
The system relies on a set of core data structures to pass information between modules.
| Entity | Description | Key Fields |
|---|---|---|
| CommandRequest | Represents the user's initial request to the system. | input: String, shell_type: ShellType, safety_level: SafetyLevel |
| GeneratedCommand | The command produced by an LLM backend. | command: String, explanation: String, risk_level: RiskLevel |
| UserConfiguration | User-defined preferences loaded from a TOML file. | default_shell: ShellType, safety_level: SafetyLevel, default_model: String |
| ExecutionContext | Snapshot of the user's environment at invocation time. | cwd: PathBuf, shell: ShellType, platform: Platform |
| CachedModel | Metadata for a model stored in the local cache. | model_id: String, path: PathBuf, checksum: String |
Sources: specs/001-create-a-comprehensive/tasks.md:16-23, specs/003-implement-core-infrastructure/spec.md:171-189
Conclusion
The architecture of caro is intentionally designed to be safe, modular, and performant. By separating concerns into distinct libraries (backends, safety, caching, configuration), the system is both testable and extensible. The library-first approach, combined with strict Test-Driven and Spec-Driven Development methodologies, ensures a high-quality, reliable codebase. The mandatory safety validation pipeline is the most critical architectural feature, positioning caro as a trustworthy tool for developers interacting with AI-powered command-line generation.