PatchPilot

A local-first coding agent TUI for safe patching, guided setup, and observable runs with high efficiency using a custom token-caching system.

---

Showcase

---

!!!Security and legal notice!!!

PatchPilot is an experimental coding agent that can read/write files and run shell commands when those capabilities are enabled. Use it only in repositories and environments you trust.

I don't want to scare people. But I must point out that using PatchPilot involves risks and that I am not liable for any problems or damages that may arise.

Security notice

• No zero-risk guarantee: LLM-driven tooling can make incorrect or unsafe suggestions. Always review diffs and commands before applying them.
• Sensitive data handling: Never expose private keys, passwords, tokens, credentials, or confidential code to providers you do not fully trust.
• Provider data flow: Local provider (ollama) keeps inference on your own infrastructure. Cloud providers (gemini, codex) may process prompts and context remotely under their own terms.
• Permission model: Keep write and shell permissions disabled unless needed. Enable them only for the current task and disable afterward.
• Workspace boundary: Run PatchPilot in a dedicated project root and avoid mixing unrelated sensitive material in that workspace.
• User responsibility: You are responsible for reviewing, testing, and validating all generated changes before merge, deployment, or production use.

Legal notice

• License: This project is provided under the MIT License.
• No warranty: The software is provided "AS IS", without warranties of any kind, express or implied.
• Limitation of liability: The authors and contributors are not liable for damages, data loss, security incidents, or other consequences resulting from use or misuse.
• Third-party services: Use of model providers and external services is subject to their own terms, privacy policies, retention settings, and regional compliance requirements.
• Compliance: If you process personal, regulated, or company-restricted data, ensure your usage complies with applicable law, contracts, and internal policies.

Responsible disclosure

If you discover a security issue, please do not publish exploit details immediately. Open a private security report via GitHub Security Advisories or contact the maintainer directly, and include reproduction steps and impact.

PatchPilot is designed for transparent, user-controlled operation, but safe usage requires deliberate permission control, careful review, and standard engineering safeguards.

---

Enough with the legal stuff, now to the good and unique things about PatchPilot!

Contents

• PatchPilot
  • Showcase
• !!!Security and legal notice!!!
  • Security notice
  • Legal notice
  • Responsible disclosure
• Enough with the legal stuff, now to the good and unique things about PatchPilot!
  • Contents
  • Highlights
  • Why This Exists
  • Current Workflow
  • Tech Stack
  • Requirements
  • Quick Start
  • Usage
  • Remote Ollama
  • Safety Model
  • Development
  • Roadmap
  • License

---

Highlights

Feature	Description
Local-first agent	Talks to an Ollama server running on your machine by default
Guided onboarding	Dedicated setup window for provider, auth, and model selection
Gemini API provider	Can switch to Gemini through ~/.patchpilot/config.env
Codex OAuth provider	Can use your ChatGPT Plus/Pro Codex CLI login through codex exec
TUI workflow	Ink-powered terminal UI with transcript, telemetry, arrow-key palette, and setup wizard
Workspace boundary	File tools refuse to read or write outside the selected project root
Explicit permissions	Writes require --apply; shell execution requires --allow-shell and stays on a restricted single-command runner
Runtime telemetry	Header shows CPU, memory, GPU, VRAM, temperature, power, live prompt tokens, request tokens, cache hits, estimated session cost, generation speed, and latency
Remote Ollama	/connect scans the LAN and only lists hosts that answer Ollama's /api/version endpoint
Compute target awareness	The TUI marks Ollama as local/remote and Gemini/Codex as cloud inference
Advisor subagents	Planner and reviewer subagents give the primary agent a short tactical brief before it starts
Tool-visible loop	The model can list files, read files, search text, write files, and run commands
JSON agent protocol	Model responses are parsed through a typed command envelope
CI-ready repo	TypeScript build, tests, and GitHub Actions are included from day one

Why This Exists

Local LLMs are useful for coding, but most local agent experiments either feel like raw scripts or hide too much of what is happening. PatchPilot aims for the middle ground: a polished TUI that stays honest about every file read, write, search, and command.

The first target is a practical developer workflow: open a repository, describe the patch, let the local model inspect context, and keep the user in control of risky actions.

Current Workflow

1. Start Ollama and pull a coding model such as qwen2.5-coder:7b.
2. Open a project directory.
3. Run PatchPilot with a task prompt.
4. Watch the agent inspect files and request tools.
5. Enable writes or shell commands only when you intentionally want them.
6. Review the resulting Git diff before committing.

---

Tech Stack

Layer	Technologies
Language	TypeScript, strict NodeNext ESM
Runtime	Node.js 22 or newer
TUI	Ink, React, ink-text-input
Agent protocol	JSON command envelope validated with Zod
Model providers	Ollama chat API, Gemini generateContent API, Codex CLI OAuth backend with JSON usage telemetry
Tests	Vitest
CI	GitHub Actions

Requirements

• Node.js 22 or newer
• npm 10 or newer
• Git
• Ollama for local or remote model execution, a Gemini API key, or Codex CLI login
• A pulled local model, for example qwen2.5-coder:7b, PatchPilot config in ~/.patchpilot/config.env, or codex login

---

Quick Start

Install dependencies:

npm install

Start Ollama and pull a model:

ollama pull qwen2.5-coder:7b

Or use guided setup:

patchpilot

Then open /onboarding or follow the first-run setup window. Gemini keys are stored in ~/.patchpilot/config.env.

Or use Codex OAuth through your ChatGPT plan:

codex login
patchpilot --provider codex --model gpt-5.4

Run PatchPilot in a repository:

patchpilot

Then type normal tasks directly into the TUI:

summarize this repository

Use slash commands inside the TUI:

/help
/onboarding
/mode build
/write on
/shell on
/provider gemini
/provider codex
/model uncensored
/connect http://192.168.1.50:11434
/doctor

Usage

patchpilot [task] [options]

Option	Description
--workspace <path>	Project root the agent may inspect
--provider <name>	Model provider: ollama, gemini, or codex
--model <name>	Model name, defaults to qwen2.5-coder:7b, gemini-2.5-flash, or gpt-5.4
--ollama-url <url>	Ollama base URL, defaults to http://127.0.0.1:11434
--steps <count>	Maximum agent steps before stopping
--apply	Allows file writes inside the workspace
--allow-shell	Allows shell commands inside the workspace
--no-subagents	Disables planner/reviewer advisor calls for faster local runs

Run diagnostics:

patchpilot doctor

The doctor command checks Node, Git, and the active provider. For Ollama, it checks the Ollama CLI/server and whether the selected model is pulled locally. For Gemini, it checks GEMINI_API_KEY, the models API, and whether the selected model is listed. For Codex, it checks the Codex CLI and your local ChatGPT OAuth login. Use patchpilot doctor --provider codex when testing Codex OAuth.

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

Inside the TUI, use /help to see available commands. Slash-command discovery now behaves like a palette: type /, move with up/down, press Enter to run or fill the selected command. Permissions can be changed without restarting:

The transcript and session sidebar have internal scroll windows. With an empty prompt, use left/right to choose the sidebar or transcript, then Page Up/Page Down to scroll and Home/End to jump.

Slash command	Description
/help	Show available commands
/	Open the interactive command palette while typing
/onboarding	Open the guided setup window for local-vs-host choice, auth, and model selection
/permissions	Show current write and shell permissions
/agents on|off	Enable or disable planner/reviewer advisor subagents
/provider ollama|gemini|codex	Switch between Ollama, Gemini API, and Codex OAuth inference
/mode plan	Read-only planning mode
/mode build	Implementation mode; writes and shell can be enabled
/plan	Shortcut for /mode plan
/build	Shortcut for /mode build
/write on|off	Enable or disable workspace writes
/shell on|off	Enable or disable shell commands
/model <name>	Switch the model for the current provider
/models	Refresh models for the current provider and open them in the palette
/models <number>	Select a model from the last /models list
/model uncensored	Switch to huihui_ai/qwen2.5-coder-abliterate:7b
/model default	Switch back to qwen2.5-coder:7b
/connect	Auto-scan the LAN and Tailscale peers for reachable Ollama servers
/connect <url>	Connect to another Ollama host for the current session
/connect <number>	Connect to a numbered host from the /connect list
/connect local	Switch back to local Ollama at 127.0.0.1:11434 on non-macOS clients
/hosts	Re-scan reachable Ollama hosts
/doctor	Check Node, Git, and the active provider from inside the TUI
/clear	Clear the current transcript
/exit	Quit PatchPilot

Remote Ollama

PatchPilot can run the agent on one machine while using an Ollama server on another machine. This is useful when your Windows desktop has the GPU and your MacBook is where you are editing code.

At startup, the guided setup now asks whether inference should run on This Device or a Remote Host. Host mode walks through LAN/Tailscale discovery first, then fetches the host's models before letting you choose one.

By default, PatchPilot talks to Ollama at http://127.0.0.1:11434 on macOS, Windows, and Linux. On macOS, install and start Ollama.app, pull a model, then run PatchPilot directly:

ollama pull qwen2.5-coder:7b
patchpilot

PatchPilot keeps file reads, file writes, shell commands, Git, and tests on the machine where the TUI runs. Only model requests go to the selected Ollama server.

When connected to a remote Ollama server, patchpilot doctor treats the local Ollama CLI as optional because the selected compute target is another machine. Node.js and Git are still checked locally because workspace tools still run on the client.

For Apple Silicon Macs with less memory, tune the request budget before starting PatchPilot:

PATCHPILOT_NUM_CTX=4096 PATCHPILOT_NUM_PREDICT=768 patchpilot

To use a stronger remote GPU host from the MacBook, switch inside the TUI:

/connect
/connect 1

If both machines are on the same Tailscale tailnet, PatchPilot also checks Tailscale peers and MagicDNS names during /connect and the startup host flow. A host can be selected by Tailscale IP, MagicDNS name, or full URL.

On a Windows desktop or another remote machine, expose Ollama on the LAN:

1. Quit Ollama from the taskbar.
2. Add a user environment variable named OLLAMA_HOST with value 0.0.0.0:11434.
3. Start Ollama again from the Start menu.
4. Allow inbound TCP traffic on port 11434 in the Windows firewall for your private network.

From the MacBook, run PatchPilot inside the project you want to edit and connect to the desktop:

patchpilot --ollama-url http://<windows-pc-ip>:11434

Or switch inside the TUI from any supported platform:

/connect
/connect 1
/connect http://<windows-pc-ip>:11434
/connect local

The scan verifies GET /api/version, so it does not list random local interfaces or machines that merely have port 11434 open. When connected, the header/sidebar switch to the selected host's device name, route, version, and model inventory instead of showing the client machine as the compute target.

Safety Model

PatchPilot is designed to make local execution boring in the best way:

• File access is constrained to a single workspace root.
• Secret-like files such as .env, .npmrc, SSH keys, and .netrc are blocked from normal file tools.
• Write tools are disabled unless --apply is set.
• Shell tools are disabled unless --allow-shell is set.
• Shell commands are restricted to simple single commands with blocked metacharacters, interpreters, absolute paths, and .. traversal.
• Provider config is stored in ~/.patchpilot/config.env, not in the current repository by default.
• Tool output is fed back into the agent in clipped form instead of hidden from the user.
• The TUI surfaces CPU, memory, GPU utilization, VRAM, temperature, power draw, live prompt tokens, token counts, Codex cache hits, estimated session cost, token throughput, and request latency.

Codex OAuth runs codex exec --json and reads the CLI's turn.completed.usage event, including cached input tokens. Session cost is an estimate based on public API token pricing where available; actual ChatGPT-plan quota behavior is controlled by Codex/ChatGPT plan limits.

This does not make local or cloud-backed agents harmless. Review diffs before committing, and do not point remote providers at repositories containing secrets you would not intentionally send off-box.

Development

Run the development TUI:

npm run dev -- "summarize this repository"

Typecheck:

npm run typecheck

Run tests:

npm test

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

Build:

npm run build

Roadmap

Area	Planned Work
Patch review	Rich diff preview before writes
Permissions	Interactive approve/deny prompts per risky tool call
Agents	Dedicated editor and test-runner roles with hard tool boundaries
Memory	Repository summaries and local task state
Model support	Native Ollama tool-calling when model support is reliable
Distribution	Tauri shell with PatchPilot CLI sidecar for signed macOS and Windows releases
Efficiency	Token-caching for better performance

License

PatchPilot is released under the MIT License.