Architecture

Primitives beneath the pi command.

Every feature rides on a small set of named primitives. All open-source, all inspectable under packages/pi-cli/src/lib/.

See capabilities
Execution pipeline

How one pi sentence becomes a shipped change

Everything starts with argv. From there: translate, plan, orchestrate, validate, govern.

  argv  ─→  omni-router ─→  polyglot-router ─→  nlp-router (API)
              │                                     │ (offline fallback)
              │                                     ▼
              │                            intent-classifier
              │                                     │
              ▼                                     ▼
     session-store           ──────  execution-planner
     session-learning                          │
              │                                ▼
              │                     cli-orchestrator
              │                                │
              │       ┌─────── validate ─── sharingan · ts-morph · polyglot ── rasengan-cache
              ├──────▶│                          │                                  │
              │       ├─────── fix ─────── patch-generator ─── rules.*              │
              │       ├─────── routine ─── embedded-templates · workflow-poller     │
              │       ├─────── prompt ──── dependency-chain · prompt-cache          │
              │       ├─────── resonate ── mastra workflow · plan.md                │
              │       └─────── watch ──── chokidar · daemon · observability         │
              │                                                                     │
              ▼                                                                     ▼
     vcs adapters (git / p4 / host-labeled)           agentic-ide-injector → .cursorrules / CLAUDE.md
Named primitives

The nine modules that do the work

Each one is swappable; none are hidden.

Omni-router

Entry for any pi "…" not matching a subcommand. Translates, resumes sessions, routes via NLP or offline heuristics, chains subprocesses.

// packages/pi-cli/src/lib/omni-router.ts

Sharingan (AST)

ts-morph Project helper. In-memory blast-radius analysis from excerpts and boundary checks used by validate + doctor.

// packages/pi-cli/src/lib/ast/sharingan.ts

Rasengan (cache)

L1 memory + L2 disk under the .pi cache dir. Fingerprint helpers dedupe cloud validate calls and save API budget.

// packages/pi-cli/src/lib/cache/rasengan-cache.ts

Execution planner

Normalizes NLP or heuristic plans into ordered steps. Enforces invariants like 'validate before fix'.

// packages/pi-cli/src/lib/execution-planner.ts

Dependency chain

Implicit preflight: ensurePiDir, shouldSyncBeforeValidate, ensureSystemStyleJson. Agents stop forgetting steps.

// packages/pi-cli/src/lib/dependency-chain.ts

Routine system

Library + index + context detector. v2 markdown specs, per-phase DAG, progress JSON, drift checks against the spec.

// packages/pi-cli/src/lib/routine-library.ts, routine-index.ts, routine-context-detector.ts

VCS adapters

Git, host-labeled Git (GitLab / Bitbucket / Gerrit), Perforce (p4), unknown — all via a common getPendingChanges interface.

// packages/pi-cli/src/lib/vcs/

Mastra workflow polling

WorkflowKey union for validate / routine / resonate / learn. Polls /api/cli/workflow/poll until terminal, resumes on reconnect.

// packages/pi-cli/src/lib/workflow-client.ts, workflow-poller.ts

Privacy redactor

Regex redaction for Stripe / Pi keys and generic secrets before anything leaves the machine. Applied by pi learn, pi prompt, validate.

// packages/pi-cli/src/lib/privacy/redactor.ts

Design principles

  • 01Local-first. API is useful, not required — cli-capabilities banner names what degrades.
  • 02Cited. Every primitive has a single file of truth; no invisible magic.
  • 03Resumable. Task trees + workflow poller + session store survive dropped connections.
  • 04Safe by default. pi fix needs a confidence threshold; nothing writes outside .pi/ without you asking.
  • 05Polyglot. TS is first-class, but polyglot-router + VCS adapters do not assume a monoculture.