PatchPal — An Agentic Coding and Automation Assistant

Supporting both local and cloud LLMs, with autopilot mode and extensible tools.

PatchPal is an AI coding agent that helps you build software, debug issues, and automate tasks. It supports agent skills, tool use, and executable Python generation, enabling interactive workflows for tasks such as data analysis, visualization, web scraping, API interactions, and research with synthesized findings.

Most agent frameworks are built in TypeScript. PatchPal is Python-native, designed for developers who want both interactive terminal use (patchpal) and programmatic API access (agent.run("task")) in the same tool—without switching ecosystems.

Key Features

Terminal Interface for interactive development
Sandbox Mode for secure container isolation
Python SDK for flexibility and extensibility
Built-In and Custom Tools
Browser Automation for interactive web tasks, form filling, and JavaScript-heavy sites
Skills System and MCP Integration
Autopilot Mode using Ralph Wiggum loops
Project Memory automatically loads project context from MEMORY.md (repository root or ~/.patchpal/repos/<repo-name>/MEMORY.md) at startup.

PatchPal prioritizes customizability: custom tools, custom skills, a flexible Python API, and support for any tool-calling LLM.

Full documentation is here.

Quick Start

$ pip install patchpal          # install
$ patchpal --model <model_id>   # start

Model support: Any LiteLLM-supported model can be used. Platform support: Linux, macOS, and Windows are all supported

Alternative: Run with Docker/Podman (no installation required)

# Using pre-built image with patchpal installed (default model)
docker run -it --rm \
  -v $(pwd):/workspace \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  ghcr.io/amaiya/patchpal-sandbox:latest \
  patchpal --model anthropic/claude-sonnet-4-5

# Or with Podman
podman run -it --rm \
  -v $(pwd):/workspace \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  ghcr.io/amaiya/patchpal-sandbox:latest \
  patchpal --model anthropic/claude-sonnet-4-5

# Specify a different model
docker run -it --rm \
  -v $(pwd):/workspace \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  ghcr.io/amaiya/patchpal-sandbox:latest \
  patchpal --model openai/gpt-5-mini

Setup

Install: pip install patchpal
- Optional: For browser automation (13 additional tools): pip install patchpal[browser] && python -m playwright install chromium
Get an API key or a Local LLM Engine:
- [Cloud] For Anthropic models (default): Sign up at https://console.anthropic.com/
- [Cloud] For OpenAI models: Get a key from https://platform.openai.com/
- [Local] For vLLM: Install from https://docs.vllm.ai/ (free - no API charges) Recommended for Local Use
- [Local] For Ollama: Install from https://ollama.com/ (⚠️ requires OLLAMA_CONTEXT_LENGTH=32768 - see Ollama section below)
- For other providers: Check the LiteLLM documentation
Set up your API key as environment variable:

# For Anthropic (default)
export ANTHROPIC_API_KEY=your_api_key_here

# For OpenAI
export OPENAI_API_KEY=your_api_key_here

# For vLLM - API key required only if configured
export HOSTED_VLLM_API_BASE=http://localhost:8000 # depends on your vLLM setup
export HOSTED_VLLM_API_KEY=token-abc123           # optional depending on your vLLM setup

# For Ollama, no API key required

# For other providers, check LiteLLM docs

Run PatchPal:

# Use default model (anthropic/claude-sonnet-4-5)
patchpal

# Use a specific model via command-line argument
patchpal --model openai/gpt-5.2-codex  # or openai/gpt-5-mini, anthropic/claude-opus-4-5, etc.

# Use vLLM (local)
# Note: vLLM server must be started with --tool-call-parser and --enable-auto-tool-choice
export HOSTED_VLLM_API_BASE=http://localhost:8000
export HOSTED_VLLM_API_KEY=token-abc123
patchpal --model hosted_vllm/openai/gpt-oss-120b

# Use Ollama (local - requires OLLAMA_CONTEXT_LENGTH=32768)
export OLLAMA_CONTEXT_LENGTH=32768
patchpal --model ollama_chat/gpt-oss:120b

# Or set the model via environment variable
export PATCHPAL_MODEL=openai/gpt-5.2
patchpal

Tip for Local Models: Local models (i.e., models served by Ollama or vLLM) may work better with these settings:

PATCHPAL_MINIMAL_TOOLS=true and PATCHPAL_ENABLE_WEB=false - For models with function calling: Provides only essential tools (read_file, read_lines, write_file, edit_file, run_shell), reducing tool confusion
PATCHPAL_REACT_MODE=true - For models without function calling: Enables text-based tool invocation (see ReAct mode docs)
For Ollama, additionally setting PATCHPAL_STREAM_OUTPUT=false may help with tool call reliability

Beyond Coding: General Problem-Solving

While originally designed for software development, PatchPal is also a general-purpose assistant. With web search, file operations, shell commands, and custom tools/skills, it can help with research, data analysis, document processing, log file analyses, etc.

FAQ

There are so many coding agent harnesses. Why build yet another one?

Most agent harnesses are in TypeScript. We wanted something in Python that we could easily extend for our custom workflows.
PatchPal includes a unique guardrails system that is better suited to privacy-conscious use cases involving sensitive data.
We needed an agent harness that seamlessly works with both local and cloud models, including AWS GovCloud Bedrock models.

I noticed there's another package called PatchPal on GitLab. Are they related?

No, they're separate projects. The project with the same name on GitLab is unrelated to this one.

On Windows Subsystem for Linux (WSL), why is it stalling intermittently at "Thinking..."?

This is a known issue with WSL2.

Try examining and then lowering the mtu:

$ cat /sys/class/net/eth1/mtu
1427

$ sudo ip link set eth1 mtu 1400

Documentation

Full documentation is available here.

Release files for patchpal 0.24.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for patchpal 0.24.1
File	Size	Uploaded
patchpal-0.24.1.tar.gz	233.9 kB	Sep 24, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for patchpal 0.24.1
File	Interpreter	ABI	Platform	Reset
patchpal-0.24.1-py3-none-any.whl 189.8 kB Sep 24, 2026	Python 3	none	any	Details

Total release size: 423.7 kB

Release files / patchpal-0.24.1.tar.gz

Download URL	patchpal-0.24.1.tar.gz
Size	233.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`f4d6d23acd00eb0bd7e0bcfc6d43aec5960a68f84121dd9a792934f1b67051ea`
BLAKE2b-256 checksum How to use checksums	`faf6b4cd820363f16c62ac5e1434d7c3205bda3f5b26eddf495a2623b9b4e9b8`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/amaiya/patchpal
Publishing commit: github.com/amaiya/patchpal/tree/7988f1d41e03bbf5b93010cc9087a24b12549e46

Workflow

Publishing configuration: github.com/amaiya/patchpal/blob/7988f1d41e03bbf5b93010cc9087a24b12549e46/.github/workflows/release.yml
Publishing logs: github.com/amaiya/patchpal/actions/runs/36050949157/attempts/1

Artifact

Subject: patchpal-0.24.1.tar.gz
SHA-256 checksum: f4d6d23acd00eb0bd7e0bcfc6d43aec5960a68f84121dd9a792934f1b67051ea Verifying attestations

Release files / patchpal-0.24.1-py3-none-any.whl

Download URL	patchpal-0.24.1-py3-none-any.whl
Size	189.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`2b9ae8ba3347db52b91ea3d00a471c3348357ff0db338a2c92c6ca37c9c549d8`
BLAKE2b-256 checksum How to use checksums	`f1ba2a7222ec8b725a64bce75b62f646317aff76ee6bdaba4a7f1d333553acf6`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/amaiya/patchpal
Publishing commit: github.com/amaiya/patchpal/tree/7988f1d41e03bbf5b93010cc9087a24b12549e46

Workflow

Publishing configuration: github.com/amaiya/patchpal/blob/7988f1d41e03bbf5b93010cc9087a24b12549e46/.github/workflows/release.yml
Publishing logs: github.com/amaiya/patchpal/actions/runs/36050949157/attempts/1

Artifact

Subject: patchpal-0.24.1-py3-none-any.whl
SHA-256 checksum: 2b9ae8ba3347db52b91ea3d00a471c3348357ff0db338a2c92c6ca37c9c549d8 Verifying attestations