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

# Or choose from many supported providers:
echo "ANTHROPIC_API_KEY=your_api_key_here" > .env
echo "MISTRAL_API_KEY=your_api_key_here" > .env
echo "CEREBRAS_API_KEY=your_api_key_here" > .env
echo "GROQ_API_KEY=your_api_key_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, Groq, Mistral, Ollama, and many 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	❌
search_files	Search with glob patterns	✅
get_file_info	Get file metadata	✅
read_files	Read multiple files at once	✅
grep	Search patterns in files	✅
edit_file	Edit files by line (insert/replace/delete/append)	❌

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

Models & Configuration

Supported Providers

clippy-code works with any OpenAI-compatible provider: Anthropic, Chutes, Cerebras, Gemini, Groq, LM Studio, MiniMax, Mistral, Ollama, OpenAI, OpenRouter, Synthetic.new, Together AI, Z.AI, and more.

Managing Models

# List available providers
/model list

# Try a model without saving
/model use cerebras qwen-3-coder-480b

# 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, CHUTES_API_KEY, CEREBRAS_API_KEY, GOOGLE_API_KEY, GROQ_API_KEY, MISTRAL_API_KEY, OPENAI_API_KEY, etc.
• OPENAI_BASE_URL - Optional base URL override for custom providers

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
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
• 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