Evo-Pi

A local-first coding agent that learns from your own work.

Evo-Pi is an AI coding agent you run in your terminal — like Claude Code or a similar assistant — that reads, edits, and runs code through conversation. What sets it apart: it also learns from how you actually work and proposes narrow, reviewable improvements to its own prompts, skills, and configuration over time.

Under the hood it combines the Pi terminal coding agent with a built-in evolution engine. It records local session evidence, proposes narrow improvements, evaluates them independently, and activates them through deterministic policy or explicit review. Every active personal configuration is an immutable local bundle with rollback history.

Install

Requires Node.js 22.19 or newer (check with node --version).

npm install -g --ignore-scripts @ch1nyzzz/evo-pi
evo-pi

--ignore-scripts skips optional native post-install steps; the evo-pi CLI itself needs no build step and works without them.

The evo-pi executable includes the coding agent and loads Evo automatically. There is no separate Pi installation or pi install step. Upgrade later with evo-pi update --self.

First run

Evo-Pi needs a model provider. On first launch, run /login to connect one — it supports Anthropic, OpenAI, Google, xAI, Groq, DeepSeek, OpenRouter, GitHub Copilot and many others, through OAuth or your own API key. Use whichever account or key you already have; Evo-Pi does not resell model access.

Then initialize the evolution engine once:

/login          connect a model provider (OAuth or API key)
/evo init       set up local evolution state
/evo status     confirm everything is ready

Now just talk to it — ask it to explain code, fix a bug, or build something. From inside a project directory:

> explain what src/cli.ts does
> add a --verbose flag to the CLI and update the tests
> run the tests and fix whatever fails

The evolution engine works quietly in the background from there; see below for how to inspect and control it.

Product and personal-data boundary

The published npm packages contain shared product code only:

• terminal UI, model providers, authentication, sessions, and coding tools
• Recorder, immutable bundle runtime, proposal workflow, evaluation, approval, trials, and rollback
• default workflow templates, schemas, and host-defined component ABIs

Personal evolution state is created at runtime and remains outside the installed package:

${PI_CODING_AGENT_DIR:-~/.pi/agent}/evo/
├── log/                 session evidence
├── session-digests/     derived local metrics
├── inbox/               preference, request, and note candidates
├── bundles/             immutable personal prompts, skills, memory, and preferences
├── proposals/           candidate changes and approval records
├── reports/             local reports and model-usage journal
├── runs/                background evolution runs
├── worktrees/           isolated code candidates
└── registry/            active digest, trials, history, and rollback state

Durable preferences are stored in the active local bundle at bundles/<digest>/memory/preferences.json. User sessions, preferences, memory, bundles, reports, and generated candidates are never included in npm releases or committed back to this repository by Evo-Pi.

Project-owned instructions such as AGENTS.md are separate from personal evolution state and may be shared through the project's own Git repository. Add .pi/evo-private to a project root to disable recording for that project.

Privacy statement

Evo-Pi has no hosted synchronization database; personal evolution state is persisted locally. Model execution still sends the current conversation and selected evidence required for a requested evolution run to the model provider chosen by the user. "Local-first" describes storage and ownership, not offline-only inference.

Evolution loop

local evidence
  → ResearchPlanner: grounded research plan and frozen experiment
  → Builder: one data, component, or isolated code candidate
  → Evaluator: independent evaluation and adversarial review
  → deterministic release policy or explicit human approval
  → reversible trial, keep, or rollback

Useful commands:

/evo help
/evo report
/evo go <research goal>
/evo inspect
/evo list
/evo show <proposal-id>
/evo permit <proposal-id>
/evo rollback

Use evo-pi-admin <command> for non-interactive local administration and external scheduling.

Repository packages

Package	Purpose
@ch1nyzzz/evo-pi	One-command product distribution and evo-pi entry point
@ch1nyzzz/pi-evo	Evolution engine and embedded Pi extension
@ch1nyzzz/pi-coding-agent	Pi terminal coding-agent runtime and SDK
@ch1nyzzz/pi-agent-core	Agent loop and state management
@ch1nyzzz/pi-ai	Multi-provider model API
@ch1nyzzz/pi-tui	Terminal UI library

See packages/evo/README.md for the complete evolution architecture, approval tiers, command reference, and current limitations.

Development

npm install --ignore-scripts
npm run build
npm run check
./test.sh

Create an isolated release install outside the repository:

npm run release:local -- --out /tmp/evo-pi-release --force
/tmp/evo-pi-release/node/evo-pi --help
/tmp/evo-pi-release/node/evo-pi --version

Security

Evo-Pi has the same filesystem and process permissions as the user who launches it. Extensions and coding tools can execute code. Use a container or sandbox when stronger isolation is required. Generated ordinary code candidates remain in isolated worktrees and are not automatically merged or installed.

Report vulnerabilities according to SECURITY.md.

Upstream and license

Evo-Pi is based on Pi. The repository is licensed under the MIT License.