https://github.com/horacehylee/pico-agent
⚡A pico-sized coding agent used for experiment and testing agent harness with different LLM models
https://github.com/horacehylee/pico-agent
Last synced: 7 days ago
JSON representation
⚡A pico-sized coding agent used for experiment and testing agent harness with different LLM models
- Host: GitHub
- URL: https://github.com/horacehylee/pico-agent
- Owner: horacehylee
- License: mit
- Created: 2026-04-18T16:21:51.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-18T16:39:20.000Z (3 months ago)
- Last Synced: 2026-04-18T18:30:19.989Z (3 months ago)
- Language: Python
- Homepage:
- Size: 35.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🤖 Pico Agent
> ⚡ A pico-sized coding agent used for experiment and testing agent harness with different LLM models.
Pico Agent is a minimal, single-file coding agent that connects to LLM providers via the OpenAI-compatible chat completions API. It ships with file reading, editing, searching, and shell execution tools — giving the model everything it needs to assist with real coding tasks, all in under 150 lines of Python.
## ✨ Features
- 📄 **File operations** — read, create, and edit files
- 📁 **Directory listing** — browse project structure
- 🔍 **Regex search** — find patterns across files recursively
- 🐚 **Shell execution** — run arbitrary commands (30s timeout)
- 🔄 **Agentic loop** — multi-turn tool calling until the task is done
- 🔌 **Multiple providers** — pluggable provider config for experimenting with different LLMs
## 🚀 Quick Start
```bash
# Clone the repo
git clone https://github.com/horacehylee/pico-agent.git
cd pico-agent
# Install uv (if not already installed)
pip install uv
# Create virtual environment and install dependencies
uv sync
# Configure your API key
cp .env.example .env
# Edit .env and add your API key
# Run
uv run python agent.py
```
## 🧪 Running Tests
```bash
# Install dev dependencies and run tests
uv run pytest test_agent.py -v
```
## 🌍 System-wide Installation
To use `pico` from any directory:
```bash
# Add pico to your PATH (pick one option)
# Option 1: Link to ~/.local/bin (recommended)
mkdir -p ~/.local/bin
ln -s "$(pwd)/pico" ~/.local/bin/pico
# Option 2: Link to /usr/local/bin (requires sudo)
sudo ln -s "$(pwd)/pico" /usr/local/bin/pico
# Make sure ~/.local/bin is in your PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"
# Now you can run from anywhere!
pico
```
The `pico` command will:
- 📍 Stay in your current working directory
- 🧪 Use the installed virtual environment
- ▶️ Run agent.py from the repo
## ⚙️ Configuration
Environment variables are loaded from a `.env` file:
| Variable | Description | Default |
| -------------- | -------------------------- | -------- |
| `BASE_URL` | Base URL for the API | `https://openrouter.ai/api/v1` |
| `MODEL` | Model to use | `minimax/minimax-m2.5:free`|
| `API_KEY` | API key for the provider | — |
## 📂 Project Structure
```
pico-agent/
├── agent.py # The entire agent (entry point)
├── test_agent.py # Unit tests
├── .env.example # Template for environment variables
└── README.md
```
## 📝 License
MIT © [Horace Lee](https://github.com/horacehylee)