PurrCode

A local-first coding agent with an independent, auditable judgment runtime.

Models propose. PawGate authorizes. Claw executes. Evidence decides.

PurrCode is an open-source coding agent for developers who want more control, transparency, and operational safety when using AI to modify code. It works in isolated Git worktrees, records durable evidence, supports local and remote model providers, and treats repository content, model output, downloaded skills, MCP servers, and web content as untrusted.

Unlike a conventional coding chatbot, PurrCode separates model generation, authorization, execution, validation, and recovery into distinct system responsibilities. The CLI, TUI, and the v1.0 native desktop IDE all share one authoritative daemon-owned session model.

v1.0: the native desktop IDE

PurrCode v1.0 adds its own native desktop IDE — a pure-Rust desktop application, not a browser portal and not an extension inside somebody else’s editor. purrcode ide (or purrcode gui, the same command) opens a real window on the same session the terminal Workbench is running, so you can move between them without losing anything.

• IDE — the native desktop app
• Quick Start
• Modes — task and permission

Install

curl -fsSL https://raw.githubusercontent.com/Weilin0723/PurrCode/v0.9.0/scripts/install.sh | sh

Or via npm: npm install --global @minaovo/purrcode. See Installation for every option, including Windows and building from source.

Guides

• Installation
• Quick Start
• Modes — task and permission
• Providers and Models
• IDE — the native desktop app
• CLI Reference

Concepts

• Architecture
• Security
• Recovery

Reference

• Troubleshooting
• Development and Testing

Repository: https://github.com/Weilin0723/PurrCode · Releases: https://github.com/Weilin0723/PurrCode/releases

Installation

macOS and Linux installer

curl -fsSL https://raw.githubusercontent.com/Weilin0723/PurrCode/v0.9.0/scripts/install.sh | sh

The installer detects the host platform, downloads the release archive, verifies it against the release SHA256SUMS, and installs into ~/.local/bin. Use a custom installation directory:

PURRCODE_INSTALL_DIR="$HOME/bin" \
  curl -fsSL https://raw.githubusercontent.com/Weilin0723/PurrCode/v0.9.0/scripts/install.sh | sh

npm

Node.js 18 or newer:

npm install --global @minaovo/purrcode

The package selects the correct macOS, Linux, or Windows binary, verifies its pinned SHA-256 digest, and exposes both purrcode and purrcoded.

You can also install the signed-release launcher directly from GitHub:

npm install --global https://github.com/Weilin0723/PurrCode/releases/latest/download/purrcode-0.9.0.tgz

Windows

Download and extract purrcode-x86_64-pc-windows-msvc.zip from the latest release.

Build from source

Requirements:

• Rust 1.88 or newer;
• Git;
• platform build tools.

git clone https://github.com/Weilin0723/PurrCode.git
cd PurrCode

cargo install --locked --path crates/purrcode-cli
cargo install --locked --path crates/purrcode-daemon

Verify the install

purrcode --version
purrcoded --version

Upgrade and rollback

purrcode upgrade check --channel stable
purrcode upgrade download /tmp/purrcode-release.tar.gz
purrcode upgrade install --channel stable
purrcode upgrade rollback

install verifies the checksum manifest and both Sigstore bundles before extraction, rejects unsafe archive paths, atomically rotates purrcode and purrcoded, and preserves the prior pair for rollback.

Optional isolation dependencies

• macOS: /usr/bin/sandbox-exec when available.
• Linux: bubblewrap (bwrap).
• Windows: process filtering and job controls; inspect with purrcode sandbox doctor.

PurrCode reports degraded isolation explicitly and does not reinterpret it as a full sandbox.

Quick Start

1. Initialize PurrCode

purrcode init

Initialization:

• discovers supported local providers;
• creates secure local configuration;
• initializes persistence;
• creates a managed workspace;
• starts the authenticated loopback daemon;
• verifies daemon readiness;
• reports sandbox capability.

2. Open a repository

cd path/to/your-project

3. Start the terminal Workbench — or the native IDE

purrcode          # terminal Workbench (default on every platform)
purrcode ide      # native desktop IDE (same as purrcode gui)

4. Connect a model

Inside the TUI or IDE:

/connect

Or import a provider configuration example:

/connect import

Credentials are stored in the operating-system credential store and never enter the model context or tool processes.

5. Submit a task

Examples:

Explain the architecture of this repository.

Add pagination to the orders API and update the tests.

Review the current diff and identify possible regressions.

The composer supports multiline text, source code, logs, JSON, YAML, TOML, and pasted scripts.

Composer shortcuts

Enter          Insert newline
Ctrl+G         Submit
Ctrl+C         Cancel active work

TUI shortcuts

Ctrl+B         Toggle workspace panel
Ctrl+D         Open diff
Ctrl+P         Open command palette
Ctrl+K         Switch task mode
Space or E     Expand selected timeline card
Mouse click    Expand a timeline detail card
Up/Down        Scroll the timeline
Mouse wheel    Scroll the timeline
?              Open help
Ctrl+C         Cancel active work

Typical workflow

Describe task
  ↓
Review plan
  ↓
Inspect retrieved context
  ↓
Approve or reject proposed actions
  ↓
Review execution output
  ↓
Inspect diff
  ↓
Review validation evidence
  ↓
Apply, commit, export, or rollback

For the full command and slash-command list, see CLI Reference.

Modes

PurrCode separates two kinds of modes: task modes and permission modes. Both are shown in the header and travel with the session, so a read-only mode is a constraint the daemon enforces rather than a hint.

Task modes

Ctrl+K / /mode switches between:

To start executing a plan you settled on, use Build this plan or /resume in the same session.

Permission modes

/permission switches between:

Full Access does not grant any permission the process does not already hold. Read-only modes refuse mutation; the daemon enforces the boundary.

Adaptive workflow

New sessions use a daemon-resolved auto task mode. Based on task evidence, the daemon selects a workflow profile:

The TUI header also shows the current workflow and search policy; /usage exposes the recorded token/cost ledger.

Providers and Models

PurrCode supports:

• Ollama;
• LM Studio;
• OpenAI;
• OpenAI-compatible APIs;
• enterprise gateways;
• NVIDIA NIM;
• environment-backed credentials;
• operating-system credential stores;
• custom CA bundles;
• proxies;
• mTLS;
• secret-backed headers.

Provider discovery

Inside the TUI or IDE:

/connect

PurrCode probes supported local endpoints and displays observed availability. Local discovery does not generate model output and does not load an unloaded model.

Import provider configuration

/connect import

Supported source formats: Python, JavaScript, TypeScript, cURL, JSON, YAML, TOML, and dotenv. PurrCode parses imported configuration without executing it, and can extract provider type, base URL, model ID, API mode, request defaults, custom headers, authentication configuration, and local-or-remote classification.

Secret handling during import

Detected secrets remain in transient zeroizing memory until you choose one of:

• store the secret in the operating-system credential store;
• convert it to an environment-variable reference;
• discard it.

Raw secret values are never written into provider configuration or conversation events.

Manage credentials

purrcode credential set openai

Configuration stores a reference such as keychain:openai; the secret itself remains in the operating-system credential store.

Provider profiles

/provider list
/provider edit <name>
/provider test <name>
/provider remove <name>

Provider diagnostics

purrcode provider doctor

PurrCode classifies provider failures such as connection refused, DNS failure, TLS failure, authentication failure, HTTP error, content-type mismatch, incompatible schema, streaming framing failure, unsupported API mode, model not found, context too large, out of memory, and cancellation.

Local models

Ollama

PurrCode supports Ollama’s native API and inspects /api/version, /api/tags, /api/ps, and /api/chat. Native Ollama mode is separate from OpenAI-compatible mode, so API-mode mismatches are detected instead of surfacing as generic decoding errors.

LM Studio

PurrCode can discover LM Studio and compatible local endpoints running on loopback. Local-only mode rejects undeclared remote providers and does not silently fall back to cloud inference.

NVIDIA NIM

NVIDIA_API_KEY is detected during onboarding and models are enumerated from the NIM endpoint. NIM is a first-class provider.

Local model commands

/model recommend
/model qualify <model>
/model loaded
/model unload <model>
/model unload-all

Recommendations use observed evidence — model metadata, qualification, physical and available memory, swap pressure, loaded-model memory, context requirements, structured-output reliability, measured latency, and tool-calling support. A model is not recommended only because its name contains terms such as coder.

Pulling a model

When a recommended Ollama model is not installed, PurrCode can propose a governed pull action that requires explicit authorization, uses an exact validated model identifier, reports bounded progress, supports cancellation, and rediscovers models on completion.

Model lifecycle policies

Supported policies: unload_after_request, idle_timeout, keep_loaded, external. Low-memory systems use conservative concurrency and unload behavior. Opening PurrCode does not automatically generate output or load an unloaded model.

IDE — the native desktop app

PurrCode v1.0’s graphical product is a pure-Rust native desktop IDE (eframe/egui). It is not a browser portal and not an extension inside somebody else’s editor. purrcode ide and purrcode gui are the same command; neither ever opens a browser.

Launch

purrcode ide --repository "$PWD"

Or from inside the terminal Workbench:

/ide

purrcode resume --tui and purrcode ide attach to the same daemon session in both directions — you can move between the terminal and the desktop window without losing anything.

The IDE starts or reuses a compatible authenticated local daemon. It never resumes a session implicitly; reopen work with an explicit --session UUID --repository PATH.

What it draws

• an application bar and icon rail;
• session navigation grouped by Today/Yesterday/date, with unread activity marked by a dot;
• a project tree and workspace source-control rail (branch, dirty-file count, ten bounded recent commits);
• a conversation Workbench with a composer and a collapsed, height-bounded Work log;
• a syntax-highlighted editor with tabs, file-type colour icons, a bounded minimap, and cursor position;
• a docked Diff / Tests / Terminal / Problems / Output panel.

Terminal, diff, and validation

• The native terminal uses the daemon’s typed PTY routes and the shared ANSI screen buffer: incremental output, input, stop, reconnect-safe offsets, and ownership generations.
• Diff review exposes daemon hunk digests plus Apply/Reject actions.
• Problems and tests are sourced from the daemon’s truthful validation artifacts. Missing or skipped evidence renders as unavailable/pending, never as passing.

Settings

Native settings are grouped around appearance, models/providers, authority, agent behavior, context/skills, terminal/Git, privacy/recovery, and diagnostics. They apply the selected Light/Dark/High-contrast appearance without writing repository state and expose explicit Apply/Reset actions. The IDE never accepts a provider secret — credentials use keychain references only.

Boundaries

• The IDE owns no session store, no model state, no permission state, and no execution path. All state flows through the daemon.
• All HTTP runs on a worker thread and reaches the UI through channels, so an unreachable daemon reports itself as disconnected instead of freezing the window.
• purrcode studio remains a secure browser maintenance/development client. It is not the v1.0 release IDE and nothing routes to it automatically.

CLI Reference

General

purrcode init                          # discover local providers, write secure defaults, start the daemon
purrcode                               # terminal Workbench (default)
purrcode ide                           # native desktop IDE (same as purrcode gui)
purrcode studio                        # authenticated browser maintenance client
purrcode plan "Describe the change"    # plan first, write nothing
purrcode run "Implement the change"    # implement and validate
purrcode sessions                      # review active sessions
purrcode review                        # review the current diff
purrcode approve                       # approve a proposed action
purrcode reject                        # reject a proposed action
purrcode cancel                        # cancel a session
purrcode resume                        # resume a paused plan in the same session
purrcode rollback                      # roll back isolated work
purrcode doctor                        # environment diagnostics
purrcode export-patch                  # export the isolated-worktree patch
purrcode apply                         # apply the reviewed patch

Providers

/connect
/connect import
/provider list
/provider edit <name>
/provider test <name>
/provider remove <name>

Models

/model recommend
/model qualify <model>
/model loaded
/model unload <model>
/model unload-all

Skills, MCP, and capability

/skills search <query>
/mcp search <query>
/capability add <description>

Credentials and configuration

purrcode credential set <provider>     # store a keychain reference
purrcode credential delete <name>
purrcode config migrate                # migrate configuration files
purrcode config migration-preview      # preview a configuration migration

Upgrade

purrcode upgrade check --channel stable
purrcode upgrade download /tmp/purrcode-release.tar.gz
purrcode upgrade install --channel stable
purrcode upgrade rollback

Evaluation and evidence

purrcode benchmark list
purrcode benchmark validate-cases
purrcode benchmark run --output benchmark.json
purrcode benchmark report benchmark.json
purrcode trace show latest
purrcode trace export latest
purrcode explain completion latest
purrcode bundle export latest evidence.json
purrcode bundle verify evidence.json
purrcode bundle replay evidence.json

TUI controls

Enter          Insert newline
Ctrl+G         Submit
Ctrl+B         Toggle workspace panel
Ctrl+D         Open diff
Ctrl+P         Open command palette
Ctrl+K         Switch task mode
Space or E     Expand selected timeline card
Mouse click    Expand a timeline detail card
Up/Down        Scroll the timeline
Mouse wheel    Scroll the timeline
?              Open help
Ctrl+C         Cancel active work

Terminal support for modified Enter combinations varies. The TUI footer displays the portable active shortcut.

Architecture

PurrCode is organized around four primary subsystems.

The simplified runtime flow is:

User task
  ↓
Repository context
  ↓
Model proposal
  ↓
PawGate policy and judgment
  ↓
Durable exact-action authorization
  ↓
Claw verification and isolated execution
  ↓
Validation evidence
  ↓
Review, apply, commit, export, or rollback

Core principles

1. Model output is a proposal, not authority. A model may recommend an action, but it cannot authorize its own execution.
2. Execution is isolated. Coding work runs in detached Git worktrees under PurrCode-managed storage. Your active working tree is not silently modified, overwritten, stashed, or discarded.
3. Completion requires evidence. Passed, failed, timed out, unavailable, undetected, skipped, and uncertain are distinct states. Skipped or unavailable validation is never reported as success.
4. Recovery is conservative. Interrupted actions are not blindly replayed. NineLives restores durable state and flags uncertain effects for explicit review.
5. Local-first does not mean resource-unaware. Ollama and LM Studio are supported while avoiding unnecessary model loading during startup.
6. External capabilities remain governed. Skills, MCP servers, downloaded packages, web research, and repository content are untrusted inputs.

The model provider is outside the trusted boundary

A provider can generate a proposal, but it cannot directly authorize or execute that proposal.

Shared session state

The CLI, TUI, and native IDE use the daemon-owned runtime instead of independent competing agent loops. All state flows through the daemon — the IDE owns no session store, no model state, no permission state, and no execution path. The daemon exposes typed presentation endpoints (activity, validation, summary, usage) so clients share one vocabulary instead of each inventing a reading of the durable event log.

For the durable security properties, see Security. For recovery behavior, see Recovery.

Security

PurrCode assumes the following may be untrusted:

• model output;
• repository content;
• downloaded skills;
• MCP servers;
• web content;
• imported configuration;
• generated commands;
• tool output.

Authorization binding

PawGate authorizes the exact serialized action and constraints. Claw verifies the authorization again immediately before execution.

Authorizations are:

• durable;
• digest-bound;
• single-use;
• consumed atomically.

A model can never create, widen, re-scope, impersonate, escalate, or hide a grant.

Process execution

PurrCode uses explicit argument vectors rather than shell command strings. Execution environments are scrubbed of credentials unless an explicitly authorized capability receives a secret reference.

Repository isolation

Agent work runs in detached Git worktrees under PurrCode-managed storage. Existing uncommitted work is not silently stashed, overwritten, discarded, or copied into the isolated worktree.

Sandbox support

PurrCode uses available host isolation:

• macOS: sandbox-exec when available;
• Linux: Bubblewrap when available;
• Windows: process filtering and job controls.

Inspect the current host environment:

purrcode sandbox doctor

Degraded isolation is reported explicitly and is not represented as a full sandbox.

Secret protection

Provider keys and secret-like values are:

• detected before durable conversation persistence;
• redacted from diagnostic excerpts;
• stored using keychain or environment references;
• scrubbed from tool and plugin child environments;
• excluded from imported-source review output.

Security documentation

Read the repository’s security model, architecture, and production acceptance audit before using PurrCode for sensitive repositories.

Recovery

NineLives maintains durable session events and checkpoints.

Recovery behavior includes:

• restart reconciliation;
• uncertain-action detection;
• preserved isolated worktrees;
• session resume;
• manual checkpoints;
• isolated rollback;
• partial-output preservation after cancellation;
• lease-conflict handling.

Interrupted actions are not automatically replayed. When the runtime cannot prove whether an action completed, it marks the result as uncertain and requires review.

Resume

purrcode resume

Resumes a paused plan in the same session. purrcode resume --tui reattaches the terminal Workbench.

Rollback

purrcode rollback

Rolls back isolated work. Rollback requires an exact preview digest and explicit acknowledgement of any unattributed effects; invalid event append or replay fails loudly.

Recovery evidence

The repository’s recovery documentation and troubleshooting guide cover durable state and failure behavior in detail.

Troubleshooting

Environment diagnostics

purrcode doctor --repository "$PWD"

doctor performs bounded, read-only project and host detection, records real version probes, and returns one evidence-bearing plan with detected, missing, install, and verification records. A missing tool is reported explicitly — never as installed or ready.

purrcode sandbox doctor

Reports the host’s real isolation capability. Degraded isolation is reported accurately and is not represented as a full sandbox.

purrcode provider doctor

Classifies provider failures — connection refused, DNS failure, TLS failure, authentication failure, HTTP error, content-type mismatch, incompatible schema, streaming framing failure, unsupported API mode, model not found, context too large, out of memory, cancellation.

Known limitations

PurrCode is under active development. Before using it with sensitive repositories, review:

• current implementation status;
• host sandbox capability;
• provider qualification results;
• release acceptance evidence;
• platform-specific limitations.

Important considerations:

• not every provider has been live-tested on every platform;
• some model capabilities remain unknown until qualification;
• weak host isolation cannot provide the same guarantees as a supported OS sandbox;
• local model quality and memory requirements vary by model and quantization;
• reduced-independence mode may use the same model for proposal and judgment;
• external skills and MCP servers remain untrusted until qualified;
• a successful unit test suite does not replace testing against your exact provider and environment.

Where to go next

• The repository’s troubleshooting guide
• The implementation status for verified capabilities and remaining gates
• Open an issue at https://github.com/Weilin0723/PurrCode/issues

Development and Testing

Build

Requirements:

• Rust 1.88 or newer;
• Git;
• platform build tools.

git clone https://github.com/Weilin0723/PurrCode.git
cd PurrCode

cargo install --locked --path crates/purrcode-cli
cargo install --locked --path crates/purrcode-daemon

Repository checks

Run from the project root:

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

npm test --prefix packages/purrcode
npm test --prefix sdk/typescript

PYTHONPATH=sdk/python/src \
  python3 -m unittest discover -s sdk/python/tests -v

Implementation status

PurrCode is under active development. See the repository’s implementation status and the PurrCode v1.0 Master PRD for milestone status, verified capabilities, and remaining platform-specific gates.

Contributing

Contributions are welcome. Before opening a pull request:

1. review the architecture and security documentation;
2. preserve the existing trust boundaries;
3. do not allow model providers to authorize actions;
4. keep external content and downloaded skills untrusted;
5. add deterministic tests;
6. run formatting, Clippy, and workspace tests;
7. document unsupported or skipped validation honestly.

Suggested contribution areas:

• provider compatibility;
• terminal usability;
• qualification fixtures;
• cross-platform sandboxing;
• documentation;
• accessibility;
• performance;
• skill and MCP catalogs;
• model recommendation evidence;
• integration testing.