PatchPilot is a terminal interface for running coding-agent tasks inside a repository. It shows what the agent is doing, keeps risky actions behind explicit permissions, and supports local Ollama, remote Ollama, Google Gemini, OpenRouter, NVIDIA NIM-compatible endpoints, and Codex CLI OAuth.

• Highlights
• Why This Exists
• Quick Start
• Usage
• Providers
• Remote Ollama
• Safety Model
• Tech Stack
• Development
• Roadmap
• Security and Legal
• License

Most local coding-agent experiments fall into one of two traps: they are either raw scripts that feel painful to use, or polished tools that hide too much of what is happening. PatchPilot aims for the middle: a practical TUI where every file read, search, proposed write, command, model route, and token/cost signal stays visible.

The core workflow is intentionally simple:

1. Open a repository.
2. Pick local, remote, or cloud inference.
3. Ask for a patch, review, summary, or refactor plan.
4. Enable writes or shell commands only when the current task needs them.
5. Review the diff before committing.

Install the public CLI globally:

npm install -g @jx-grxf/patchpilot

For source development, clone it, install dependencies, build it, and link the local CLI:

git clone https://github.com/jx-grxf/PatchPilot.git
cd PatchPilot
npm install
npm run build
npm link

For local Ollama inference:

ollama pull qwen2.5-coder:7b
patchpilot doctor
patchpilot

Then type a task inside the TUI:

summarize this repository and point out the riskiest files

For a one-shot task from a different repository:

cd /path/to/your/project
patchpilot "find likely test gaps in this repo"

Use build permissions only when you intentionally want PatchPilot to modify files or run commands:

patchpilot "add tests for the parser" --apply --allow-shell

API keys are stored by onboarding in ~/.patchpilot/.env.

patchpilot [task] [options]
patchpilot doctor [options]

Useful slash commands inside the TUI:

The transcript and sidebar have internal scroll areas. With an empty prompt, use left/right to choose the sidebar or transcript, then Page Up/Page Down and Home/End to navigate long sessions.

Examples:

patchpilot --provider ollama --model qwen2.5-coder:7b
patchpilot --provider gemini --model gemini-2.5-flash
patchpilot --provider openrouter --model openrouter/auto
patchpilot --provider nvidia --model meta/llama-3.1-70b-instruct
patchpilot --provider codex --model gpt-5.5
patchpilot --provider google --model gemini-2.5-flash
patchpilot --provider nim --model meta/llama-3.1-70b-instruct
patchpilot --provider openai --model gpt-5.5

Provider diagnostics:

patchpilot doctor --provider ollama
patchpilot doctor --provider gemini
patchpilot doctor --provider openrouter
patchpilot doctor --provider nvidia
patchpilot doctor --provider codex

PatchPilot caches model discovery for a short TTL inside the running TUI, so normal prompts do not re-query providers every time. Run /models again when you intentionally want to refresh the visible list.

PatchPilot reads provider cache telemetry when the provider reports it, for example Codex cached input tokens or OpenRouter prompt_tokens_details.cached_tokens, then displays cache hit rate as cached / input.

OpenRouter :free models are rate-limited by OpenRouter. PatchPilot warns when a selected model ID ends in :free.

PatchPilot can run the TUI and workspace tools on one machine while sending model requests to Ollama on another machine. This is useful when your desktop has the GPU and your laptop is where you edit code.

Inside PatchPilot:

/connect
/connect 1
/connect http://192.168.1.50:11434
/connect local

From the shell:

patchpilot --ollama-url http://<host-ip>:11434

On a Windows desktop or remote host, expose Ollama on your private network:

1. Quit Ollama.
2. Set OLLAMA_HOST to 0.0.0.0:11434.
3. Start Ollama again.
4. Allow inbound TCP traffic on port 11434 only on trusted private networks.

PatchPilot verifies candidates with Ollama's /api/version endpoint before listing them. It does not move file reads, writes, Git, or test commands to the remote host; only model requests are routed there.

For smaller local machines, reduce the request budget before starting PatchPilot:

PATCHPILOT_NUM_CTX=4096 PATCHPILOT_NUM_PREDICT=768 patchpilot

PatchPilot is designed to keep powerful actions boring and reviewable:

• File access is constrained to one workspace root.
• Secret-like files such as .env, .npmrc, SSH keys, and .netrc are blocked from normal file tools.
• Writes are disabled unless --apply is set.
• Shell commands are disabled unless --allow-shell is set.
• Shell execution uses a restricted single-command runner.
• Provider config is stored in ~/.patchpilot/.env, not in the current repository by default.
• Tool output is shown in the transcript and fed back into the agent in clipped form.
• Cloud providers may process prompts and context remotely under their own terms.

This is still experimental agent tooling. Review diffs, avoid sensitive repositories when using cloud providers, and do not enable write or shell permissions casually.

More detail: docs/architecture.md

Run the TUI from source:

npm run dev -- "summarize this repository"

Typecheck, test, and build:

npm run typecheck
npm test
npm run build

If Vitest fails because a native optional dependency was installed incorrectly, run npm ci again before debugging PatchPilot itself.

PatchPilot can read files, write files, and run shell commands when you enable those capabilities. Use it only in repositories and environments you trust.

• Security reports: please use GitHub Security Advisories or contact the maintainer privately with reproduction steps and impact.
• License: this project is provided under the MIT License.
• Warranty: the software is provided "AS IS", without warranties of any kind.
• Third-party services: model providers and external services are subject to their own terms, privacy policies, retention settings, and regional compliance requirements.

PatchPilot is released under the MIT License.