# clippy-code 👀📎
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/astral-sh/ruff)
[](http://mypy-lang.org/)
> 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
```bash
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install clippy-code from PyPI
uv tool install clippy-code
```
#### Install from source
```bash
git clone https://github.com/yourusername/clippy.git
cd clippy
# Install with dev dependencies (recommended for contributors)
make dev
# Or install without dev extras
make install
```
### Setup API Keys
clippy-code supports multiple LLM providers through OpenAI-compatible APIs:
```bash
# OpenAI (default)
echo "OPENAI_API_KEY=your_api_key_here" > .env
# Cerebras
echo "CEREBRAS_API_KEY=your_api_key_here" > .env
# Groq
echo "GROQ_API_KEY=your_api_key_here" > .env
# For local models like Ollama, you typically don't need an API key
# Just set the base URL:
export OPENAI_BASE_URL=http://localhost:11434/v1
```
### MCP Configuration
clippy-code can dynamically discover and use tools from MCP (Model Context Protocol) servers. MCP enables external services to expose tools that can be used by the agent without requiring changes to the core codebase.
To use MCP servers, create an `mcp.json` configuration file in your project root or home directory:
```json
{
"mcp_servers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp", "--api-key", "${CTX7_API_KEY}"]
},
"perplexity-ask": {
"command": "npx",
"args": ["-y", "server-perplexity-ask"],
"env": { "PERPLEXITY_API_KEY": "${PERPLEXITY_API_KEY}" }
}
}
}
```
See [MCP_DOCUMENTATION.md](MCP_DOCUMENTATION.md) for detailed information about MCP configuration and usage.
MCP tools will automatically be available in interactive and document modes, with appropriate approval prompts to maintain safety.
See [Setup API Keys](#setup-api-keys) for provider configuration details.
### Basic Usage
```bash
# One-shot mode - execute a single task
clippy "create a hello world python script"
# Interactive mode - REPL-style conversations
clippy -i
# Document mode - Word-inspired TUI interface
clippy -d
# Specify a model
clippy --model gpt-5 "refactor main.py to use async/await"
# Auto-approve all actions (use with caution!)
clippy -y "write unit tests for utils.py"
```
### Development Workflow
Use the provided `Makefile` for common development tasks:
```bash
make dev # Install with development dependencies
make check # Format, lint, and type-check
make test # Run the test suite
make run # Launch clippy-code in interactive mode
```
## Features
### Three Interface Modes
1. **One-shot mode**: `clippy "your task"` - Execute single task and exit
2. **Interactive mode**: `clippy -i` - REPL-style multi-turn conversations with slash commands
3. **Document mode**: `clippy -d` - Word-inspired TUI with toolbar buttons
### Permission System
clippy-code implements safety-first design with a three-tier permission system:
**Auto-approved actions** (read-only operations):
- read_file, list_directory, search_files, get_file_info, grep, read_files
**Require approval** (potentially destructive operations):
- write_file, delete_file, create_directory, execute_command, edit_file
**Blocked actions** (currently empty but configurable)
When clippy-code wants to perform a risky action, you'll see a prompt:
```
→ write_file
path: example.py
content: print("Hello, World!")
[?] Approve this action? [(y)es/(n)o/(a)llow]:
```
Options:
- `(y)es` or `y` - Approve and execute
- `(n)o` or `n` - Reject and stop execution
- `(a)llow` or `a` - Approve and auto-approve this action type for the session
- Empty (just press Enter) - Reprompt for input
### Slash Commands (Interactive/Document Mode)
- `/reset`, `/clear`, `/new` - Reset conversation history
- `/status` - Show token usage and session info
- `/compact` - Summarize conversation to reduce context usage
- `/model list` - Show available models
- `/model <name>` - Switch model/provider
- `/auto list` - List auto-approved actions
- `/auto revoke <action>` - Revoke auto-approval for an action
- `/auto clear` - Clear all auto-approvals
- `/mcp list` - List configured MCP servers
- `/mcp tools [server]` - List tools available from MCP servers
- `/mcp refresh` - Refresh tool catalogs from MCP servers
- `/mcp allow <server>` - Mark an MCP server as trusted for this session
- `/mcp revoke <server>` - Revoke trust for an MCP server
- `/help` - Show help message
- `/exit`, `/quit` - Exit clippy-code
### Supported Providers
Works with any OpenAI-compatible API out of the box:
- OpenAI
- Cerebras
- Together AI
- Ollama
- Groq
- DeepSeek
- Azure OpenAI
- llama.cpp
- vLLM
Switch providers with the `/model` command or CLI arguments.
## Architecture Overview
### System Architecture
clippy-code follows a layered architecture with clear separation of concerns:
```
┌─────────────────────────────────────────────────────┐
│ CLI Layer │
│ (Argument Parsing, User Interaction, Display) │
└─────────────────────┬───────────────────────────────┘
│
┌─────────────────────▼───────────────────────────────┐
│ Agent Layer │
│ (Conversation Management, Response Processing) │
└─────────────────────────────────────────────────────┘
│
┌─────────────────────▼───────────────────────────────┐
│ Tool System │
│ (Tool Definitions, Execution, Permissions) │
└─────────────────────────────────────────────────────┘
│
┌─────────────────────▼───────────────────────────────┐
│ Provider Layer │
│ (OpenAI-compatible API Abstraction) │
└─────────────────────────────────────────────────────┘
```
### Core Components
```
src/clippy/
├── agent/
│ ├── core.py # Core agent implementation
│ ├── loop.py # Agent loop logic
│ ├── conversation.py # Conversation utilities
│ ├── tool_handler.py # Tool calling handler
│ ├── subagent.py # Subagent implementation
│ ├── subagent_manager.py # Subagent lifecycle management
│ ├── subagent_types.py # Subagent type configurations
│ ├── subagent_cache.py # Result caching system
│ ├── subagent_chainer.py # Hierarchical execution chaining
│ ├── subagent_config_manager.py # Subagent configuration management
│ ├── utils.py # Agent helper utilities
│ └── errors.py # Agent-specific exceptions
├── cli/
│ ├── main.py # Main entry point
│ ├── parser.py # Argument parsing
│ ├── oneshot.py # One-shot mode implementation
│ ├── repl.py # Interactive REPL mode
│ ├── commands.py # High-level CLI commands
│ └── setup.py # Initial setup helpers
├── tools/
│ ├── __init__.py # Tool registrations
│ ├── catalog.py # Tool catalog for built-in and MCP tools
│ ├── create_directory.py
│ ├── delete_file.py
│ ├── delegate_to_subagent.py
│ ├── edit_file.py
│ ├── execute_command.py
│ ├── get_file_info.py
│ ├── grep.py
│ ├── list_directory.py
│ ├── read_file.py
│ ├── read_files.py
│ ├── run_parallel_subagents.py
│ ├── search_files.py
│ └── write_file.py
├── mcp/
│ ├── config.py # MCP configuration loading
│ ├── errors.py # MCP error handling
│ ├── manager.py # MCP server connection manager
│ ├── naming.py # MCP tool naming utilities
│ ├── schema.py # MCP schema conversion
│ ├── transports.py # MCP transport layer
│ ├── trust.py # MCP trust system
│ └── types.py # MCP type definitions
├── ui/
│ ├── document_app.py # Textual-based document mode interface
│ ├── styles.py # CSS styling for document mode
│ ├── utils.py # UI utility functions
│ └── widgets.py # Custom UI widgets
├── diff_utils.py # Diff generation utilities
├── executor.py # Tool execution implementations
├── models.py # Model configuration loading and presets
├── models.yaml # Model presets for different providers
├── permissions.py # Permission system (AUTO_APPROVE, REQUIRE_APPROVAL, DENY)
├── prompts.py # System prompts for the agent
├── providers.py # OpenAI-compatible LLM provider
├── providers.yaml # Model/provider preset definitions
├── __main__.py # Module entry point
└── __version__.py # Version helper
```
## Configuration & Models
### Environment Variables
- Provider-specific API keys: `OPENAI_API_KEY`, `CEREBRAS_API_KEY`, `GROQ_API_KEY`, etc.
- `OPENAI_BASE_URL` - Optional base URL override
### Provider-Based Model System
clippy-code uses a flexible provider-based system. Instead of maintaining a fixed list of models, you:
1. **Choose from available providers** (defined in `providers.yaml`): OpenAI, Cerebras, Ollama, Together AI, Groq, DeepSeek, ZAI
2. **Save your favorite model configurations** using `/model add`
3. **Switch between saved models** anytime with `/model <name>`
The default model is **GPT-5** from OpenAI.
#### Managing Models
```bash
# List your saved models
/model list
# Try a model without saving
/model use cerebras qwen-3-coder-480b
# Save a model
/model add cerebras qwen-3-coder-480b --name "q3c"
# Switch to a saved model
/model q3c
# Set a model as default
/model default q3c
# Remove a saved model
/model remove q3c
```
Saved models are stored in `~/.clippy/models.json` and persist across sessions.
## Development Workflow
### Setting Up Development Environment
```bash
# 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
```
### Code Quality Tools
```bash
# Auto-format code
uv run ruff format .
# Lint and check for issues
uv run ruff check .
# Fix auto-fixable issues
uv run ruff check --fix .
# Type checking
uv run mypy src/clippy
```
### Testing
```bash
# Run all tests
uv run pytest
# Run with coverage reporting
uv run pytest --cov=clippy --cov-report=html
# Run specific test file
uv run pytest tests/test_permissions.py
```
Testing philosophy:
- Unit tests for individual components
- Integration tests for workflows
- Mock external APIs for reliability
- Aim for >80% code coverage
### Available Tools
clippy-code has access to these tools:
| Tool | Description | Auto-Approved |
| ------------------ | ------------------------------------------------- | ------------- |
| `read_file` | Read file contents | ✅ |
| `write_file` | Write/modify entire files | ❌ |
| `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) | ❌ |
For detailed information about MCP integration, see [MCP_DOCUMENTATION.md](docs/MCP_DOCUMENTATION.md).
clippy-code can dynamically discover and use tools from MCP (Model Context Protocol) servers. MCP enables external services to expose tools that can be used by the agent without requiring changes to the core codebase.
To use MCP servers, create an `mcp.json` configuration file in your home directory (`~/.clippy/mcp.json`) or project directory (`.clippy/mcp.json`):
```json
{
"mcp_servers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp", "--api-key", "${CTX7_API_KEY}"]
},
"perplexity-ask": {
"command": "npx",
"args": ["-y", "server-perplexity-ask"],
"env": { "PERPLEXITY_API_KEY": "${PERPLEXITY_API_KEY}" }
}
}
}
```
MCP tools will automatically be available in interactive and document modes, with appropriate approval prompts to maintain safety.
## 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
- **Error Handling**: Retry logic with exponential backoff, graceful degradation
## Extensibility
### Adding New LLM Providers
clippy-code works with any OpenAI-compatible API provider. Add new providers by updating `providers.yaml`:
```yaml
providers:
provider_name:
base_url: https://api.provider.com/v1
api_key_env: PROVIDER_API_KEY
description: "Provider Name"
```
Then users can add their own model configurations:
```bash
/model add provider_name model-id --name "my-model" --desc "My custom model"
```
### Adding New Tools
Tools follow a declarative pattern with four components:
1. **Definition & Implementation** (`tools/your_tool.py`): Co-located schema and implementation
2. **Catalog Integration** (`tools/catalog.py`): Tool gets automatically included
3. **Permission** (`permissions.py`): Add to `ActionType` enum and permission config
4. **Execution** (`executor.py`): Implement method returning `tuple[bool, str, Any]`
The steps are:
1. Create a tool file in `src/clippy/tools/` (e.g., `your_tool.py`) with:
- `TOOL_SCHEMA` constant defining the tool's JSON schema
- Implementation function (e.g., `def your_tool(...) -> tuple[bool, str, Any]`)
2. Add the tool export to `src/clippy/tools/__init__.py`
3. Add the action type in `src/clippy/permissions.py`
4. Add the tool execution to `src/clippy/executor.py`
5. Add the tool to the action maps in `src/clippy/agent/tool_handler.py`
6. Add tests for your tool in `tests/tools/test_your_tool.py`
The tool catalog (`tools/catalog.py`) automatically discovers and includes all tools from the tools module.
## Skills Demonstrated
This project showcases proficiency in:
**Software Engineering**:
- SOLID principles and clean architecture
- Dependency injection and separation of concerns
- API design with intuitive interfaces
**Python Development**:
- Modern Python features (type hints, dataclasses, enums)
- Packaging with pyproject.toml and optional dependencies
- CLI development with argparse, prompt_toolkit, rich
**System Design**:
- Layered architecture with clear module boundaries
- Error handling and graceful degradation
- Configuration management (environment, CLI, defaults)
**UI/UX Design**:
- Multiple interface modes for different workflows
- Textual-based TUI with custom styling
- Intuitive command system and user workflows
**Product Thinking**:
- Safety controls with user approval systems
- Maintainable and extensible design patterns
- Developer productivity focus
---
Made with ❤️ by the clippy-code team
Raw data
{
"_id": null,
"home_page": null,
"name": "clippy-code",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, cerebras, cli, coding-agent, developer-tools, llm, ollama, openai",
"author": null,
"author_email": "Your Name <your.email@example.com>",
"download_url": "https://files.pythonhosted.org/packages/ad/9b/fa0d8493546a477a4a51441fc6888a331eb205abe6cfb025a2a3b6fc2c66/clippy_code-2.0.0.tar.gz",
"platform": null,
"description": "# clippy-code \ud83d\udc40\ud83d\udcce\n\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/astral-sh/ruff)\n[](http://mypy-lang.org/)\n\n> A production-ready, model-agnostic CLI coding agent with safety-first design\n\nclippy-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.\n\n## Quick Start\n\n### Installation\n\n```bash\n# Install uv if you haven't already\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install clippy-code from PyPI\nuv tool install clippy-code\n```\n\n#### Install from source\n\n```bash\ngit clone https://github.com/yourusername/clippy.git\ncd clippy\n\n# Install with dev dependencies (recommended for contributors)\nmake dev\n\n# Or install without dev extras\nmake install\n```\n\n### Setup API Keys\n\nclippy-code supports multiple LLM providers through OpenAI-compatible APIs:\n\n```bash\n# OpenAI (default)\necho \"OPENAI_API_KEY=your_api_key_here\" > .env\n\n# Cerebras\necho \"CEREBRAS_API_KEY=your_api_key_here\" > .env\n\n# Groq\necho \"GROQ_API_KEY=your_api_key_here\" > .env\n\n# For local models like Ollama, you typically don't need an API key\n# Just set the base URL:\nexport OPENAI_BASE_URL=http://localhost:11434/v1\n```\n\n### MCP Configuration\n\nclippy-code can dynamically discover and use tools from MCP (Model Context Protocol) servers. MCP enables external services to expose tools that can be used by the agent without requiring changes to the core codebase.\n\nTo use MCP servers, create an `mcp.json` configuration file in your project root or home directory:\n\n```json\n{\n \"mcp_servers\": {\n \"context7\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@upstash/context7-mcp\", \"--api-key\", \"${CTX7_API_KEY}\"]\n },\n \"perplexity-ask\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"server-perplexity-ask\"],\n \"env\": { \"PERPLEXITY_API_KEY\": \"${PERPLEXITY_API_KEY}\" }\n }\n }\n}\n```\n\nSee [MCP_DOCUMENTATION.md](MCP_DOCUMENTATION.md) for detailed information about MCP configuration and usage.\n\nMCP tools will automatically be available in interactive and document modes, with appropriate approval prompts to maintain safety.\nSee [Setup API Keys](#setup-api-keys) for provider configuration details.\n\n### Basic Usage\n\n```bash\n# One-shot mode - execute a single task\nclippy \"create a hello world python script\"\n\n# Interactive mode - REPL-style conversations\nclippy -i\n\n# Document mode - Word-inspired TUI interface\nclippy -d\n\n# Specify a model\nclippy --model gpt-5 \"refactor main.py to use async/await\"\n\n# Auto-approve all actions (use with caution!)\nclippy -y \"write unit tests for utils.py\"\n```\n\n### Development Workflow\n\nUse the provided `Makefile` for common development tasks:\n\n```bash\nmake dev # Install with development dependencies\nmake check # Format, lint, and type-check\nmake test # Run the test suite\nmake run # Launch clippy-code in interactive mode\n```\n\n## Features\n\n### Three Interface Modes\n\n1. **One-shot mode**: `clippy \"your task\"` - Execute single task and exit\n2. **Interactive mode**: `clippy -i` - REPL-style multi-turn conversations with slash commands\n3. **Document mode**: `clippy -d` - Word-inspired TUI with toolbar buttons\n\n### Permission System\n\nclippy-code implements safety-first design with a three-tier permission system:\n\n**Auto-approved actions** (read-only operations):\n\n- read_file, list_directory, search_files, get_file_info, grep, read_files\n\n**Require approval** (potentially destructive operations):\n\n- write_file, delete_file, create_directory, execute_command, edit_file\n\n**Blocked actions** (currently empty but configurable)\n\nWhen clippy-code wants to perform a risky action, you'll see a prompt:\n\n```\n\u2192 write_file\n path: example.py\n content: print(\"Hello, World!\")\n\n[?] Approve this action? [(y)es/(n)o/(a)llow]:\n```\n\nOptions:\n\n- `(y)es` or `y` - Approve and execute\n- `(n)o` or `n` - Reject and stop execution\n- `(a)llow` or `a` - Approve and auto-approve this action type for the session\n- Empty (just press Enter) - Reprompt for input\n\n### Slash Commands (Interactive/Document Mode)\n\n- `/reset`, `/clear`, `/new` - Reset conversation history\n- `/status` - Show token usage and session info\n- `/compact` - Summarize conversation to reduce context usage\n- `/model list` - Show available models\n- `/model <name>` - Switch model/provider\n- `/auto list` - List auto-approved actions\n- `/auto revoke <action>` - Revoke auto-approval for an action\n- `/auto clear` - Clear all auto-approvals\n- `/mcp list` - List configured MCP servers\n- `/mcp tools [server]` - List tools available from MCP servers\n- `/mcp refresh` - Refresh tool catalogs from MCP servers\n- `/mcp allow <server>` - Mark an MCP server as trusted for this session\n- `/mcp revoke <server>` - Revoke trust for an MCP server\n- `/help` - Show help message\n- `/exit`, `/quit` - Exit clippy-code\n\n### Supported Providers\n\nWorks with any OpenAI-compatible API out of the box:\n\n- OpenAI\n- Cerebras\n- Together AI\n- Ollama\n- Groq\n- DeepSeek\n- Azure OpenAI\n- llama.cpp\n- vLLM\n\nSwitch providers with the `/model` command or CLI arguments.\n\n## Architecture Overview\n\n### System Architecture\n\nclippy-code follows a layered architecture with clear separation of concerns:\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 CLI Layer \u2502\n\u2502 (Argument Parsing, User Interaction, Display) \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25bc\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 Agent Layer \u2502\n\u2502 (Conversation Management, Response Processing) \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25bc\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 Tool System \u2502\n\u2502 (Tool Definitions, Execution, Permissions) \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25bc\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 Provider Layer \u2502\n\u2502 (OpenAI-compatible API Abstraction) \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n### Core Components\n\n```\nsrc/clippy/\n\u251c\u2500\u2500 agent/\n\u2502 \u251c\u2500\u2500 core.py # Core agent implementation\n\u2502 \u251c\u2500\u2500 loop.py # Agent loop logic\n\u2502 \u251c\u2500\u2500 conversation.py # Conversation utilities\n\u2502 \u251c\u2500\u2500 tool_handler.py # Tool calling handler\n\u2502 \u251c\u2500\u2500 subagent.py # Subagent implementation\n\u2502 \u251c\u2500\u2500 subagent_manager.py # Subagent lifecycle management\n\u2502 \u251c\u2500\u2500 subagent_types.py # Subagent type configurations\n\u2502 \u251c\u2500\u2500 subagent_cache.py # Result caching system\n\u2502 \u251c\u2500\u2500 subagent_chainer.py # Hierarchical execution chaining\n\u2502 \u251c\u2500\u2500 subagent_config_manager.py # Subagent configuration management\n\u2502 \u251c\u2500\u2500 utils.py # Agent helper utilities\n\u2502 \u2514\u2500\u2500 errors.py # Agent-specific exceptions\n\u251c\u2500\u2500 cli/\n\u2502 \u251c\u2500\u2500 main.py # Main entry point\n\u2502 \u251c\u2500\u2500 parser.py # Argument parsing\n\u2502 \u251c\u2500\u2500 oneshot.py # One-shot mode implementation\n\u2502 \u251c\u2500\u2500 repl.py # Interactive REPL mode\n\u2502 \u251c\u2500\u2500 commands.py # High-level CLI commands\n\u2502 \u2514\u2500\u2500 setup.py # Initial setup helpers\n\u251c\u2500\u2500 tools/\n\u2502 \u251c\u2500\u2500 __init__.py # Tool registrations\n\u2502 \u251c\u2500\u2500 catalog.py # Tool catalog for built-in and MCP tools\n\u2502 \u251c\u2500\u2500 create_directory.py\n\u2502 \u251c\u2500\u2500 delete_file.py\n\u2502 \u251c\u2500\u2500 delegate_to_subagent.py\n\u2502 \u251c\u2500\u2500 edit_file.py\n\u2502 \u251c\u2500\u2500 execute_command.py\n\u2502 \u251c\u2500\u2500 get_file_info.py\n\u2502 \u251c\u2500\u2500 grep.py\n\u2502 \u251c\u2500\u2500 list_directory.py\n\u2502 \u251c\u2500\u2500 read_file.py\n\u2502 \u251c\u2500\u2500 read_files.py\n\u2502 \u251c\u2500\u2500 run_parallel_subagents.py\n\u2502 \u251c\u2500\u2500 search_files.py\n\u2502 \u2514\u2500\u2500 write_file.py\n\u251c\u2500\u2500 mcp/\n\u2502 \u251c\u2500\u2500 config.py # MCP configuration loading\n\u2502 \u251c\u2500\u2500 errors.py # MCP error handling\n\u2502 \u251c\u2500\u2500 manager.py # MCP server connection manager\n\u2502 \u251c\u2500\u2500 naming.py # MCP tool naming utilities\n\u2502 \u251c\u2500\u2500 schema.py # MCP schema conversion\n\u2502 \u251c\u2500\u2500 transports.py # MCP transport layer\n\u2502 \u251c\u2500\u2500 trust.py # MCP trust system\n\u2502 \u2514\u2500\u2500 types.py # MCP type definitions\n\u251c\u2500\u2500 ui/\n\u2502 \u251c\u2500\u2500 document_app.py # Textual-based document mode interface\n\u2502 \u251c\u2500\u2500 styles.py # CSS styling for document mode\n\u2502 \u251c\u2500\u2500 utils.py # UI utility functions\n\u2502 \u2514\u2500\u2500 widgets.py # Custom UI widgets\n\u251c\u2500\u2500 diff_utils.py # Diff generation utilities\n\u251c\u2500\u2500 executor.py # Tool execution implementations\n\u251c\u2500\u2500 models.py # Model configuration loading and presets\n\u251c\u2500\u2500 models.yaml # Model presets for different providers\n\u251c\u2500\u2500 permissions.py # Permission system (AUTO_APPROVE, REQUIRE_APPROVAL, DENY)\n\u251c\u2500\u2500 prompts.py # System prompts for the agent\n\u251c\u2500\u2500 providers.py # OpenAI-compatible LLM provider\n\u251c\u2500\u2500 providers.yaml # Model/provider preset definitions\n\u251c\u2500\u2500 __main__.py # Module entry point\n\u2514\u2500\u2500 __version__.py # Version helper\n```\n\n## Configuration & Models\n\n### Environment Variables\n\n- Provider-specific API keys: `OPENAI_API_KEY`, `CEREBRAS_API_KEY`, `GROQ_API_KEY`, etc.\n- `OPENAI_BASE_URL` - Optional base URL override\n\n### Provider-Based Model System\n\nclippy-code uses a flexible provider-based system. Instead of maintaining a fixed list of models, you:\n\n1. **Choose from available providers** (defined in `providers.yaml`): OpenAI, Cerebras, Ollama, Together AI, Groq, DeepSeek, ZAI\n2. **Save your favorite model configurations** using `/model add`\n3. **Switch between saved models** anytime with `/model <name>`\n\nThe default model is **GPT-5** from OpenAI.\n\n#### Managing Models\n\n```bash\n# List your saved models\n/model list\n\n# Try a model without saving\n/model use cerebras qwen-3-coder-480b\n\n# Save a model\n/model add cerebras qwen-3-coder-480b --name \"q3c\"\n\n# Switch to a saved model\n/model q3c\n\n# Set a model as default\n/model default q3c\n\n# Remove a saved model\n/model remove q3c\n```\n\nSaved models are stored in `~/.clippy/models.json` and persist across sessions.\n\n## Development Workflow\n\n### Setting Up Development Environment\n\n```bash\n# Clone and enter repository\ngit clone https://github.com/yourusername/clippy.git\ncd clippy\n\n# Create virtual environment with uv\nuv venv\nsource .venv/bin/activate # or .venv\\Scripts\\activate on Windows\n\n# Install in editable mode with dev dependencies\nuv pip install -e \".[dev]\"\n\n# Run clippy in development\npython -m clippy\n```\n\n### Code Quality Tools\n\n```bash\n# Auto-format code\nuv run ruff format .\n\n# Lint and check for issues\nuv run ruff check .\n\n# Fix auto-fixable issues\nuv run ruff check --fix .\n\n# Type checking\nuv run mypy src/clippy\n```\n\n### Testing\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run with coverage reporting\nuv run pytest --cov=clippy --cov-report=html\n\n# Run specific test file\nuv run pytest tests/test_permissions.py\n```\n\nTesting philosophy:\n\n- Unit tests for individual components\n- Integration tests for workflows\n- Mock external APIs for reliability\n- Aim for >80% code coverage\n\n### Available Tools\n\nclippy-code has access to these tools:\n\n| Tool | Description | Auto-Approved |\n| ------------------ | ------------------------------------------------- | ------------- |\n| `read_file` | Read file contents | \u2705 |\n| `write_file` | Write/modify entire files | \u274c |\n| `delete_file` | Delete files | \u274c |\n| `list_directory` | List directory contents | \u2705 |\n| `create_directory` | Create directories | \u274c |\n| `execute_command` | Run shell commands | \u274c |\n| `search_files` | Search with glob patterns | \u2705 |\n| `get_file_info` | Get file metadata | \u2705 |\n| `read_files` | Read multiple files at once | \u2705 |\n| `grep` | Search patterns in files | \u2705 |\n| `edit_file` | Edit files by line (insert/replace/delete/append) | \u274c |\n\nFor detailed information about MCP integration, see [MCP_DOCUMENTATION.md](docs/MCP_DOCUMENTATION.md).\n\nclippy-code can dynamically discover and use tools from MCP (Model Context Protocol) servers. MCP enables external services to expose tools that can be used by the agent without requiring changes to the core codebase.\n\nTo use MCP servers, create an `mcp.json` configuration file in your home directory (`~/.clippy/mcp.json`) or project directory (`.clippy/mcp.json`):\n\n```json\n{\n \"mcp_servers\": {\n \"context7\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@upstash/context7-mcp\", \"--api-key\", \"${CTX7_API_KEY}\"]\n },\n \"perplexity-ask\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"server-perplexity-ask\"],\n \"env\": { \"PERPLEXITY_API_KEY\": \"${PERPLEXITY_API_KEY}\" }\n }\n }\n}\n```\n\nMCP tools will automatically be available in interactive and document modes, with appropriate approval prompts to maintain safety.\n\n## Design Principles\n\n- **OpenAI Compatibility**: Single standard API format works with any OpenAI-compatible provider\n- **Safety First**: Three-tier permission system with user approval workflows\n- **Type Safety**: Fully typed Python codebase with MyPy checking\n- **Clean Code**: SOLID principles, modular design, Google-style docstrings\n- **Streaming Responses**: Real-time output for immediate feedback\n- **Error Handling**: Retry logic with exponential backoff, graceful degradation\n\n## Extensibility\n\n### Adding New LLM Providers\n\nclippy-code works with any OpenAI-compatible API provider. Add new providers by updating `providers.yaml`:\n\n```yaml\nproviders:\n provider_name:\n base_url: https://api.provider.com/v1\n api_key_env: PROVIDER_API_KEY\n description: \"Provider Name\"\n```\n\nThen users can add their own model configurations:\n\n```bash\n/model add provider_name model-id --name \"my-model\" --desc \"My custom model\"\n```\n\n### Adding New Tools\n\nTools follow a declarative pattern with four components:\n\n1. **Definition & Implementation** (`tools/your_tool.py`): Co-located schema and implementation\n2. **Catalog Integration** (`tools/catalog.py`): Tool gets automatically included\n3. **Permission** (`permissions.py`): Add to `ActionType` enum and permission config\n4. **Execution** (`executor.py`): Implement method returning `tuple[bool, str, Any]`\n\nThe steps are:\n\n1. Create a tool file in `src/clippy/tools/` (e.g., `your_tool.py`) with:\n - `TOOL_SCHEMA` constant defining the tool's JSON schema\n - Implementation function (e.g., `def your_tool(...) -> tuple[bool, str, Any]`)\n2. Add the tool export to `src/clippy/tools/__init__.py`\n3. Add the action type in `src/clippy/permissions.py`\n4. Add the tool execution to `src/clippy/executor.py`\n5. Add the tool to the action maps in `src/clippy/agent/tool_handler.py`\n6. Add tests for your tool in `tests/tools/test_your_tool.py`\n\nThe tool catalog (`tools/catalog.py`) automatically discovers and includes all tools from the tools module.\n\n## Skills Demonstrated\n\nThis project showcases proficiency in:\n\n**Software Engineering**:\n\n- SOLID principles and clean architecture\n- Dependency injection and separation of concerns\n- API design with intuitive interfaces\n\n**Python Development**:\n\n- Modern Python features (type hints, dataclasses, enums)\n- Packaging with pyproject.toml and optional dependencies\n- CLI development with argparse, prompt_toolkit, rich\n\n**System Design**:\n\n- Layered architecture with clear module boundaries\n- Error handling and graceful degradation\n- Configuration management (environment, CLI, defaults)\n\n**UI/UX Design**:\n\n- Multiple interface modes for different workflows\n- Textual-based TUI with custom styling\n- Intuitive command system and user workflows\n\n**Product Thinking**:\n\n- Safety controls with user approval systems\n- Maintainable and extensible design patterns\n- Developer productivity focus\n\n---\n\nMade with \u2764\ufe0f by the clippy-code team\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A powerful CLI coding agent powered by OpenAI-compatible LLMs",
"version": "2.0.0",
"project_urls": {
"Documentation": "https://github.com/yourusername/clippy#readme",
"Homepage": "https://github.com/yourusername/clippy",
"Issues": "https://github.com/yourusername/clippy/issues",
"Repository": "https://github.com/yourusername/clippy"
},
"split_keywords": [
"ai",
" cerebras",
" cli",
" coding-agent",
" developer-tools",
" llm",
" ollama",
" openai"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "252c0998ce11377e1f37572a2f5682e9119e1caeffa045677ad4c776fb0ff389",
"md5": "02fc318278124e909b6a253151f2e430",
"sha256": "731f49dbe2ab723e265815855faa56dd4f8d42e135fb3ae7fa9fd80e59f183e4"
},
"downloads": -1,
"filename": "clippy_code-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "02fc318278124e909b6a253151f2e430",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 117555,
"upload_time": "2025-10-21T22:43:53",
"upload_time_iso_8601": "2025-10-21T22:43:53.233906Z",
"url": "https://files.pythonhosted.org/packages/25/2c/0998ce11377e1f37572a2f5682e9119e1caeffa045677ad4c776fb0ff389/clippy_code-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ad9bfa0d8493546a477a4a51441fc6888a331eb205abe6cfb025a2a3b6fc2c66",
"md5": "c083b7207cc5e41c56db1742048e3178",
"sha256": "863b582ff101f698b5384a5ddab9c2128f1473971b58fffbe6fcb05107df37ce"
},
"downloads": -1,
"filename": "clippy_code-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "c083b7207cc5e41c56db1742048e3178",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 616962,
"upload_time": "2025-10-21T22:43:54",
"upload_time_iso_8601": "2025-10-21T22:43:54.506708Z",
"url": "https://files.pythonhosted.org/packages/ad/9b/fa0d8493546a477a4a51441fc6888a331eb205abe6cfb025a2a3b6fc2c66/clippy_code-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-21 22:43:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "clippy#readme",
"github_not_found": true,
"lcname": "clippy-code"
}
JSON
