pi-tidy-tools

See what your pi agent is doing at a glance. Restyles pi's built-in tools into compact, configurable blocks so the transcript reads like a narrative, not a wall of boxes.

Restyles pi's built-in tools (read write edit bash grep find ls) with a two-line default plus optional one-line reasoning and result layouts.

Before and after

The same successful read, grep, and edit calls rendered by native pi and pi-tidy-tools:

• Line 1 — status mark, tool icon/name, and the model's goal/reasoning for the call.
• Line 2 — the concrete target (path/command/pattern) and a colored result summary.

Execution delegates to pi's built-in tools unchanged. The extension replaces their TUI rendering and, in reasoning-enabled modes, augments their schemas with a required goal phrase.

In action

Reasoning headline

In default and reasoning modes, each wrapped tool gains a required reasoning parameter that the model fills with the goal behind the call (not a restatement of the file or command, which is already shown). result mode leaves the native tool schema unchanged and does not request reasoning.

Expand for detail (ctrl+o)

Collapsed blocks show the two-line summary. Expanding a tool (ctrl+o, app.tools.expand) appends its full output:

• edit — the colored, line-numbered diff
• write — the written content with line numbers
• bash — the full (multi-line) command input, then its output
• read/grep/… — the raw result text

/diff — last-turn changes

/diff (or ctrl+shift+o) recaps successful edit/write changes from the immediately preceding turn as colored line-by-line diffs, including new files and whole-file overwrites.

ctrl+shift+o also maps to the built-in app.tree.filter.cycleBackward; in the main transcript it triggers /diff. Rebind in keybindings.json if you prefer.

Enable or disable persistently

The extension is enabled by default. Use the management command to change or inspect its startup state:

/tidy on
/tidy off
/tidy toggle
/tidy status
/tidy mode default
/tidy mode reasoning
/tidy mode result
/tidy mode status

Layout modes:

• default — reasoning headline, then target and result on line two
• reasoning — one line with the reasoning and summarized result
• result — one line with the target and summarized result; no reasoning parameter is requested

A successful change is saved to ~/.pi/agent/pi-tidy-tools.json and reloads pi's extensions immediately. While disabled, /tidy remains available, but all seven tool overrides, reasoning prompts, diff hooks, /diff, its shortcut, and custom rendering are absent.

For temporary or managed environments, PI_TIDY_TOOLS overrides the file. It accepts on/off, true/false, yes/no, or 1/0. Unset the variable before using /tidy on|off|toggle; /tidy status reports when the override is active. A missing, unreadable, or malformed config defaults to enabled.

Styling

Mirrors a clean, theme-agnostic palette + icon mapping:

| Tools | Icon | Color | |--------------------------|------|---------| | read grep find ls| 📖 | cyan | | write edit | ✏️ | yellow | | bash | ⚡ | magenta |

• Paths collapse $HOME → ~
• edit shows +adds/-dels; text write shows line count; bash shows status + elapsed time
• grep shows N matches in M files; find/ls show file or entry counts
• Every line is truncated to the live terminal width (ANSI-aware) so nothing wraps past the gutter
• Pi's native pending/success/error background colors remain, without restoring its padding or extra spacing

Raw ANSI is intentional for the foreground palette; tool backgrounds follow the active Pi theme.

Scope

Only the seven built-in tools are restyled. MCP / third-party tools keep their default rendering — pi does not expose a way to override a foreign tool's renderer without owning its execution.

Install

Install the published npm package with pi:

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

Restart pi or run /reload in an existing session. To update later:

pi update --extension npm:@mobrienv/pi-tidy-tools

To remove it:

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

Local development

From the monorepo root, quick-test this workspace:

pi -e ./packages/pi-tidy-tools/index.ts

Or install the workspace through ~/.pi/agent/settings.json:

{
  "packages": ["/absolute/path/to/repo/packages/pi-tidy-tools"]
}

Develop

Run all workspaces from the repository root:

npm install
npm test
npm run check

Or target this package with --workspace @mobrienv/pi-tidy-tools.

Regenerating screenshots

docs/comparison.png, docs/demo.png, docs/diff.png, and docs/modes.png are generated from real renderer output (no hand-typed ANSI): the scripts run the built-in tools, render them through the actual extension (or native pi cards for the comparison), and screenshot the result via headless Chrome.

bash packages/pi-tidy-tools/docs/comparison.sh # native vs tidy comparison
bash packages/pi-tidy-tools/docs/demo.sh       # full tidy transcript
bash packages/pi-tidy-tools/docs/diff.sh       # /diff last-turn recap
bash packages/pi-tidy-tools/docs/modes.sh      # layout-mode comparison

All four generators require Google Chrome/Chromium and ImageMagick.