pi-precognition

---

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 · Reproduce · Build a future

---

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 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.

---

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

pi install npm:pi-precognition

Recommended environment (safest defaults):

PI_PRECOG=1
PI_PRECOG_TOOL_CACHE=1
PI_PRECOG_COMMAND_FUTURES=1
PI_PRECOG_INJECTION_MODE=silent-futures

Hard off switch:

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 — anatomy of a future class, 30-line template, safety checklist → Current open slots & leaderboard — 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 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.