pi-loop is the completion-driven coding agent built in the pi-loop repository. It extends the public Pi SDK with a durable execution loop, evidence-based completion, and locally accumulated experience.
Most coding agents are optimized to produce a useful next response. pi-loop is optimized to finish the requested work.
"Done" is not a tone or a model prediction. pi-loop accepts completion only after the agent submits a structured claim backed by observed verification. A failed check becomes the next input to the same session instead of the end of the run.
pi-loop records the commands that actually ran, deterministic verifier results, review findings, stop reasons, and runtime telemetry. Claims must agree with that evidence. Live repository state always outranks plans, memories, and learned guidance.
Unfinished work stays resumable. pi-loop keeps the objective, session, blocker, verification history, and compact loop state so a run can continue without pretending that partial progress was success.
pi-loop learns useful project lessons from completed runs, but historical lessons remain advisory. Its curated skill can evolve only when a candidate performs strictly better on the eval suite and a human explicitly approves the proposal. Model weights never change.
Every top-level request requires confirmation before model or tool execution. External mutations may require additional approval, and curated-skill promotions are never automatic.
| Capability | Benefit |
|---|---|
| Structured completion gate | Prevents polished but unverified "done" responses |
| Ordered deterministic verifiers | Turns failing checks into another repair cycle |
| Persistent runs and native Pi sessions | Makes interruption and external blockers resumable |
| Project-scoped experience | Reuses successful local practices without overriding live evidence |
| Eval-gated curated skill | Accumulates proven guidance instead of unvalidated prompt drift |
| Optional read-only planning and review | Separates implementation from assumption probing and independent inspection |
| Shared policy for TUI and one-shot runs | Keeps command and write decisions consistent across interfaces |
| Local telemetry and result cards | Makes cost, tokens, tools, cycles, and stop reasons inspectable |
pi-loop keeps Pi's model providers, authentication, sessions, compaction, tools, themes, and interactive workflow. The loop adds discipline without replacing the platform underneath it.
confirm request
-> retrieve relevant local experience
-> optionally plan in a read-only session
-> execute in a persistent Pi session
-> submit a structured completion claim
-> run deterministic verifiers
-> optionally review independently
-> persist the result and reinforce useful lessons
If completion evidence is missing or a verifier fails, pi-loop continues in the same session. It stops without success only for a concrete external blocker, such as a missing credential, denied permission, unavailable service, or a material decision that cannot be inferred safely.
- Fewer premature completions: successful work needs observable proof.
- Less supervision: verification failures feed directly back into the loop.
- Better continuity: interrupted work and blockers remain explicit and resumable.
- Compounding local value: useful commands and lessons improve later runs.
- Controlled self-improvement: curated guidance must pass evaluation and human review.
- Native Pi ergonomics: existing authentication, models, TUI commands, session management, and themes continue to work.
pi-loop requires Node.js 22.19 or newer and Bun. It reuses Pi credentials and model
settings from ~/.pi/agent.
make install
# Open Pi's interactive TUI with pi-loop's completion loop.
pi-loop
# Run one request and require a deterministic final check.
pi-loop "Refactor the parser and preserve its behavior" --verify "make check"
# Resume an interrupted or externally blocked run.
pi-loop runs
pi-loop resume <run-id>
# Inspect and improve pi-loop's curated guidance.
pi-loop skillsUseful optional flags include --plan, --review, repeated --verify,
--cwd <dir>, and --timeout-minutes <n>. Run pi-loop --help for the complete
command reference.
pi-loop stores experience, run records, curated skills, and headless sessions
under $PI_LOOP_HOME or ~/.pi-loop. It does not place memory files in the target
repository.
The command and write policy is behavioral protection, not a complete security
boundary. On macOS, pi-loop also uses a Seatbelt profile and denies network access
unless --allow-network is provided. Use a container or another OS-level
sandbox for untrusted repositories on other platforms.
bun install --ignore-scripts
make checkThe full behavior contract and architecture are documented in docs/DESIGN.md. The optional out-of-tree SkillOpt adapter is documented in integrations/skillopt/README.md.
MIT