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.
# 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-codeclippy-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# 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"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- 🌐 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
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.
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.
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 (
sudounless clearly necessary) - File system attacks (
ddto 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
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.
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.
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.
clippy-code works with any OpenAI-compatible provider: OpenAI, Anthropic, Cerebras, DeepSeek, Google Gemini, Groq, LM Studio, Mistral, Ollama, OpenRouter, Synthetic.new, Z.AI, and more.
# 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- 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 OPENAI_BASE_URL- Optional base URL override for custom providersCLIPPY_SHOW_COMMAND_OUTPUT- Control whether to show output fromexecute_commandtool (default:false, set totrueto 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)
# 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# Format code
make format
# Run linting, type checking, and tests
make check
make testFor detailed information about:
- Adding new tools: See CONTRIBUTING.md
- MCP server integration: See docs/MCP_DOCUMENTATION.md
- Subagent development: See docs/SUBAGENTS.md
- 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
- 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