---
slug: "pi-precognition"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/ultronisnice/pi-precognition@main/README.md"
repo: "https://github.com/ultronisnice/pi-precognition"
source_file: "README.md"
branch: "main"
---
# pi-precognition
Coding agents that wait less the longer they run.
---
v0.3 ships the core substrate for **persistent, cross-session personal anticipation** — the foundation that lets an agent learn how *you* actually work and start reducing the repetitive friction in your workflow.
This is the first release where the system moves beyond local, session-scoped guessing into durable, learnable patterns that survive across restarts and projects.
→ **[Install](#install)** · **[Reproduce](https://github.com/ultronisnice/pi-precognition/blob/HEAD/challenges/003-reproduce-the-baseline.md)** · **[Build a future](https://github.com/ultronisnice/pi-precognition/blob/HEAD/docs/build-a-future.md)**
---
## Why now
For many coding-agent workflows, tool execution — not model inference — is the largest source of perceptible latency. v0.2 proved that *some* of that wait is avoidable by warming safe futures while the operator drafts: a 15-second `npm test` served in 29 ms through wrapped Pi-compatible tools, zero hidden context injection. v0.3 extends that proof across sessions: the model of *what's likely to matter* now persists, so the system gets steadily better at the work *you* actually do.
---
## The Leap (v0.2 → v0.3)
**v0.2** was speculative warming. It watched your draft and tried to pre-compute expensive results in the moment. It was useful, but fundamentally short-term and stateless.
**v0.3** introduces the real building blocks for something that compounds:
- A **Pattern Library** that persists across sessions and projects.
- A **Mutation Stream** that re-arms futures when your files change.
- An **Anticipation Planner** that turns observed behavior into bounded, actionable plans.
- A **Future Compose API** that makes it straightforward for anyone to add new future classes.
- First-class CLI surfaces (`doctor`, `patterns`, `watch`, `bench`) so you can see and interact with the system directly.
This is the shift from a clever local cache to the early form of a system that can build a model of its operator over time.
---
## Who This Is For Right Now
pi-precognition v0.3 is built for people who do **long, focused, or autonomous sessions** on the same codebase(s) over hours and days.
It gets better the longer you stay in the same project. The more repetition the system sees, the stronger the patterns become. If your work involves repeated reads of the same modules and frequent expensive commands (typecheck, test, build, etc.), you will feel the difference over time.
If you mostly do short sessions or constantly jump between unrelated tasks, the value will be lower until more surfaces are added.
---
## The Headline Number
On the slow-command workload (a `bash("npm test")` that takes 15 seconds, with 17s of draft budget), `pi-precognition` drops the blocked tool wait from **15.2 seconds to 29 milliseconds** — a **522× collapse** of the dominant latency cost.
| Metric | Baseline | With `pi-precognition` | Speedup |
|---|---:|---:|---:|
| Blocked tool wait | 15,234 ms | 29 ms | **522×** |
| First tool result | 18.4 s | 3.2 s | **5.8×** |
| Task completion | 21.9 s | 6.6 s | **3.3×** |
| Hidden injections | n/a | 0 | — |
| Quality parity | n/a | 100% | — |
**n=3 paired live runs. Boundary: deterministic-class agent turns only.** See [`docs/benchmarks.md`](https://github.com/ultronisnice/pi-precognition/blob/HEAD/docs/benchmarks.md) for the full methodology and the workload class breakdown.
v0.3 adds 30 paired-benchmark samples across 3 real projects. See [`validation/v0.3-evidence-report.md`](https://github.com/ultronisnice/pi-precognition/blob/HEAD/validation/v0.3-evidence-report.md).
---
## What Shipped in v0.3
- Persistent Pattern Library with cross-session and cross-project storage
- Mutation Stream that re-arms futures based on file changes
- Anticipation Planner that turns evidence into concrete warming plans
- Future Compose API for registering new future classes
- CLI tools: `doctor`, `patterns`, `watch`, and improved `bench`
- First-class community surface (`build-a-future`, challenges, templates)
- 82/82 tests passing + paired benchmark receipts across real projects
- Full documentation and examples (including Rust cargo support)
The full release evidence and receipts are in the repo.
---
## Install
```bash
pi install npm:pi-precognition
```
Recommended environment (safest defaults):
```bash
PI_PRECOG=1
PI_PRECOG_TOOL_CACHE=1
PI_PRECOG_COMMAND_FUTURES=1
PI_PRECOG_INJECTION_MODE=silent-futures
```
Hard off switch:
```bash
PI_PRECOG=0
```
---
## First Wave
The Future Compose API is first-class in v0.3. Anyone can register a new future class — usually around 30 lines plus a fingerprint test — for a language or workflow that isn't covered yet, or for something specific to how *you* work.
Future classes shipped during the v0.3 window land on the permanent contributor record. No bounties, no contest. The point isn't to win — it's to be one of the people who showed up while the substrate was still soft, and to have your name on the future class that proved a workflow worked.
If you ship one with real receipts before the window closes, it becomes part of how this thing actually grew.
→ [Build a Future](https://github.com/ultronisnice/pi-precognition/blob/HEAD/docs/build-a-future.md) — anatomy of a future class, 30-line template, safety checklist
→ [Current open slots & leaderboard](https://github.com/ultronisnice/pi-precognition/blob/HEAD/challenges/leaderboard.md) — what's open, what's been shipped
---
## What's Next (v0.4 and beyond)
The bigger direction is turning observed behavior into active, gated steering.
In the next release we expect to bring in the Mirror — the persistent model that can not only predict what you'll need, but begin to act on it with proper receipts and safety gates. That work is already in progress on the internal track and will land as v0.4 once it has real cross-session evidence.
v0.3 is the substrate. v0.4 is when the model starts earning the right to steer.
---
## Safety
The v0.2 safety invariants are preserved as a strict superset:
- **Silent-futures default** — nothing is hidden in the model's context.
- **Causal-fingerprint validation at serve time** — stale futures never serve.
- **Repo-local only** — realpath containment after symlink resolution.
- **Secret-path denylist** — `.env`, credentials, SSH/AWS/Docker config.
- **Hard off switch** — `PI_PRECOG=0` makes the entire extension a no-op.
See [`docs/safety-model.md`](https://github.com/ultronisnice/pi-precognition/blob/HEAD/docs/safety-model.md) for the full invariant list. Any path that violates an invariant is a release-blocking bug.
---
## Status
- 82/82 tests passing
- Typecheck clean
- Clean history with full receipts
- v0.3.0 tag published
This is the foundation release. The real compounding power will grow as usage data and new future classes flow back into the system.
---
## License
MIT.
Contributions and new future classes are welcome.