PicoGent - Minimal AI Coding Agent

A lightweight AI coding assistant built in Python with minimal dependencies. PicoGent implements a ReAct (Reasoning and Acting) loop that allows LLMs to use tools to accomplish complex tasks.

Features

• Minimal Dependencies: Only requires httpx - no heavy SDKs
• ReAct Loop: Classic reasoning and acting pattern for tool use
• Anthropic Claude Support: Direct API integration without SDK
• Built-in Tools: File operations (read/write/edit) and shell execution
• Session Management: JSONL-based conversation history
• Skills System: Extensible skills directory for custom prompts
• Configurable: JSON-based configuration with environment variable support

Installation

# Clone the repository
git clone https://git.uix.su/markov/picogent-py.git
cd picogent-py

# Install dependencies
pip install -r requirements.txt

# Or install as a package
pip install -e .

Quick Start

1. Set up your API key:

   export ANTHROPIC_API_KEY="your-api-key-here"
   

2. Create a configuration file:

   cp config.example.json config.json
   

3. Use the agent:

   import asyncio
   from picogent import run_agent, Config
   
   async def main():
       # Load configuration
       config = Config.from_file("config.json")
   
       # Run agent with prompt
       response = await run_agent("List all files in the current directory", config)
       print(response)
   
   asyncio.run(main())
   

   Or use the CLI:

   python -m picogent.cli "Create a hello world Python script"
   

Architecture

Core Components

• Agent (agent.py): Main ReAct loop implementation
• Provider (providers/anthropic.py): Anthropic API integration using httpx
• Tools (tools/): Built-in tools for file and system operations
• Session (session.py): JSONL-based conversation history
• Config (config.py): Configuration management

Built-in Tools

• read: Read file contents with optional offset/limit
• write: Write files with automatic directory creation
• edit: Find and replace text in files
• bash: Execute shell commands with timeout

ReAct Loop

1. Build context (system prompt + history + user message)
2. Send to LLM with tool definitions
3. If no tool calls → return text response (done)
4. If tool calls → execute each tool, add results to history
5. Repeat from step 2 (max 20 iterations)

Configuration

The config.json file supports:

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "api_key": "env:ANTHROPIC_API_KEY",
  "max_tokens": 8192,
  "max_iterations": 20,
  "workspace": ".",
  "system_prompt": "You are a helpful coding assistant."
}

• api_key can reference environment variables with env:VARIABLE_NAME
• workspace sets the working directory for file operations
• max_iterations prevents infinite loops in the ReAct cycle

Skills System

Add custom prompts and context to the skills/ directory:

skills/
├── python-expert.md      # Python-specific knowledge
├── web-dev.md           # Web development skills
└── debugging.md         # Debugging techniques

Skills are automatically loaded and added to the system prompt.

Session Management

Sessions are stored in JSONL format for easy inspection and debugging:

# Save conversation to file
response = await agent.run("Create a Python script", session_file="conversation.jsonl")

# Load existing session
agent.session.load("conversation.jsonl")

API Integration

The Anthropic provider uses direct HTTP requests with httpx:

• No official SDK dependency
• Full control over API calls
• Support for tool use and tool result messages
• Proper error handling and timeouts

Development

The codebase follows these principles:

• Minimal dependencies: Only essential packages
• Type hints: Full type annotations
• Async/await: Modern Python async patterns
• Error handling: Comprehensive exception management
• Extensibility: Easy to add new tools and providers

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

Roadmap

• OpenAI provider support
• Streaming responses
• Plugin system for custom tools
• Web interface
• Multi-agent coordination