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`).
```bash
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:
```text
/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:
```text
> 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:
```text
${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//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
```text
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:
```text
/evo help
/evo report
/evo go
/evo inspect
/evo list
/evo show
/evo permit
/evo rollback
```
Use `evo-pi-admin ` for non-interactive local administration and external scheduling.
## Repository packages
| Package | Purpose |
|---|---|
| [`@ch1nyzzz/evo-pi`](packages/evo-pi) | One-command product distribution and `evo-pi` entry point |
| [`@ch1nyzzz/pi-evo`](packages/evo) | Evolution engine and embedded Pi extension |
| [`@ch1nyzzz/pi-coding-agent`](packages/coding-agent) | Pi terminal coding-agent runtime and SDK |
| [`@ch1nyzzz/pi-agent-core`](packages/agent) | Agent loop and state management |
| [`@ch1nyzzz/pi-ai`](packages/ai) | Multi-provider model API |
| [`@ch1nyzzz/pi-tui`](packages/tui) | Terminal UI library |
See [`packages/evo/README.md`](packages/evo/README.md) for the complete evolution architecture, approval tiers, command reference, and current limitations.
## Development
```bash
npm install --ignore-scripts
npm run build
npm run check
./test.sh
```
Create an isolated release install outside the repository:
```bash
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`](SECURITY.md).
## Upstream and license
Evo-Pi is based on [Pi](https://pi.dev). The repository is licensed under the [MIT License](LICENSE).