regcode 0.3.0

Minimalistic coding agent with Python API and CLI

RegCode

A minimalistic coding agent with Python API bindings and CLI interface.

Features

• litellm as the LLM backbone (supports OpenAI, Anthropic, and 100+ providers)
• YAML configuration for model, tokens, temperature, provider settings
• Pydantic models for type-safe config loading with environment variable expansion
• CLI via click: chat, configure, version
• Python API: import regcode; agent = regcode.Agent()
• Host filesystem I/O: write_file and patch_file operate directly on the host filesystem with path traversal protection
• Patch tool: patch_file replaces a range of lines in an existing file
• Robust tool call handling: malformed tool calls and JSON parse errors are gracefully handled
• Progressive streaming: TUI always streams assistant responses progressively rather than all at once

Quick Start

# Install dependencies
uv sync

# Configure your API key (or set OPENAI_API_KEY in your environment)
# Edit config.yaml or use environment variables

# Chat with the agent
uv run regcode chat

# View current config
uv run regcode configure

# View version
uv run regcode version

Usage as a Library

import regcode

# Load config (reads config.yaml, falls back to defaults)
config = regcode.Config.load("config.yaml")

# Create agent
agent = regcode.Agent(config=config)

# Chat (TUI always streams responses progressively)
reply = agent.chat("Refactor this function to use async/await.")
print(reply)

# Reset conversation
agent.reset()

Tools

RegCode includes several built-in tools the agent can use:

Tool	Permission	Description
run_script	EXECUTE	Execute a Python script in the Monty sandbox
shell_command	EXECUTE	Execute shell commands (subprocess, not sandbox)
read_file	READ	Read the contents of a file from the filesystem
write_file	WRITE	Write content to a file on the host filesystem
patch_file	WRITE	Replace a range of lines in an existing file
list_dir	READ	List contents of a directory
search_files	READ	Search for files matching a pattern
browse_dir	READ	Recursively list all files in a directory tree
search_dir	READ	Search for a pattern inside all files within a directory
fetch_git_diff	READ	Fetch the git diff of the current repository
add_review_note	WRITE	Save review notes to persistent storage
read_review_notes	READ	Read previously saved review notes
system_info	READ	Get system information (OS, Python version, etc.)

All file-writing tools (write_file, patch_file) include path traversal protection (.. is blocked). The patch_file tool validates line number bounds and type correctness before performing the replacement.

Project Structure

regcode/
├── config.yaml          # All configuration
├── regcode/
│   ├── __init__.py      # Python API entry point
│   ├── main.py          # Agent core (chat, code review, etc.)
│   ├── cli.py           # CLI entry point (click)
│   ├── config.py        # Config loader (yaml + pydantic)
│   ├── permissions.py    # Tool permission definitions
│   ├── tui.py           # Terminal UI rendering
│   ├── conversation_manager.py
│   ├── sandbox.py
│   ├── monty_sandbox.py
│   └── tools/
│       ├── __init__.py
│       ├── base.py
│       ├── builtins.py   # Built-in tool implementations
│       ├── registry.py
│       └── review_notes.py
├── tests/
│   ├── conftest.py
│   ├── test_main.py
│   ├── test_config.py
│   ├── test_api.py
│   ├── test_cli.py
│   ├── test_context_manager.py
│   ├── test_monty_sandbox.py
│   ├── test_provider_extra.py
│   └── test_review_notes.py
├── pyproject.toml
├── uv.lock
└── README.md

Testing & Linting

uv run pytest tests/ -v
uv run ruff check --fix regcode/ tests/

Configuration

Edit config.yaml to change the model, provider, or tools:

agent:
  model: "openai/gpt-4o"
  max_tokens: 4096
  context_window: 128000
  temperature: 0.7

provider:
  name: "openai"
  api_key: "${OPENAI_API_KEY}"

system_prompt: |
  You are a coding agent. Help the user with code.

tools:
  code_review: true
  security_scan: false
  sandbox: false

Environment variables are expanded automatically (e.g., ${OPENAI_API_KEY}).

License

MIT