source-agent 0.0.9

Simple coding agent.

Source Agent

A simple coding agent.

How it Works

Source Agent operates as a stateless entity, guided by clear directives and external context. Its behavior is primarily defined by AGENTS.md, which serves as the core system prompt. CHANGELOG.md provides essential historical context and sense-making rationale.

---

Prerequisites

• Python 3.10 or higher
• An API key from one of the supported AI providers (see Supported Providers)
• Git (for .gitignore support)

---

Installation

Quick Start

# Clone the repository
git clone https://github.com/christopherwoodall/source-agent
cd source-agent

# Create virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e ".[developer]"

# Verify the installation
source-agent --help

Basic Usage

# Analyze the current codebase
source-agent --prompt "Analyze this codebase and identify potential improvements"

# Analyze with specific focus
source-agent --prompt "Review the authentication system for security issues"

Advanced Usage

# Use OpenAI with GPT-4
source-agent \
  --provider openai \
  --model gpt-4o \
  --temperature 0.1 \
  --prompt "Create unit tests for the utils.py file"

# Use Claude for code review
source-agent \
  --provider anthropic \
  --model claude-3-5-sonnet \
  --prompt "Review the error handling in this codebase"

---

Supported Providers

Source Agent supports multiple AI providers. Set the corresponding environment variable:

Provider	Environment Variable
OpenRouter	OPENROUTER_API_KEY
OpenAI	OPENAI_API_KEY
Anthropic	ANTHROPIC_API_KEY
Google	GEMINI_API_KEY
Mistral	MISTRAL_API_KEY
DeepSeek	DEEPSEEK_API_KEY
Cerebras	CEREBRAS_API_KEY
Groq	GROQ_API_KEY
Vercel	VERCEL_API_KEY
xAI	XAI_API_KEY

---

Available Tools

Source Agent provides these built-in tools for code analysis:

• ls - List files and directories (respects .gitignore)
• cat - Read file contents with security checks
• find - Find files by pattern (glob) in directory tree
• grep - Search for text/regex in files
• mkdir - Create directories
• write - Write content to files

These tools are automatically available to the AI agent during analysis.

---

Core Architecture

• Entry Point: src/source_agent/entrypoint.py - CLI interface with argument parsing
• Agent Engine: src/source_agent/agents/code.py - OpenAI-compatible client with tool integration
• System Prompt: AGENTS.md - Defines agent behavior, roles, and constraints

Project Structure

source-agent/
├── src/source_agent/
│   ├── entrypoint.py      # CLI interface
│   ├── agents/
│   │   └── code.py        # Main agent logic
│   └── tools/             # File system tools
├── AGENTS.md              # System prompt & behavior rules
└── CHANGELOG.md           # Development history