--- slug: "mobrienv-pi-tidy-tools" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/mikeyobrien/pi-tidy-tools@main/README.md" repo: "https://github.com/mikeyobrien/pi-tidy-tools" source_file: "README.md" branch: "main" --- # pi-tidy Focused, independently installable packages that make [Pi](https://github.com/earendil-works/pi-mono) 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):** ```bash 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: ```bash # 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 `@` if you want a frozen experimental build. Project-local installs use the same sources with `-l`. ## Packages ### [`@mobrienv/pi-tidy-tools`](https://github.com/mikeyobrien/pi-tidy-tools/tree/HEAD/packages/pi-tidy-tools) [![npm version](https://img.shields.io/npm/v/%40mobrienv%2Fpi-tidy-tools)](https://www.npmjs.com/package/@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. [![Native Pi tool cards compared with compact pi-tidy-tools output](https://github.com/mikeyobrien/pi-tidy-tools/raw/HEAD/packages/pi-tidy-tools/docs/comparison.png)](packages/pi-tidy-tools) - 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 ```bash pi install npm:@mobrienv/pi-tidy-tools ``` [Read the full pi-tidy-tools documentation →](https://github.com/mikeyobrien/pi-tidy-tools/tree/HEAD/packages/pi-tidy-tools)
More pi-tidy-tools examples #### In action ![pi-tidy-tools transcript showing successful and failed tool calls](https://github.com/mikeyobrien/pi-tidy-tools/raw/HEAD/packages/pi-tidy-tools/docs/demo.png) #### Last-turn diff ![pi-tidy-tools diff recap of the last turn's edits and writes](https://github.com/mikeyobrien/pi-tidy-tools/raw/HEAD/packages/pi-tidy-tools/docs/diff.png) #### Layout modes ![Default, reasoning, and result layouts in pi-tidy-tools](https://github.com/mikeyobrien/pi-tidy-tools/raw/HEAD/packages/pi-tidy-tools/docs/modes.png)
--- ### [`@mobrienv/pi-tidy-subagents`](https://github.com/mikeyobrien/pi-tidy-tools/tree/HEAD/packages/pi-tidy-subagents) [![npm version](https://img.shields.io/npm/v/%40mobrienv%2Fpi-tidy-subagents)](https://www.npmjs.com/package/@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. Mixed foreground and background pi-tidy-subagents cards, active widget, durable stamps, management overlay, expanded detail, and narrow viewport - 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 ```bash pi install npm:@mobrienv/pi-tidy-subagents ``` [Read the full pi-tidy-subagents documentation →](https://github.com/mikeyobrien/pi-tidy-tools/tree/HEAD/packages/pi-tidy-subagents) --- ### [`@mobrienv/pi-tidy-memory`](https://github.com/mikeyobrien/pi-tidy-tools/tree/HEAD/packages/pi-tidy-memory) [![npm version](https://img.shields.io/npm/v/%40mobrienv%2Fpi-tidy-memory)](https://www.npmjs.com/package/@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 ```bash pi install npm:@mobrienv/pi-tidy-memory ``` [Read the full pi-tidy-memory documentation →](https://github.com/mikeyobrien/pi-tidy-tools/tree/HEAD/packages/pi-tidy-memory) --- ### [`@mobrienv/pi-tidy-footer`](https://github.com/mikeyobrien/pi-tidy-tools/tree/HEAD/packages/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 ```bash 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 →](https://github.com/mikeyobrien/pi-tidy-tools/tree/HEAD/packages/pi-tidy-footer) ## 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: ```bash npm install npm test npm run check ``` Coverage bars (c8) and mutation testing (Stryker) are available monorepo-wide or per package: ```bash 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](https://github.com/mikeyobrien/pi-tidy-tools/blob/HEAD/docs/quality-gates.md) 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: ```bash 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-` and use the npm name `@mobrienv/pi-tidy-`. Releases use package-qualified tags such as `pi-tidy-tools-v0.2.0` so every package can version and publish independently.