regcode 0.4.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, and provider settings via Pydantic models
• Environment variable expansion in config values (e.g., ${OPENAI_API_KEY})
• 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
• 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
• Context window compaction: Automatically compacts conversation history when approaching token limits, preserving system instructions and review notes
• Review notes: Persistent findings stored across context compaction sessions
• Tool budget limits: Configurable maximum number of tool calls per conversation turn

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 (uses Textual TUI)
uv run regcode chat

# Interactive config generator
uv run regcode configure

# View version
uv run regcode version

CLI Chat Options

# Full agent mode (enables write permissions)
uv run regcode chat --full

# Use a specific model
uv run regcode chat --model "openai/gpt-4o"

# Disable colored output
uv run regcode chat --no-color

# Use a custom config file
uv run regcode chat --config /path/to/config.yaml

TUI Slash Commands

While chatting, you can use these slash commands in the input bar:

• /exit or /quit — Quit the application
• /clear — Clear the chat history
• /reset — Reset the session (clear history and tools)

Usage as a Library

import regcode

# Load config (reads config.yaml, falls back to ~/.regcode/config.yaml, then 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
python_code	EXECUTE	Execute Python code in an isolated Monty sandbox with Rust-based security and resource limits
shell_command	EXECUTE	Execute shell commands (subprocess, not sandbox). Only safe, read-only commands are allowed (ls, cat, echo, head, tail, wc, grep, sort, uniq, date, pwd, whoami, id, uname, df, free, which, type, stat, file, sha256sum, md5sum, base64, xxd, od, hexdump, find)
run_script	EXECUTE	Execute a Python script file in the Monty 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
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
osv_cve_scan	READ	Scan project dependencies for known CVEs via OSV.dev API. Optionally scans the codebase for vulnerable usage patterns
system_info	READ	Get system information (OS, Python version, etc.)

Note: browse_dir is defined in the codebase but not included in the default tools. It can be explicitly registered if needed, but is excluded by default because it recursively lists all files in a directory, which can fill the context window in large projects (e.g., .venv, node_modules).

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

project-root/
├── main.py              # Unused stub (hello world only)
├── config.yaml          # Runtime configuration
├── config.yaml.template # Template for new configs
├── pyproject.toml       # Project metadata and dependencies
├── uv.lock              # Locked dependencies
└── regcode/             # Python package
    ├── __init__.py      # Python API entry point
    ├── main.py          # Agent core (chat, review, etc.)
    ├── cli.py           # CLI entry point (click)
    ├── config.py        # Config loader (yaml + pydantic)
    ├── permissions.py    # Tool permission definitions
    ├── tui.py           # Textual-based terminal UI
    ├── conversation_manager.py  # Context compaction & review notes
    ├── sandbox.py       # Legacy sandbox support
    ├── monty_sandbox.py # Monty sandbox integration
    └── tools/
        ├── __init__.py
        ├── base.py      # Base tool classes
        ├── builtins.py  # Built-in tool implementations
        ├── registry.py  # Tool registry management
        └── review_notes.py  # Review notes persistence
├── 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
└── README.md

Testing & Linting

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

Configuration

Edit config.yaml to customize the agent's behavior. The config is loaded from the specified path, ~/.regcode/config.yaml, or falls back to defaults.

agent:
  context_window: 128000        # Maximum context window size
  compaction_threshold: 0.8     # Compact when context > 80% of window
  enable_compaction: true       # Enable automatic context compaction

provider:
  model: "openai/gpt-4o"        # Model identifier (litellm format)
  base_url: "https://api.openai.com/v1"
  api_key: "${OPENAI_API_KEY}"  # Environment variable expansion supported
  temperature: 1.0
  max_tokens: 4096

system_prompt: |              # Custom system prompt (default is provided)
  You are a coding agent.

tools: {}                     # Reserved for future tool configuration

sandbox:
  use_monty: true             # Enable Monty sandbox for Python execution
  max_duration_secs: 10.0
  max_memory_mb: 64
  max_recursion_depth: 100
  type_check: true
  allowed_imports: []

tool_budget: 20               # Max tool calls per agent turn

permissions:
  - read                      # READ: read_file, list_dir, search_files, search_dir, browse_dir, fetch_git_diff, read_review_notes, system_info
  - execute                   # EXECUTE: python_code, shell_command, run_script
  - write                     # WRITE: write_file, patch_file, add_review_note
  # - delete                  # DELETE: no tools currently mapped
  # - all                     # ALL: grants all permissions

Permission Levels

Permission	Tools Granted
read	read_file, list_dir, search_files, search_dir, fetch_git_diff, system_info, osv_cve_scan
write	write_file, patch_file
execute	python_code, shell_command, run_script
delete	(no tools currently)
all	All permissions

Key Settings

• context_window: Maximum token budget for the conversation context.
• compaction_threshold: Ratio of context window at which compaction triggers (e.g., 0.8 = compact at 80%).
• tool_budget: Maximum number of tool calls the agent can make in a single turn before responding.
• permissions: List of permission levels granted to the agent. The chat --full CLI flag automatically adds WRITE permission.

Environment Variables

Values in config.yaml can reference environment variables using ${VAR_NAME} syntax. For example:

provider:
  api_key: "${OPENAI_API_KEY}"

Supported formats: ${VAR}, ${VAR:-default}, and standard shell variable expansion.

License

MIT