https://github.com/jondot/picocode
a minimal, Rust-based implementation similar to Claude Code
https://github.com/jondot/picocode
Last synced: 20 days ago
JSON representation
a minimal, Rust-based implementation similar to Claude Code
- Host: GitHub
- URL: https://github.com/jondot/picocode
- Owner: jondot
- License: mit
- Created: 2026-01-16T15:10:05.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-01-16T18:56:09.000Z (4 months ago)
- Last Synced: 2026-01-17T04:53:39.817Z (4 months ago)
- Language: Rust
- Size: 854 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-cli-coding-agents - picocode - based coding agent focused on CI workflows and small codemods; multi-LLM with personas. (Terminal-native coding agents / Open Source)
README
⚡️ picocode
The tiny coding agent that speaks every LLM.
**picocode** is a minimal, high-performance Rust-based coding agent. It's a small, robust tool designed for developers who want a lightweight assistant that is easy to reason about, safe to use, and highly hackable.
## 🚀 Quick Start
Get up and running in seconds:
```bash
# 1. Install
curl -sSfL https://raw.githubusercontent.com/jondot/picocode/main/install.sh | sh
# 2. Set your API Key (pick your provider)
export ANTHROPIC_API_KEY=your_key_here # For Claude
# or
export OPENAI_API_KEY=your_key_here # For GPT-4o
# or
export GOOGLE_API_KEY=your_key_here # For Gemini
# or
export DEEPSEEK_API_KEY=your_key_here # For DeepSeek
# 3. Start coding
picocode "Analyze this project and suggest improvements"
```
Or, download directly from [releases](https://github.com/jondot/picocode/releases)
---
## 🦀 Why picocode?
- **Tiny & Fast**: A single, compact binary written in Rust. No heavy dependencies, no bloat.
- **Multi-LLM Sovereignty**: Works with Anthropic, OpenAI, DeepSeek, Google (Gemini), Ollama, and many more via [Rig](https://github.com/0xPlayground/rig).
- **Interactive & Scriptable**: Use it as an interactive CLI, pipe it into scripts, or run automated **Recipes**.
- **Persona-driven**: Switch between different expert personalities (Architect, Security, Zen Master, etc.) to change how the agent thinks and speaks.
- **Safety First**: Destructive actions (like deleting files or running shell commands) require manual confirmation by default.
- **Extensible**: Use it as a CLI tool or integrate it as a Rust library in your own projects.
## 🎭 The Persona Gallery
Picocode isn't just a tool; it has character. Use `--persona` to change the agent's expertise and "vibe":
| Persona | Description | "Voice" |
| :----------- | :------------------------------------ | :------------------------------------------------------------- |
| `architect` | High-level software architect. | _"This abstraction needs more Cowbell. Let's refactor."_ |
| `strict` | Swiss-clock precision engineer. | _"Zero tolerance for fluff. Applying optimal logic."_ |
| `security` | Bruce Schneier fan, paranoid analyst. | _"Searching for vulnerabilities... trust nothing."_ |
| `zen` | Minimalist, focused on simplicity. | _"Code is a form of meditation. Let's find the path."_ |
| `hacker` | Chaotic good, assembly dreamer. | _"I found a 2ms optimization. Applying now."_ |
| `guru` | Visionary Silicon Valley disruptor. | _"Let's move the needle and scale this to infinity."_ |
| `sysadmin` | Grumpy, old-school server legend. | _"Back in my day, we didn't need these fancy LLMs..."_ |
| `academic` | Formal professor, theory first. | _"As per the 1974 paper by Knuth, this is suboptimal."_ |
| `hustler` | MVP-focused startup survivor. | _"Ship it! We'll fix the debt after the Series A."_ |
| `craftsman` | Accessibility & semantic HTML purist. | _"Semantic HTML is the foundation of a healthy web."_ |
| `sre` | Reliability and observability ninja. | _"But how will we monitor this in production?"_ |
| `maintainer` | Patient, docs-loving OSS saint. | _"Could you add a test case and update the README?"_ |
| `tester` | Destructive edge-case finder. | _"I'm going to try passing a null to this and watch it burn."_ |
> [!TIP]
> You can even add a local `AGENTS.md` file to give the agent custom codebase-specific instructions!
## ⚙️ Recipes & Automation
Picocode supports named **Recipes** in a `picocode.yaml` file for non-interactive execution (CI/CD, automation).
```yaml
# picocode.yaml
recipes:
review-security:
prompt: "Review the codebase for security issues."
persona: "security"
model: "claude-3-5-sonnet-latest"
review-from-file:
prompt_file: "prompts/security_review.txt"
persona: "security"
```
Run it with:
```bash
picocode recipe review-security
```
## ⚙️ CLI Modes & Flags
Picocode is designed to be flexible, whether you're using it for a quick question or a complex automation task.
### Main Commands
- **Interactive Chat**: `picocode` or `picocode chat` (Default)
- **Single Prompt**: `picocode "your prompt"` or `picocode input "your prompt"`
- **Recipes**: `picocode recipe ` (Runs a pre-defined task from `picocode.yaml`)
### Common Flags
- `-p, --provider `: Override the default LLM provider (e.g., `openai`, `anthropic`, `ollama`).
- `-m, --model `: Specify a specific model (e.g., `claude-3-5-sonnet-latest`, `gpt-4o`).
- `--yolo`: Disable all confirmation prompts. **Use with caution.**
- `-q, --quiet`: Minimal output, useful for piping into other tools.
- `--persona `: Launch with a specific expert persona.
- `--tool-call-limit `: Maximum number of tool calls allowed per turn (Default: 50).
## 🛠 Available Tools
Picocode gives the AI a comprehensive set of tools to interact with your environment:
- **Filesystem**: `read_file`, `write_file`, `edit_file` (atomic search-replace), `list_dir`, `make_dir`, `remove`, `move_file`, `copy_file`.
- **Search**: `grep_text` (regex search), `glob_files` (find files by pattern).
- **System**: `bash` (run any shell command).
- **Web**: `agent_browser` (full browser automation via [agent-browser](https://github.com/jondot/agent-browser) if installed).
## 🛠 Hacking on picocode
Picocode is built with Rust and the [Rig](https://github.com/0xPlayground/rig) library. It's designed to be extremely easy to extend.
### Prerequisites
- [Rust](https://rustup.rs/) (latest stable)
- API Keys for your preferred provider (e.g., `ANTHROPIC_API_KEY`)
### Local Setup
```bash
# 1. Clone the repo
git clone https://github.com/jondot/picocode.git
cd picocode
# 2. Build and run
cargo run -- "Analyze src/main.rs"
```
### Adding a New Tool
1. Open `src/tools.rs`.
2. Use the `#[rig_tool]` macro to define your function.
3. Register the tool in `src/agent.rs` within the `build_rig_agent` function.
### Project Structure
- `src/main.rs`: CLI entry point and argument parsing.
- `src/agent.rs`: Agent creation and system prompt logic.
- `src/tools.rs`: Implementation of all AI-accessible tools.
- `src/output.rs`: Terminal UI and progress indicators.
## 📚 Use as a Library
Picocode is structured as a library (`lib.rs`) and a binary (`main.rs`).
Example usage:
```rust
use picocode::{create_agent, AgentConfig, ConsoleOutput};
use std::sync::Arc;
#[tokio::main]
async fn main() -> Result<(), Box> {
let output = Arc::new(ConsoleOutput::new());
let agent = create_agent(AgentConfig {
provider: "anthropic".into(),
model: "claude-3-5-sonnet-latest".into(),
output,
yolo: false,
tool_call_limit: 50,
system_message_extension: None,
persona_prompt: None,
persona_name: None,
bash_auto_allow: None,
agent_prompt: None,
}).await?;
let response = agent.run_once("Analyze the current project".into()).await?;
println!("Response: {}", response);
Ok(())
}
```
---
Built for speed, safety, and simplicity. MIT Licensed.