Configuration¶
PatchPal can be configured through PATCHPAL_* environment variables to customize behavior, security, and performance.
Model Selection¶
export PATCHPAL_MODEL=openai/gpt-5.2 # Override default model
# Priority: CLI arg > PATCHPAL_MODEL env var > default (anthropic/claude-sonnet-4-5)
# Extra LiteLLM parameters (JSON format)
export PATCHPAL_LITELLM_KWARGS='{"reasoning_effort": "high", "temperature": 0.7}'
# Use for: reasoning models (gpt-oss, deepseek-reasoner), temperature, max_tokens, etc.
# See: https://docs.litellm.ai/docs/completion/input
Security & Permissions¶
Maximum Security Mode¶
For environments requiring the highest level of security, use the --maximum-security CLI flag:
This single flag enables all security restrictions:
- Permission for all operations: Requires approval for ALL operations including read operations (read_file, find, etc.)
- Repository-only access: Blocks reading/writing files outside the repository directory (PATCHPAL_RESTRICT_TO_REPO=true)
- Web access disabled: Disables web search and fetch tools to prevent data spillage (PATCHPAL_ENABLE_WEB=false)
When to use: - Processing sensitive codebases with PII or confidential data - Working in compliance-driven environments (HIPAA, SOC2, etc.) - Evaluating untrusted prompts or skills
Granular Control:
You can also enable these restrictions individually:
# Require permission for all operations (including reads)
patchpal --require-permission-for-all
# Or use environment variables for fine-grained control
export PATCHPAL_RESTRICT_TO_REPO=true # Block access outside repository
export PATCHPAL_ENABLE_WEB=false # Disable web access
patchpal
In addition, the run_shell tool also includes built-in guardrails.
For maximum isolation, you can run PatchPal inside a sandboxed container using patchpal-sandbox:
# Interactive mode (permissions enabled by default)
patchpal-sandbox
# Or specify a model (pass arguments after --)
patchpal-sandbox -- --model <litellm_model_id>
# Autopilot mode (permissions disabled automatically)
patchpal-sandbox -- autopilot --prompt "..."
This provides a fully isolated environment with restricted access to your host system. Permissions remain enabled in interactive mode but are automatically disabled when using the autopilot subcommand.
Environment Variables¶
# Permission System
export PATCHPAL_REQUIRE_PERMISSION=true # Prompt before executing commands/modifying files (default: true)
# ⚠️ WARNING: Setting to false disables prompts - only use in trusted environments
# Note: Automatically set to false by autopilot mode (patchpal-autopilot command)
# When using patchpal-sandbox:
# - Interactive mode (default): permissions ENABLED
# - Autopilot mode (autopilot subcommand): permissions DISABLED automatically
# File Safety
export PATCHPAL_MAX_FILE_SIZE=512000 # Maximum file size in bytes for read/write (default: 500KB)
# Applies to: text files, SVG files
# Reduced from 10MB to prevent context window explosions
export PATCHPAL_MAX_IMAGE_SIZE=10485760 # Maximum image file size in bytes (default: 10MB)
# Applies to: PNG, JPG, GIF, BMP, WEBP (not SVG)
# Images are formatted as multimodal content, bypassing tool output limits
# Vision APIs resize images automatically, so 1-2MB is optimal
export PATCHPAL_MAX_TOOL_OUTPUT_LINES=2000 # Maximum lines per tool output (default: 2000)
# Prevents any single tool from dominating context
export PATCHPAL_MAX_TOOL_OUTPUT_CHARS=100000 # Maximum characters per tool output (default: 100K)
# Applied after tool execution to all tool results
# Character-based (not bytes) to avoid breaking Unicode
export PATCHPAL_READ_ONLY=true # Prevent ALL file modifications (default: false)
# Useful for: code review, exploration, security audits
export PATCHPAL_ALLOW_SENSITIVE=true # Allow access to .env, credentials (default: false - blocked)
# Only enable with test/dummy credentials
export PATCHPAL_RESTRICT_TO_REPO=true # Restrict file access to repository only (default: false)
# Prevents reading/writing files outside the repository directory
# Useful for: preventing PII leakage from external files
# Examples of blocked paths: /tmp/file.txt, ~/Documents/notes.txt, ../../etc/passwd
# Command Safety
export PATCHPAL_ALLOW_SUDO=true # Allow sudo/privilege escalation (default: false - blocked)
# ⚠️ WARNING: Only enable in trusted, controlled environments
export PATCHPAL_SHELL_TIMEOUT=60 # Shell command timeout in seconds (default: 30)
# Output Filtering
export PATCHPAL_FILTER_OUTPUTS=true # Filter verbose command outputs (default: true)
# Only applies to specific commands: test runners, git log, build tools
# Patterns matched: pytest, npm test, git log, pip install, cargo build, etc.
# Shows only failures, errors, and summaries for matched commands
# Can save 75%+ on output tokens for verbose commands
# All other commands return full output
export PATCHPAL_MAX_OUTPUT_LINES=500 # Max lines of shell output (default: 500)
# Applied to ALL shell commands to prevent context flooding
# If output exceeds this, shows first/last portions with truncation notice
Operational Controls¶
# Logging & Auditing
export PATCHPAL_AUDIT_LOG=false # Log operations to ~/.patchpal/repos/<repo-name>/audit.log (default: true)
export PATCHPAL_ENABLE_BACKUPS=true # Auto-backup files before modification (default: false)
# Streaming Output
export PATCHPAL_STREAM_OUTPUT=false # Disable streaming progress indicator (default: true - enabled)
# When enabled, shows animated spinner + token counter during LLM API calls
# Helps detect when LLM is hanging vs. actively generating
# Resource Limits
export PATCHPAL_MAX_OPERATIONS=10000 # Max operations per session (default: 10000)
export PATCHPAL_MAX_ITERATIONS=150 # Max agent iterations per task (default: 100)
# Increase for complex multi-file tasks
export PATCHPAL_LLM_TIMEOUT=300 # LLM API timeout in seconds (default: 300 = 5 minutes)
# Prevents indefinite stalls when API is unresponsive
Context Window Management¶
# Auto-Compaction
export PATCHPAL_DISABLE_AUTOCOMPACT=true # Disable auto-compaction (default: false - enabled)
export PATCHPAL_COMPACT_THRESHOLD=0.75 # Trigger compaction at % full (default: 0.75 = 75%)
# Context Limits
export PATCHPAL_CONTEXT_LIMIT=100000 # Override model's context limit (for testing)
# Leave unset to use model's actual capacity
# Pruning Controls
export PATCHPAL_PROACTIVE_PRUNING=true # Prune tool outputs after calls when > PRUNE_PROTECT (default: true)
# Uses intelligent summarization to preserve context
export PATCHPAL_PRUNE_PROTECT=40000 # Keep last N tokens of tool outputs (default: 40000)
export PATCHPAL_PRUNE_MINIMUM=20000 # Minimum tokens to prune (default: 20000)
MCP (Model Context Protocol) Integration¶
# Enable/Disable MCP Tools
export PATCHPAL_ENABLE_MCP=false # Disable MCP tool loading (default: true - enabled)
# Useful for: testing, faster startup, minimal environments
# Note: MCP tools are loaded dynamically from ~/.patchpal/config.json
Tool Selection¶
Minimal Tools Mode¶
# Limit to Essential Tools Only
export PATCHPAL_MINIMAL_TOOLS=true # Enable minimal tools mode (default: false)
# Limits agent to 5 essential tools: read_file, edit_file, write_file, run_shell, grep
# Recommended for: local models <20B params, models that struggle with tool selection
# Improves: decision speed (2-3s vs 10-30s), tool accuracy (~95% vs ~60%)
# Trade-off: No code_structure, web tools, TODO tools, etc.
Limiting Available Tools (enabled_tools)¶
For fine-grained control over which built-in tools are available to the agent, use enabled_tools:
Via Environment Variable (for CLI usage):
# Limit to specific tools (whitelist)
export PATCHPAL_ENABLED_TOOLS="read_file,read_lines,code_structure,get_repo_map"
patchpal
# Read-only agent (no modifications)
export PATCHPAL_ENABLED_TOOLS="read_file,read_lines,code_structure"
patchpal
# Lightweight read-only with search (uses optional tools)
export PATCHPAL_ENABLED_TOOLS="read_file,read_lines,find,grep"
patchpal
# Code editor (no shell access)
export PATCHPAL_ENABLED_TOOLS="read_file,edit_file,write_file"
patchpal
# Research assistant (web + reading)
export PATCHPAL_ENABLED_TOOLS="read_file,web_search,web_fetch"
patchpal
Via Python API (for programmatic use):
from patchpal import create_agent
# Read-only analysis agent
agent = create_agent(
enabled_tools=["read_file", "read_lines", "code_structure", "get_repo_map"]
)
# Lightweight read-only with search (uses optional tools)
agent = create_agent(
enabled_tools=["read_file", "read_lines", "find", "grep"]
)
# Code editor agent (no shell commands)
agent = create_agent(
enabled_tools=["read_file", "read_lines", "edit_file", "write_file"]
)
# Research assistant
agent = create_agent(
enabled_tools=["read_file", "web_search", "web_fetch"]
)
# Custom tools are always added on top of enabled_tools
def my_calculator(x: int, y: int) -> str:
"""Add two numbers."""
return str(x + y)
agent = create_agent(
enabled_tools=["read_file"], # Only this built-in tool
custom_tools=[my_calculator] # Plus custom tool
)
Available Built-in Tools:
- read_file - Read file contents (text, images, PDFs, etc.)
- read_lines - Read specific lines from a file
- write_file - Write complete file contents
- edit_file - Edit files using find/replace
- code_structure - Analyze code structure (AST parsing)
- get_repo_map - Generate repository overview
- run_shell - Execute shell commands
- grep - Pattern search in files (disabled by default; shell commands preferred for most cases)
- find - Find files by pattern or list directory contents (disabled by default; faster than get_repo_map for simple file listing)
- web_search - Search the web
- web_fetch - Fetch content from URLs
- list_skills - List available skills
- use_skill - Invoke a skill
- todo_add, todo_list, todo_complete, todo_update, todo_remove, todo_clear - Task management
- ask_user - Ask user for input/clarification
Note: The grep and find tools are disabled by default but can be explicitly enabled via enabled_tools. They provide lightweight search and navigation without requiring run_shell access or expensive code parsing (get_repo_map), making them ideal for read-only agents exploring codebases.
Precedence:
1. enabled_tools parameter (Python API - highest priority)
2. PATCHPAL_ENABLED_TOOLS environment variable (CLI)
3. PATCHPAL_ENABLE_WEB / PATCHPAL_MINIMAL_TOOLS (broader filters)
Use Cases: - Security: Limit agent capabilities in production environments - Specialization: Create focused agents for specific tasks (read-only, editor-only, etc.) - Testing: Control agent behavior in test environments - User Control: Let end-users configure agent permissions
Note: The enabled_tools parameter/variable overrides PATCHPAL_ENABLE_WEB and PATCHPAL_MINIMAL_TOOLS. If you specify enabled_tools, you get exactly those tools (plus any custom tools).
Web Tools¶
# Enable/Disable Web Access
export PATCHPAL_ENABLE_WEB=false # Disable web search/fetch for air-gapped environments (default: true)
# SSL Certificate Verification (for web_search)
export PATCHPAL_VERIFY_SSL=true # SSL verification for web searches (default: true)
# Set to 'false' to disable (not recommended for production)
# Or set to path of CA bundle file for corporate certificates
# Auto-detects SSL_CERT_FILE and REQUESTS_CA_BUNDLE if not set
# Examples:
# export PATCHPAL_VERIFY_SSL=false # Disable verification
# export PATCHPAL_VERIFY_SSL=/path/to/ca-bundle.crt # Custom CA bundle
# (Leave unset to auto-detect from SSL_CERT_FILE/REQUESTS_CA_BUNDLE)
# Web Request Limits
export PATCHPAL_WEB_TIMEOUT=60 # Web request timeout in seconds (default: 30)
export PATCHPAL_MAX_WEB_SIZE=10485760 # Max web content size in bytes (default: 5MB)
# Character limits are controlled by PATCHPAL_MAX_TOOL_OUTPUT_CHARS
Custom System Prompt¶
export PATCHPAL_SYSTEM_PROMPT=~/.patchpal/my_prompt.md # Use custom system prompt
# File can use template variables: {platform_info}, {web_usage}
# Useful for: custom behavior, team standards, domain-specific instructions
Configuration Examples¶
Air-Gapped Environment (Offline, No Web Access):
Reasoning Model with High Effort:
export PATCHPAL_MODEL=ollama_chat/gpt-oss:120b
export PATCHPAL_LITELLM_KWARGS='{"reasoning_effort": "high"}'
patchpal
Maximum Security:
# Single flag for all security restrictions
patchpal --maximum-security
# Enables: permission for all ops, repo-only access, web disabled
Read-Only Mode (No File Modifications):
export PATCHPAL_READ_ONLY=true
patchpal
# Agent can read files and run commands but cannot modify files
Testing Context Management:
export PATCHPAL_CONTEXT_LIMIT=10000 # Small limit to trigger compaction quickly
export PATCHPAL_COMPACT_THRESHOLD=0.75 # Trigger at 75% instead of 85%
export PATCHPAL_PRUNE_PROTECT=500 # Keep only last 500 tokens
patchpal
Autonomous Mode (Trusted Environment Only):
export PATCHPAL_REQUIRE_PERMISSION=false # ⚠️ Disables all permission prompts
export PATCHPAL_MAX_ITERATIONS=200 # Allow longer runs
patchpal
Autopilot Mode (CI/CD Integration):
export PATCHPAL_AUTOPILOT_CONFIRMED=true # Skip autopilot safety confirmation (default: false)
# ⚠️ Only use in CI/CD or automation contexts
# Autopilot mode allows continuous iterative execution
patchpal-autopilot --prompt "Implement feature X"
Image Analysis with Vision Models:
# Anthropic/Claude (5MB limit via Bedrock or Direct API)
export PATCHPAL_MODEL=anthropic/claude-3-5-sonnet-20241022
patchpal
# OpenAI/GPT-4o (20MB limit)
export PATCHPAL_MODEL=openai/gpt-4o
patchpal
# Both work the same way from user perspective:
You: Look at screenshot.png and explain what's wrong
# The agent automatically:
# - Detects the model provider
# - Formats images appropriately:
# * Anthropic: multimodal content in tool results
# * OpenAI: images injected as user messages (API workaround)
# For images exceeding provider limits, increase PatchPal's limit:
export PATCHPAL_MAX_IMAGE_SIZE=$((20*1024*1024)) # 20MB
# Tip: Use compressed images (1-2MB) for faster processing
# Vision APIs resize large images automatically anyway
# Block images for non-vision models (or for privacy):
export PATCHPAL_BLOCK_IMAGES=true # Replace images with text placeholders (default: false)
# Useful for:
# - Non-vision models (gpt-3.5-turbo, claude-instant, local models)
# - Privacy compliance (prevent image data from being sent)
# Images are replaced with: "[Image blocked - PATCHPAL_BLOCK_IMAGES=true...]"