clippy-code 4.21.0

A powerful CLI coding agent powered by OpenAI-compatible LLMs

clippy-code 👀📎

A production-ready, model-agnostic CLI coding agent with safety-first design

clippy-code is an AI-powered development assistant that works with any OpenAI-compatible API provider. It features robust permission controls, streaming responses, and multiple interface modes for different workflows.

🚀 Quick Start

Installation

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run clippy-code directly - no installation needed!
uvx clippy-code "create a hello world python script"

# Start interactive mode
uvx clippy-code

Setup API Keys

clippy-code supports multiple LLM providers through OpenAI-compatible APIs:

# OpenAI (default)
echo "OPENAI_API_KEY=your_api_key_here" > .env

# Choose from supported providers:
echo "ANTHROPIC_API_KEY=your_api_key_here" > .env
echo "CEREBRAS_API_KEY=your_api_key_here" > .env
echo "DEEPSEEK_API_KEY=your_api_key_here" > .env
echo "GOOGLE_API_KEY=your_api_key_here" > .env
echo "GROQ_API_KEY=your_api_key_here" > .env
echo "MISTRAL_API_KEY=your_api_key_here" > .env
echo "OPENROUTER_API_KEY=your_api_key_here" > .env
echo "SYNTHETIC_API_KEY=your_api_key_here" > .env
echo "ZAI_API_KEY=your_api_key_here" > .env

# For local providers (optional - can use empty API key)
echo "LMSTUDIO_API_KEY=" >> .env
echo "OLLAMA_API_KEY=" >> .env

# For Claude Code (OAuth - no API key needed for token-based access)
echo "CLAUDE_CODE_ACCESS_TOKEN=your_token_here" >> .env

Basic Usage

# One-shot mode - execute a single task
clippy "create a hello world python script"

# Interactive mode - REPL-style conversations
clippy

# Specify a model
clippy --model gpt-4 "refactor main.py to use async/await"

# Auto-approve all actions (use with caution!)
clippy -y "write unit tests for utils.py"

🔧 MCP Integration (Optional)

clippy-code can dynamically discover and use tools from MCP (Model Context Protocol) servers. For detailed configuration and available servers, see docs/MCP.md.

Quick setup:

# Create the clippy directory
mkdir -p ~/.clippy

# Copy the example configuration
cp mcp.example.json ~/.clippy/mcp.json

# Edit it with your API keys

Key Features

• 🌐 Broad Provider Support: OpenAI, Anthropic, Cerebras, DeepSeek, Google Gemini, Groq, LM Studio, Mistral, Ollama, OpenRouter, Synthetic.new, Z.AI, and more
• 🛡️ Safety-First Design: Three-tier permissions with interactive approval for risky operations
• 🔄 Multiple Interface Modes: One-shot tasks, interactive REPL, and rich document mode
• 🤖 Advanced Agent Capabilities: Streaming responses, context management, subagent delegation
• 🔌 Extensible Tool System: Built-in file operations, command execution, and MCP integration
• 💻 Developer Experience: Type-safe codebase, rich CLI, flexible configuration

Available Tools

clippy-code provides smart file operations with validation for many file types:

Tool	Description	Auto-Approved
read_file	Read file contents	✅
write_file	Write files with syntax validation	❌
delete_file	Delete files	❌
list_directory	List directory contents	✅
create_directory	Create directories	❌
execute_command	Run shell commands (output hidden by default, set CLIPPY_SHOW_COMMAND_OUTPUT=true to show)	❌
search_files	Search with glob patterns	✅
get_file_info	Get file metadata	✅
read_files	Read multiple files at once	✅
grep	Search patterns in files	✅
read_lines	Read specific lines from a file	✅
edit_file	Edit files by line (insert/replace/delete/append)	❌
fetch_webpage	Fetch content from web pages	❌
find_replace	Multi-file pattern replacement with regex	❌

write_file includes syntax validation for Python, JSON, YAML, HTML, CSS, JavaScript, TypeScript, Markdown, Dockerfile, and XML.

🛡️ Intelligent Command Safety

clippy-code includes an LLM-powered command safety agent that provides intelligent analysis of shell commands before execution. When an LLM provider is available, every execute_command call is automatically analyzed for security risks.

How It Works

The safety agent analyzes commands in full context (including working directory) and uses conservative security policies to protect against dangerous operations:

🚫 Automatically Blocks:

• Destructive operations (rm -rf, shred, recursive deletion)
• System file modifications (/etc/, /boot/, /proc/, /sys/)
• Software installation without consent (pip install, apt-get, npm install)
• Download and execute code (curl | bash, wget | sh)
• Network attacks (nmap, netcat)
• Privilege escalation (sudo unless clearly necessary)
• File system attacks (dd to block devices)

✅ Allows Safe Operations:

• File listing (ls, find)
• Basic command execution (echo, cat, grep)
• Development tools (python script.py, npm run dev)
• Safe file operations in user directories

User Experience

When a command is blocked, users receive clear, contextual feedback:

User: rm -rf /tmp/old_project
AI: Command blocked by safety agent: Would delete entire filesystem - extremely dangerous

User: curl https://github.com/user/script.sh | bash  
AI: Command blocked by safety agent: Downloads and executes untrusted code

The agent is context-aware - the same command may be allowed in a user directory but blocked in system directories.

Fallback Protection

If no LLM provider is available, the system falls back to pattern-based security checks. The safety agent fails safely - if the safety check fails for any reason, commands are blocked by default.

For detailed technical information, see Command Safety Agent Documentation.

Cache Configuration

Safety decisions are automatically cached to improve performance:

• CLIPPY_SAFETY_CACHE_ENABLED - Enable/disable safety cache (default: true)
• CLIPPY_SAFETY_CACHE_SIZE - Maximum cache entries (default: 1000)
• CLIPPY_SAFETY_CACHE_TTL - Cache TTL in seconds (default: 3600)

Caching reduces API calls for repeated commands while maintaining security. Cache entries expire automatically and use LRU eviction.

Models & Configuration

Supported Providers

clippy-code works with any OpenAI-compatible provider: OpenAI, Anthropic (including Claude Code OAuth), Cerebras, DeepSeek, Google Gemini, Groq, LM Studio, Mistral, Ollama, OpenRouter, Synthetic.new, Z.AI, and more.

Managing Models

# List available providers
/model list

# Save a model configuration
/model add cerebras qwen-3-coder-480b --name "q3c"

# Switch to a saved model
/model q3c

Environment Variables

• Provider-specific API keys: ANTHROPIC_API_KEY, CEREBRAS_API_KEY, DEEPSEEK_API_KEY, GOOGLE_API_KEY, GROQ_API_KEY, LMSTUDIO_API_KEY, MISTRAL_API_KEY, OLLAMA_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, SYNTHETIC_API_KEY, ZAI_API_KEY, CLAUDE_CODE_ACCESS_TOKEN (OAuth)
• OPENAI_BASE_URL - Optional base URL override for custom providers
• CLIPPY_SHOW_COMMAND_OUTPUT - Control whether to show output from execute_command tool (default: false, set to true to show output)
• CLIPPY_COMMAND_TIMEOUT - Default timeout for command execution in seconds (default: 300)
• CLIPPY_MAX_TOOL_RESULT_TOKENS - Maximum number of tokens to allow in tool results (default: 10000)

Development

Setting Up

# Clone and enter repository
git clone https://github.com/yourusername/clippy.git
cd clippy

# Create virtual environment with uv
uv venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install in editable mode with dev dependencies
uv pip install -e ".[dev]"

# Run clippy in development
uv run python -m clippy

# For normal usage, use uvx clippy-code

Code Quality

# Format code
make format

# Run linting, type checking, and tests
make check
make test

Adding Features

For detailed information about:

• Adding new tools: See CONTRIBUTING.md
• MCP server integration: See docs/MCP_DOCUMENTATION.md
• Subagent development: See docs/SUBAGENTS.md

Design Principles

• OpenAI Compatibility: Single standard API format works with any OpenAI-compatible provider
• Safety First: Three-tier permission system with user approval workflows
• Type Safety: Fully typed Python codebase with MyPy checking
• Clean Code: SOLID principles, modular design, Google-style docstrings
• Streaming Responses: Real-time output for immediate feedback

Documentation

• Quick Start Guide - Getting started in 5 minutes
• Visual Tutorial - Interactive mode walkthrough with screenshots
• Use Cases & Recipes - Real-world workflows and examples
• Troubleshooting Guide - Common issues and solutions
• Advanced Configuration - Deep customization guide
• MCP Integration - Model Context Protocol setup and usage
• Contributing Guide - Development workflow and code standards
• Agent Documentation - Internal architecture for developers

---

Made with ❤️ by the clippy-code team