Use Cases & Examples

Last updated: 2026-07-13

Pi is not another black-box chatbot — it is a "self-extending" AI coding-agent toolkit. Its sweet spot is chaining the tedious loop of "read code → edit code → run a command → read the result" into a reviewable, reversible workflow. Below are three real scenarios that show how it does the work for you.

Scenario 1 — Let the coding agent refactor a function

You inherited an old callback-style function and want it upgraded to async/await, but the nesting is deep and manual edits are error-prone. Hand it to pi-coding-agent: it reads the context, proposes a diff, and only writes once you approve.

1. Enter the repo and launch the agent: from the repo root run ./pi-test.sh to start the interactive coding agent.
2. Describe the refactor: state the target in natural language, e.g. "convert getUser from callbacks to async/await, keeping the public signature unchanged".
3. Review the diff: the agent lists every file and change it plans to make, so you can inspect each one.
4. Ask it to add tests and run: request unit tests for the new implementation and execute the suite to verify behavior.
5. Accept or roll back: once tests pass, accept; if not, roll back to any node in the JSONL session tree and try again.

# launch the interactive coding agent
./pi-test.sh

# in the session, just say:
# "convert src/db.js getUser from callbacks to async/await,
#  and add a test covering the error branch"

Scenario 2 — Auto-run tests and fix failures

After merging several PRs the tests are red, and you don't want to click through logs one by one. Give "run the tests" to Pi: it reads the failure output, locates the case, tries a fix, and re-runs until it's green or clearly says "this one needs you".

# hand the test-fix loop to the agent
./pi-test.sh
# "run npm test and fix the failing cases; re-run after each fix"

Internally it runs the same core loop: prepare context (test output) → call model → run tool (edit file / run command) → write back → continue or stop. Every round is recorded on the session tree, so you can always see why it changed what it changed.

Scenario 3 — Explore an unfamiliar repository

You just cloned a monorepo you don't know, and you're not sure where the entry point is or which package provides an API. Instead of grepping blindly, ask the agent: trained on the repo structure, it can walk the import graph and explain the call chain.

./pi-test.sh
# "in this repo, who is responsible for forwarding requests to the LLM?
#  give me the full chain from the CLI entry to the pi-ai call"

It answers in terms of the core packages — pi-ai for the unified model, pi-agent-core for the runtime, pi-coding-agent for the CLI, pi-tui for the terminal UI — rather than guessing. To go deeper on any package, jump to the relevant reference doc.

How the pieces combine

• Safe install: every dependency is installed with npm install --ignore-scripts to avoid untrusted lifecycle scripts — see Running & debugging.
• Offline development: use MockModel to exercise tool and loop logic without spending tokens — see Quick Start.
• Self-host: the whole toolkit is MIT-licensed and can be deployed privately, with no vendor cloud required.

Not sure Pi is the right fit? Read the Pi vs Aider / Claude Code / OpenHands breakdown before committing.

When Pi shines — and when it doesn't

Pi is at its best when the work is iterative and reviewable: refactors, test-driven fixes, codebase archaeology, and any task where you want to watch every change before it lands. It is less suited to one-shot generation of an entire project from a vague prompt — there the loop still helps, but you should keep the diff small and the tests tight. The common thread is control: you stay in the loop, the agent stays in its sandbox, and the session tree keeps everything auditable afterward.