pi-work-timer

A small Pi extension that shows how long the agent has been working, then adds a durable Worked for: entry when the run finishes.

What it does

• Shows elapsed time while Pi is working.
• Defaults to a colorful rainbow spinner with the timer beside it, for example: ⠋ 00:12.
• Adds a final TUI-only transcript entry with a local completion timestamp, for example: ✓ Worked for: 12s · 2026-08-06 14:32.
• Keeps a footer/status timer while the agent is active.
• Does not add timer entries to the LLM context.

Default behavior

This package currently defaults to:

• Work timer: on
• Spinner timer: on
• Spinner color mode: rainbow

Because Pi has one global working-indicator slot, enabling the spinner timer means this extension owns the working indicator while the agent runs. If you use another spinner/working-indicator extension and want to preserve it, run:

/work-timer indicator off

You will still get the footer/status timer and final Worked for: entries.

Commands

/work-timer
/work-timer status
/work-timer on
/work-timer off
/work-timer indicator on
/work-timer indicator off
/work-timer color rainbow
/work-timer color theme

Command details

Command	Effect
/work-timer or /work-timer status	Shows current timer, spinner, and color settings.
/work-timer on	Enables the work timer.
/work-timer off	Disables the work timer and clears timer UI.
/work-timer indicator on	Shows elapsed time next to the working spinner.
/work-timer indicator off	Leaves Pi/other extensions' spinner alone; timer stays in footer/status only.
/work-timer color rainbow	Uses pastel ANSI colors for the spinner frames.
/work-timer color theme	Uses Pi theme colors for a more theme-safe spinner.

Performance and context impact

LLM context impact: none

The final Worked for: row is stored with Pi's pi.appendEntry(...) API. Custom entries created this way do not participate in LLM context, so they do not add tokens to prompts and the model does not see them.

This extension does not call pi.sendMessage(...), does not inject custom messages, and does not modify the provider context.

Runtime performance impact: negligible

While the agent is running, the extension uses one setInterval that ticks once per second. Each tick:

• calculates elapsed time,
• updates a namespaced footer status entry,
• and, if spinner timer mode is enabled, refreshes a small working-indicator frame list.

The spinner animation itself is handled by Pi's existing working-indicator system. The extension clears its timer on completion and on session shutdown/reload.

Session file impact: small

Each completed run appends one small custom JSON entry to the session file. These entries are not sent to the model. If you run hundreds of tiny prompts, the session file will grow slightly. A future option could add a minimum-duration threshold for saved entries.

Theme and color behavior

• Final transcript entries use Pi theme tokens like success, accent, dim, customMessageLabel, and customMessageBg.
• Footer/status timer uses Pi theme tokens.
• Spinner color modes:
  • rainbow: pastel raw ANSI colors for a colorful spinner.
  • theme: Pi theme accent color for the spinner and dim for elapsed time.

For maximum theme compatibility, use:

/work-timer color theme

For a more colorful personal setup, use:

/work-timer color rainbow

Installation

Install from npm

After publishing:

pi install npm:pi-work-timer

Install from GitHub

After pushing to GitHub:

pi install git:github.com/YOUR_USERNAME/pi-work-timer

Pinned install example:

pi install git:github.com/YOUR_USERNAME/pi-work-timer@v0.1.0

Test locally without installing

From this package directory:

pi -e .

Or from anywhere:

pi -e /absolute/path/to/pi-work-timer

Install locally

pi install /absolute/path/to/pi-work-timer

Then reload Pi:

/reload

Publishing checklist

Before publishing:

1. Confirm the extension loads:

   pi -e .

2. In Pi, run:

   /work-timer status

3. Send a prompt that takes a few seconds and verify:

   • the timer appears beside the spinner,
   • the footer/status timer updates,
   • a Worked for: entry appears after completion.

4. Test compatibility mode:

   /work-timer indicator off

   Confirm another spinner extension can keep controlling the spinner.

5. Test theme-safe mode:

   /work-timer color theme

6. Test reload cleanup:

   /reload

7. Dry-run npm packaging:

   npm run pack:dry

8. Publish:

   npm publish

Pi package metadata

This package uses the Pi package manifest in package.json:

{
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"]
  }
}

Pi's package gallery can discover packages tagged with pi-package. You can add a preview later with:

"pi": {
  "extensions": ["./extensions"],
  "image": "https://example.com/screenshot.png"
}

or:

"pi": {
  "extensions": ["./extensions"],
  "video": "https://example.com/demo.mp4"
}

Notes and limitations

• Pi exposes one global working-indicator slot. If spinner timer mode is enabled, this extension controls that slot while the agent is running.
• Settings are runtime toggles for the current extension instance. If you reload or start a new Pi session, defaults are restored.
• The extension currently focuses on interactive TUI mode.

License

MIT