Introduction to caro

caro is a Rust CLI tool that converts natural language descriptions into safe, POSIX-compliant shell commands using local LLMs.

What is caro?

Instead of memorizing complex command syntax or searching Stack Overflow, simply describe what you want to do:

$ caro "find all log files larger than 100MB"
find . -name "*.log" -size +100M

$ caro "show processes using port 3000"
lsof -i :3000

$ caro "compress all jpg files in current directory"
tar -czvf images.tar.gz *.jpg

Key Features

Local LLM Inference

All processing happens on your machine. No cloud API, no data leaving your computer.

Safety Validation

Dangerous commands are detected and blocked before you can execute them.

Apple Silicon Optimized

GPU acceleration via MLX for fast inference on M1/M2/M3/M4 Macs.

Multi-Backend Support

Works with MLX, Ollama, and vLLM for flexible deployment options.

How It Works

You describe what you want to accomplish in plain English
caro sends your description to a local LLM (no internet required)
The LLM generates a POSIX-compliant shell command
Safety validation checks for dangerous patterns
You review the command before execution

┌─────────────────┐     ┌─────────────┐     ┌──────────────┐
│  Natural        │────▶│  Local LLM  │────▶│   Safety     │
│  Language       │     │  (MLX/etc)  │     │  Validation  │
└─────────────────┘     └─────────────┘     └──────────────┘
                                                   │
                                                   ▼
                                           ┌──────────────┐
                                           │ Shell Command │
                                           │  (reviewed)   │
                                           └──────────────┘

Safety First

caro prioritizes safety with multiple layers of protection:

Risk Level	Color	Description
Safe	Green	Normal operations like listing files
Moderate	Yellow	Operations that modify files
High	Orange	System-level changes
Critical	Red	Blocked - dangerous commands

Blocked patterns include:

rm -rf / and variations
Fork bombs (:(){:|:&};:)
Disk destruction (dd if=/dev/zero)
System path modifications

Performance

Backend	First Inference	Subsequent	Best For
MLX (GPU)	< 2s	< 500ms	Apple Silicon Macs
Ollama	~3s	~2s	Cross-platform
vLLM	~2s	~1s	Server deployment

Next Steps

Ready to get started?

Installation - Install caro on your system
Quick Start - Learn the basics with examples
macOS Setup - Optimize for Apple Silicon