v1.5.0

Explore Caro

Your loyal companion for safe shell command generation. Published on crates.io with core features working - advanced features in active development.

Get Started See Examples

🚀 Get Started 💻 Use Cases 🔌 Integration 🛡️ Safety ⚙️ Backends 📦 Install

Choose Your Path

Get started with Caro based on your workflow and goals

👨‍💻

Try Caro Today

Get started with the core CLI tool - install via cargo and start generating safe commands

1 Install with: cargo install caro

2 Try: caro 'list all files larger than 1GB'

3 Review the generated command with safety validation

4 Execute or customize as needed

Installation Guide →

🍎

Apple Silicon Users

In Development

Early access to MLX-optimized inference for blazing-fast local command generation

1 Build from source with MLX support (in development)

2 Experience sub-2s inference on M1/M2/M3

3 Run completely offline with local models

4 Help us test and improve performance

MLX Details →

🤖

Claude Integration

Skill Available

Install Caro as a Claude Skill, or use the upcoming MCP server for automatic delegation

1 Install with: /plugin install wildcard/caro

2 Use /caro-shell-helper for command generation

3 MCP server integration (coming soon)

4 Automatic safety validation for Claude's workflows

Integration Methods →

🔧

Advanced Setups

Connect to remote inference servers or configure custom backends

1 Use Ollama for local multi-model support

2 Connect to vLLM servers for team deployments

3 Configure backends in ~/.config/caro/config.toml

4 Automatic fallback to embedded CPU backend

Backend Config →

Use Cases

Real-world examples of safe, POSIX-compliant commands generated by Caro

📁

File Management

You: Find all files larger than 1GB

find . -type f -size +1G -exec ls -lh {} \; ✓ Safe

You: List all PNG images modified in the last 7 days

find . -name '*.png' -type f -mtime -7 ✓ Safe

You: Show disk usage of each directory sorted by size

du -h --max-depth=1 | sort -hr ✓ Safe

📊

System Monitoring

You: Show top 10 memory-consuming processes

ps aux --sort=-%mem | head -n 11 ✓ Safe

You: Monitor CPU usage in real-time

top -b -n 1 | head -n 20 ✓ Safe

You: Check which process is using port 8080

lsof -i :8080 ✓ Safe

🔀

Git & Version Control

You: Show commits from the last week

git log --since='1 week ago' --oneline ✓ Safe

You: List all branches sorted by last commit date

git for-each-ref --sort=-committerdate refs/heads/ --format='%(committerdate:short) %(refname:short)' ✓ Safe

You: Find who changed a specific file

git log --follow -p -- <filename> ✓ Safe

📝

Log Analysis

You: Find all ERROR entries in application logs

grep -i 'error' /var/log/app.log | tail -n 50 ✓ Safe

You: Count HTTP status codes in access log

awk '{print $9}' /var/log/nginx/access.log | sort | uniq -c | sort -rn ✓ Safe

You: Show last 100 system errors

journalctl -p err -n 100 ✓ Safe

🌐

Network Operations

You: Test connection to a remote server

ping -c 4 example.com ✓ Safe

You: Show all listening TCP ports

ss -tlnp ✓ Safe

You: Download a file with resume support

wget -c https://example.com/file.tar.gz ✓ Safe

✂️

Text Processing

You: Extract unique email addresses from a file

grep -Eo '\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b' file.txt | sort -u ✓ Safe

You: Count lines, words, and characters in all .txt files

wc $(find . -name '*.txt') ✓ Safe

You: Replace all occurrences in multiple files

sed -i 's/old_text/new_text/g' *.txt ⚠ Moderate

Integration Methods

Choose how you want to work with Caro - standalone, with Claude, or both

⌨️

Standalone CLI

Available Now

Use Caro directly from your terminal for instant command generation

Features

Direct command-line interface
Interactive confirmation prompts
Customizable safety levels
Shell alias support

Basic Usage

# Generate a command
caro "find all Python files modified today"

# Review the command
find . -name "*.py" -type f -mtime 0

# Execute (after confirmation)
[y/N]? y

Setup

Install Caro from source or download the binary
Add to PATH or create shell alias
Configure backend preferences (optional)
Start using: caro "your natural language prompt"

🔌

Claude MCP Server

Coming Soon

Integrate Caro as an MCP server for seamless Claude Desktop integration

Features

Automatic delegation from Claude
Safety validation without interruption
Context-aware command generation
Shared conversation history

MCP Configuration

// claude_desktop_config.json
{
  "mcpServers": {
    "caro": {
      "command": "caro",
      "args": ["--mcp"],
      "env": {
        "CARO_BACKEND": "mlx"
      }
    }
  }
}

Setup

Install Caro MCP package
Configure Claude Desktop settings
Enable Caro MCP server
Claude automatically uses Caro for shell commands

🎯

Dedicated Skill

Available Now

Use Caro as a specialized skill within Claude's broader workflow

Features

Explicit skill invocation
Specialized shell expertise
Multi-turn command refinement
Batch command generation

Skill Installation

# Install Caro as a Claude skill
/plugin install wildcard/caro

# Use the skill
You: /caro-shell-helper "find large log files and compress them"

Caro: I'll generate a safe command for that:

find /var/log -name "*.log" -size +100M \
  -exec gzip {} \;

Risk Level: Moderate
- Modifies files (compression)
- Targets system logs

Proceed? [y/N]

Setup

Install with: /plugin install wildcard/caro
Invoke with /caro-shell-helper command
Provide natural language description
Review and approve generated commands

Safety First

Caro's multi-layered safety validation protects you from dangerous commands

How Safety Validation Works

Command Generation

LLM generates POSIX-compliant command from natural language

→

Pattern Matching

Check against 52 dangerous patterns and destructive operations

→

Risk Assessment

Evaluate potential impact and assign risk level (Safe → Critical)

→

User Confirmation

Display command with risk level, require explicit confirmation

→

Execution

Execute command only after user approval, log for audit trail

🛡️

50+ Dangerous Patterns Detected

Built-in pattern matching helps identify potentially destructive operations

Example Blocked Patterns

rm -rf /

Filesystem destruction critical

mkfs.*

Disk formatting critical

:(){ :|:& };:

Fork bomb critical

chmod 777 /

Privilege escalation high

dd if=/dev/zero

Disk overwrite critical

📊

Risk Level Assessment

Every command is evaluated and color-coded based on potential impact

Safe

Read-only operations with no system impact

ls -lagrep pattern file.txtfind . -name '*.log'

Moderate

File modifications or network operations

sed -i 's/old/new/g' file.txtwget https://example.com/filecurl -X POST api.example.com

High

System-level changes requiring caution

chmod +x script.shchown user:group filekill -9 <pid>

Critical

Dangerous operations that are blocked by default

rm -rf /mkfs /dev/sdafork bombs

✅

POSIX Compliance Validation

Ensures commands work reliably across different systems and shells

Standard utilities only (ls, find, grep, awk, sed)
Proper path quoting for spaces and special characters
No bash-specific features (ensures portability)
Command syntax validation before execution

Choose Your Backend

Flexible inference options from ultra-fast local to scalable cloud deployments

🍎

llama.cpp (Metal)

Apple Silicon Native

Available

High-performance local inference using llama.cpp with Metal GPU acceleration on Apple Silicon

Key Features

Metal GPU acceleration on M1/M2/M3/M4 chips
GGUF model format for efficient quantization
Complete offline capability
Privacy-focused (no data leaves your machine)
Unified memory architecture for efficiency

Performance

Startup < 500ms

Inference < 2s

Memory ~2GB with 7B model

Quick Setup

Build with: cargo build --features embedded-mlx
Download a GGUF model (e.g., from Hugging Face)
Configure model path in caro config
Test: caro "list files"

Best For

macOS users with Apple SiliconPrivacy-conscious developersOffline workflowsLow-latency requirements

🌐

Exo Cluster

Distributed Inference

Available

Connect to Exo distributed clusters for running large models across multiple devices

Key Features

Distributed inference across multiple devices
RDMA over Thunderbolt for high-speed communication
Run large models (e.g., llama-3.1-405b) across clusters
Automatic peer discovery on local networks
OpenAI-compatible API

Performance

Startup < 200ms (client)

Inference 2-5s (cluster dependent)

Memory Distributed across cluster

Quick Setup

Set up Exo cluster (github.com/exo-explore/exo)
Configure endpoint: caro config set exo.url http://localhost:52415
Select model: caro config set exo.model llama-3.2-3b
Test connection: caro "echo hello"

Best For

Running large models locallyMulti-device setupsApple Silicon clustersHigh-performance inference

🚀

vLLM

High-Throughput Server

Untested

Connect to vLLM servers for production-grade inference with optimized performance

Key Features

PagedAttention for efficient memory
Continuous batching for throughput
Multi-GPU support
OpenAI-compatible API
Production-ready deployment

Performance

Startup < 150ms (client)

Inference < 5s (network dependent)

Memory Server-side (client is lightweight)

Quick Setup

Deploy vLLM server (Docker/k8s recommended)
Configure endpoint: caro config set vllm.url https://api.example.com
Set API key: caro config set vllm.api_key YOUR_KEY
Test connection: caro "echo hello"

Best For

Team deploymentsCentralized inferenceHigh-throughput scenariosCloud-based workflows

🦙

Ollama

Local Model Management

Planned

Connect to Ollama for local LLM inference with easy model management

Key Features

Cross-platform (macOS, Linux, Windows)
Simple model management (ollama pull/list)
Multiple model support (Llama, Mistral, etc.)
GPU acceleration (CUDA, Metal)
Active community and ecosystem

Performance

Startup < 200ms

Inference 2-5s (hardware dependent)

Memory Varies by model

Quick Setup

Install Ollama from ollama.ai
Pull a model: ollama pull llama2
Configure Caro: caro config set backend ollama
Specify model: caro config set ollama.model llama2

Best For

Cross-platform developmentModel experimentationLocal-first workflowsGPU-accelerated inference

🖥️

LM Studio

Desktop LLM Runner

Planned

Connect to LM Studio's local server for a GUI-based local model experience

Key Features

User-friendly desktop application
Easy model discovery and download
Local inference with GPU support
OpenAI-compatible API server
Cross-platform (macOS, Windows, Linux)

Performance

Startup < 200ms (client)

Inference 2-5s (hardware dependent)

Memory Varies by model

Quick Setup

Download LM Studio from lmstudio.ai
Download and load a model in LM Studio
Start the local server in LM Studio
Configure Caro: caro config set backend lmstudio

Best For

GUI model managementEasy setup experienceLocal-first workflowsDesktop users

📦

CPU Backend

Built-in Fallback

In Development

Cross-platform CPU-based inference using Candle (currently in development)

Key Features

Cross-platform (macOS, Linux, Windows)
No GPU required
Candle-based inference engine
Automatic fallback option
Works on any hardware

Performance

Startup < 50ms

Inference 5-15s

Memory < 500MB

Quick Setup

Build with default features
Configure model path in caro config
Will be used automatically as fallback

Best For

Older hardwareNon-GPU systemsEmergency fallbackCross-platform compatibility

Which Backend Should I Choose?

On Apple Silicon? Use llama.cpp with Metal for fast, private, offline inference.
Have multiple Macs? Set up an Exo cluster to run larger models across devices.
Running a server? vLLM offers high-throughput production inference (testing welcome!).
Prefer a GUI? LM Studio and Ollama support are planned for easier model management.

Installation Guides

Get Caro running on your preferred platform with step-by-step instructions

🍎

macOS

macOS 12+ (Monterey, Ventura, Sonoma)

Apple Silicon (M1/M2/M3)Intel x86_64

Installation

One-Line Install (Recommended)

bash <(curl --proto '=https' --tlsv1.2 -sSfL https://setup.caro.sh)

Using Cargo

cargo install caro

# Add alias to ~/.zshrc or ~/.bashrc:

alias ai='caro'

Build from Source

git clone https://github.com/wildcard/caro.git

cd caro

. "$HOME/.cargo/env"

cargo build --release

Post-Installation

Verify: caro --version (or ai --version if alias set)
Try it: caro "list files in current directory"
Configure backends in ~/.config/caro/config.toml (optional)

Platform-Specific Tips

MLX backend coming soon for Apple Silicon performance
Use Ollama for local model flexibility
CPU backend works immediately with zero configuration

🐧

Linux

Ubuntu 20.04+, Debian 11+, Fedora 35+, Arch, RHEL 8+

x86_64ARM64

Installation

One-Line Install (Recommended)

bash <(curl --proto '=https' --tlsv1.2 -sSfL https://setup.caro.sh)

Using Cargo

cargo install caro

alias ai='caro' # Add to ~/.bashrc

Build from Source

git clone https://github.com/wildcard/caro.git

cd caro

cargo build --release

Post-Installation

Verify: caro --version
Try: caro "show disk usage"
Optional: Install Ollama for local models

Platform-Specific Tips

CPU backend works out of the box
Connect to Ollama or vLLM for more features
Configure backends in ~/.config/caro/config.toml

🪟

Windows

Windows 10/11 (WSL2 recommended)

x86_64

Installation

WSL2 (Recommended)

# In PowerShell (Admin):

wsl --install

# After restart, in WSL Ubuntu:

bash <(curl --proto '=https' --tlsv1.2 -sSfL https://setup.caro.sh)

Using Cargo in WSL

cargo install caro

alias ai='caro'

Post-Installation

Verify: caro --version
Try: caro "list files"
Works with POSIX commands in WSL environment

Platform-Specific Tips

WSL2 provides full POSIX compatibility
Native Windows support planned for future releases
Use Windows Terminal for best experience

😈

BSD

FreeBSD 13+, OpenBSD 7+, NetBSD 9+

x86_64ARM64

Installation

Using Cargo

# Install Rust if needed

pkg install rust cargo

cargo install caro

Build from Source

git clone https://github.com/wildcard/caro.git

cd caro

cargo build --release

Post-Installation

Verify: caro --version
Try: caro "list open ports"
POSIX compliance ensures BSD compatibility

Platform-Specific Tips

CPU backend works reliably on BSD systems
Connect to Ollama or vLLM as needed
Excellent POSIX command compatibility

Universal Configuration

Once installed, Caro's configuration is consistent across all platforms:

Join the Pack

Caro is open source and built with the community. Contribute, report issues, or join the conversation.

⭐