pi-tidy

Focused, independently installable packages that make Pi easier to follow.

Long agent turns are hard to read in Pi's native transcript: every tool call renders as a boxed card, the model's goal behind each call is invisible, and delegated work has no compact live view. pi-tidy replaces that with dense, reason-first output while preserving native execution behavior.

Each package solves one transcript or workflow problem. Install only the ones you want — there is no umbrella runtime package.

Stable (npm):

pi install npm:@mobrienv/pi-tidy-tools      # compact, reason-first tool cards
pi install npm:@mobrienv/pi-tidy-subagents  # foreground and background subagent fan-out
pi install npm:@mobrienv/pi-tidy-memory     # durable, backend-neutral memory

Experimental (source only for now): @mobrienv/pi-tidy-footer ships on main but is not published to npm yet. Its API, config, and layout may still change before a first release. It lives as a monorepo package directory, so install the repo from git and then install that package path:

# clone via Pi's git installer (also registers the monorepo root)
pi install git:github.com/mikeyobrien/pi-tidy-tools@main

# the experimental package is a workspace directory under that clone
pi install ~/.pi/agent/git/github.com/mikeyobrien/pi-tidy-tools/packages/pi-tidy-footer

Equivalent sources: https://github.com/mikeyobrien/pi-tidy-tools@main or git:git@github.com:mikeyobrien/pi-tidy-tools@main. Pin a commit with @<sha> if you want a frozen experimental build. Project-local installs use the same sources with -l.

Packages

@mobrienv/pi-tidy-tools

See what your Pi agent is doing at a glance. Replaces Pi's built-in tool cards with compact, reason-first output while preserving native execution behavior.

• Restyles read, write, edit, bash, grep, find, and ls
• Shows the goal, concrete target, and useful result in one or two lines
• Keeps live status, errors, expansion, terminal-width truncation, and native tool behavior
• Adds configurable layouts and a /diff recap of the previous turn's changes

pi install npm:@mobrienv/pi-tidy-tools

Read the full pi-tidy-tools documentation →

More pi-tidy-tools examples

In action

Last-turn diff

Layout modes

---

@mobrienv/pi-tidy-subagents

Fan work out to child Pi agents without losing the thread. Adds resource-aware subagent delegation — foreground or background — with compact live state and ordered results.

• Runs independent child prompts concurrently through a session-wide queue
• Shows one scan-friendly activity per child, with full recent detail on expansion
• Backgrounds long-running children and delivers their results when the parent is idle
• Preserves healthy sibling results when an individual child fails
• Records complete responses, usage, and normalized events in versioned run artifacts

pi install npm:@mobrienv/pi-tidy-subagents

Read the full pi-tidy-subagents documentation →

---

@mobrienv/pi-tidy-memory

Give Pi durable memory without tying the agent to one storage engine. The package exposes compact recall, retain, and reflect tools through a backend-neutral contract. Hindsight is the first adapter.

• Connects to authenticated self-hosted Hindsight servers with native fetch
• Keeps credentials in environment variables or a protected env file
• Marks recalled content as untrusted historical data
• Offers optional automatic recall and retain hooks, both disabled by default
• Uses left-edge, two-line why/result cards with a live-only state mark and native settled backgrounds
• Leaves room for additional backends without changing the Pi-facing tools

pi install npm:@mobrienv/pi-tidy-memory

Read the full pi-tidy-memory documentation →

---

@mobrienv/pi-tidy-footer · experimental

Keep the important state visible on a phone-sized terminal. The footer anchors model and context to the right while fitting branch, Codex quotas, and active extension statuses into the flexible left side.

Experimental: on main, not on npm yet. Install from a local checkout. Layout tiers and CodexBar integration may still change before 0.1.0 is published.

• Designed around 52–56-column Termux sessions
• Uses two justified, ANSI- and Unicode-safe lines
• Reads five-hour and seven-day quota usage from the codexbar CLI
• Polls outside rendering and keeps the last good quota snapshot

pi install git:github.com/mikeyobrien/pi-tidy-tools@main
pi install ~/.pi/agent/git/github.com/mikeyobrien/pi-tidy-tools/packages/pi-tidy-footer

Read the full pi-tidy-footer documentation →

About the collection

Packages follow the @mobrienv/pi-tidy-* naming convention. Each package owns its runtime, documentation, tests, version, changelog, and npm release when published.

@mobrienv/pi-tidy-tools, @mobrienv/pi-tidy-subagents, and @mobrienv/pi-tidy-memory are published independently on npm. @mobrienv/pi-tidy-footer remains experimental and is available from this repository until its first release.

The private root manifest exists for workspace development and keeps existing local-checkout installs pointed at pi-tidy-tools; published packages remain independent.

Develop

Install once at the repository root and validate every workspace:

npm install
npm test
npm run check

Coverage bars (c8) and mutation testing (Stryker) are available monorepo-wide or per package:

npm run test:coverage
npm run test:mutation

HTML reports land under each package's coverage/ and reports/mutation/ directories. The canonical quality-gate policy sets per-file coverage floors of 90% statements/lines/functions and 80% branches, plus an 80% package mutation break score. Package .c8rc.json and stryker.config.mjs files enforce those values.

Target one package during development:

npm test --workspace @mobrienv/pi-tidy-tools
npm run check --workspace @mobrienv/pi-tidy-tools
npm run test:coverage --workspace @mobrienv/pi-tidy-tools
npm pack --workspace @mobrienv/pi-tidy-tools --dry-run

npm test --workspace @mobrienv/pi-tidy-subagents
npm run check --workspace @mobrienv/pi-tidy-subagents
npm run test:coverage --workspace @mobrienv/pi-tidy-subagents
npm pack --workspace @mobrienv/pi-tidy-subagents --dry-run

npm test --workspace @mobrienv/pi-tidy-memory
npm run check --workspace @mobrienv/pi-tidy-memory
npm run test:coverage --workspace @mobrienv/pi-tidy-memory
npm pack --workspace @mobrienv/pi-tidy-memory --dry-run

npm test --workspace @mobrienv/pi-tidy-footer
npm run check --workspace @mobrienv/pi-tidy-footer
npm run test:coverage --workspace @mobrienv/pi-tidy-footer
npm pack --workspace @mobrienv/pi-tidy-footer --dry-run

Publishable packages live at packages/pi-tidy-<name> and use the npm name @mobrienv/pi-tidy-<name>. Releases use package-qualified tags such as pi-tidy-tools-v0.2.0 so every package can version and publish independently.