Welcome to Caro
Relevant source files
The following files were used as context for generating this wiki page:- CONTRIBUTING.md
- presentation/slides.md
- ROADMAP.md
- website/index.html
- exports/session-logs/2025-09-13-readme.txt
- mlx-test/START_HERE.md
- specs/003-implement-core-infrastructure/spec.md
- specs/005-karo-distributed-mesh/spec.md
- website/IMPROVEMENT_PLAN.md
- presentation/roadmap-slides.md
- docs-site/README.md
Caro is a safety-first, high-performance CLI tool that converts natural language descriptions into executable POSIX shell commands. It is designed to be a "loyal shell companion," leveraging local Large Language Models (LLMs) to make terminal interactions safer, faster, and more accessible. The project prioritizes user trust and security, following BSD/GNU-level security practices to prevent accidental data loss or system damage.
The core mission is to democratize command-line expertise by providing a safe intelligence layer for AI-to-terminal interactions. Caro is built with Rust for performance and is designed to be a single, self-contained binary with minimal dependencies. It operates local-first, with no cloud dependencies, and can work entirely offline with cached models.
Core Principles & Features
Caro's development is guided by several key principles that translate into its core features.
| Principle | Description | Key Features |
|---|---|---|
| Safe by Default | Comprehensive validation prevents destructive operations. Caro is a security-critical tool. | Dangerous pattern detection (52+ patterns), user confirmation workflows, risk level assessment. |
| Blazingly Fast | Optimized for performance on modern hardware. | Sub-100ms startup time, sub-2s inference on Apple Silicon. |
| Truly Local | No cloud dependencies, respecting user privacy and enabling offline use. | Embedded MLX (Apple Silicon) & Candle (CPU) backends, local model caching. |
| Developer-Friendly | Minimal configuration and clear error messaging. | Single binary distribution, zero-config default setup. |
| Community-Driven | Open development process and transparent governance. | AGPL-3.0 license, public roadmap, community-validated safety rules. |
Sources: CONTRIBUTING.md:25-33, presentation/slides.md:29-53, website/index.html:301-325
System Architecture
Caro is designed with a modular, layered architecture that prioritizes safety and flexibility. The command generation process flows through several key components, ensuring that any command is validated before it is presented to the user for execution.
This diagram shows the data flow from user input to final shell execution or clipboard copy.
Key Components
- Safety Validator: The first and most critical layer. It checks the user's natural language prompt and the generated command against a database of dangerous patterns.
- Risk Assessment: Classifies the generated command into risk levels (e.g., Safe, Moderate, High, Critical) and determines if user confirmation is required.
- Backend Router: Selects the appropriate LLM backend for inference based on user configuration and platform capabilities.
- Command Generator: The LLM backend that translates the natural language prompt into a shell command.
- POSIX Validator: Ensures the generated command is compliant with POSIX standards for cross-platform compatibility.
- Execution Engine: The final stage that, with user consent, executes the command in the shell.
Sources: presentation/slides.md:111-136, specs/001-create-a-comprehensive/tasks.md:81-84, exports/session-logs/2025-09-13-readme.txt:203-214
Safety-First Design
Safety is the most critical aspect of Caro. The system is designed with the awareness that LLMs can and do make mistakes. A core finding during development was that the model could mark a destructive command like rm -rf / as "Safe". Therefore, Caro employs an independent, multi-layered safety validation system.
Sources: presentation/slides.md:163-171, mlx-test/START_HERE.md:73-75
Security Principles
- Defense in Depth: Multiple validation layers (parsing, safety checks, execution confirmation). The system fails securely by blocking any command it is uncertain about.
- Input Validation: All LLM output is treated as untrusted. Generated commands are validated against safety patterns, and arguments are sanitized.
- Secure Defaults: The default safety level is "moderate," which blocks most dangerous operations and requires confirmation for others. Auto-execution is disabled by default.
Sources: CONTRIBUTING.md:200-220
Risk Levels and Actions
Caro categorizes commands into different risk levels, each triggering a specific action.
| Risk Level | Example Patterns | Default Action |
|---|---|---|
| 🔴 Critical | rm -rf /, mkfs.*, dd if=.*of=/dev/ | Blocked |
| 🟠 High | rm -rf on non-system dirs, chmod 777, package installation | Confirmation Required |
| 🟡 Moderate | File copying/moving, archive operations, permission changes | Warn |
Sources: presentation/slides.md:140-159
The following diagram illustrates the safety validation workflow.
Backend System
Caro supports multiple LLM backends to provide flexibility for different platforms and use cases. The default experience is designed to work out-of-the-box with zero configuration.
| Backend | Platform | Type | Key Feature |
|---|---|---|---|
| MLX | macOS (Apple Silicon) | Embedded | Metal GPU acceleration, <2s inference, 100% offline. |
| Candle | Linux / Windows | Embedded | Pure Rust CPU inference, cross-platform, 100% offline. |
| Ollama | Cross-platform | Remote | Connects to a local Ollama server for flexible model serving. |
| vLLM | Cross-platform | Remote | Connects to a remote/cloud vLLM instance for larger models. |
Sources: presentation/slides.md:208-230, exports/session-logs/2025-09-13-readme.txt:120-146
Configuration
Users can configure backends via a TOML file located at ~/.config/caro/config.toml.
# ~/.config/caro/config.toml
[backend]
primary = "embedded" # auto-detected
enable_fallback = true
[backend.embedded]
model = "qwen2.5-coder-1.5b-q4"
variant = "mlx" # or "cpu"
[backend.ollama]
base_url = "http://localhost:11434"
model_name = "codellama:7b"
enabled = false
Sources: presentation/slides.md:232-251
Development Roadmap (2026)
The project has a structured roadmap for 2026, focusing on foundational improvements, a public launch, and future innovation.
This Gantt chart provides a high-level overview of the major release milestones.
Release Milestones
- v1.1.0 - Core Improvements (GA): Due Feb 15, 2026. Focus on production-ready core functionality, including Hugging Face model downloads, performance optimization, and an LLM evaluation harness.
- v1.2.0 - Website & Documentation Launch: Due Mar 31, 2026. Focus on public launch, marketing, and creating a comprehensive documentation site with Astro Starlight.
- v2.0.0 - Advanced Features: Due Jun 30, 2026. Focus on innovation, including a distributed intelligence system, voice synthesis for the Caro character, and an advanced rule engine.
Sources: ROADMAP.md:46-150, presentation/roadmap-slides.md:51-119
Community and Contribution
Caro is an open-source project licensed under AGPL-3.0, with a dual-licensing strategy for enterprise adoption. The project encourages community involvement, especially in defining safety patterns.
Contribution Areas
- Safety Patterns: Submit dangerous commands and validation patterns.
- Backend Implementations: Add support for new LLM backends.
- Documentation: Improve user guides, API docs, and tutorials.
- Testing: Expand contract, integration, and property-based test coverage.
Sources: CONTRIBUTING.md:589-668
Community Governance
A future goal is to establish a "Safety Council" for democratic decision-making on new safety rules.
This diagram shows the proposed flow for community-driven safety pattern validation.
Sources: presentation/slides.md:313-327
Conclusion
Caro is an ambitious project aiming to fundamentally improve the safety and accessibility of the command line through AI. With a strong emphasis on local-first operation, user privacy, and a robust, independent safety validation system, it provides a trustworthy tool for developers and system administrators. The clear architectural design and public roadmap invite community participation in building the future of safe AI-shell interaction.
Sources: CONTRIBUTING.md:25-33, website/IMPROVEMENT_PLAN.md:168-174