🚀 Token Rate Tracker

A real-time performance monitor for your AI interactions within pi.

The Token Rate extension provides a live dashboard showing and calculating inference metrics as the model generates text. Instead of waiting until the end of a message to see how "fast" it was, you can watch the token flow in real-time.

🎬 Demo

https://github.com/user-attachments/assets/fa5dcd89-fc8f-4aa8-a553-7423d2c00109

✨ Features

• Live Metrics: Displays current throughput (tokens/sec) and cumulative averages while the model is streaming.
• Smooth Tracking: Uses a weighted moving average to provide a stable "current speed" even during network fluctuations or inference spikes.
• Summary View: Automatically switches to a detailed summary at the end of each message, showing total tokens used and actual elapsed time.
• Native TUI Integration: Built using official @earendil-works/pi-tui components (DynamicBorder, Container, Text), ensuring perfect theme compatibility.
• Easy Toggle: Quickly show or hide the stats with a hotkey (or slash command) to keep your workspace clean when not needed.

📦 Installation & Distribution

Method 1: pi install (Recommended)

Install directly from npm:

pi install npm:@juancrg90/token-rate

Or install directly from this GitHub repository:

pi install git:github.com/JuanCrg90/pi-extensions@main#packages/token-rate

Note: Use pi install -l ... to install for the current project only. Without -l, the package is installed globally (~/.pi/agent/).

Method 2: Local Installation (Manual)

For development or simple use cases, place the extension folder in the standard discovery path:

# For a global installation (available in all sessions):
mkdir -p ~/.pi/agent/extensions/token-rate
cp -r ./path/to/packages/token-rate/* ~/.pi/agent/extensions/token-rate/

# For a project-local installation:
mkdir -p .pi/extensions/token-rate
cp -r ./path/to/packages/token-rate/* .pi/extensions/token-rate/

🛠 Tech Stack & Best Practices

This extension is built following the official Pi-TUI Standardized Patterns to ensure high performance and theme support:

• Theme-aware Rendering: Uses the Factory Pattern ((tui, theme) => ...) to ensure colors adapt instantly when the user changes themes.
• Component Composition: Uses DynamicBorder and Container to maintain a clean, consistent look with the rest of the Pi interface.
• Performance Caching: Implements standard render() caching to minimize TUI overhead during rapid token streaming.

⚙️ Configuration

The widget is enabled by default. To customize behavior, create ~/.pi/agent/token-rate.json:

{
  "widgetVisible": true
}

Key	Type	Default	Description
widgetVisible	boolean	true	Whether the widget appears during streaming

Omit the file or the widgetVisible key to use the default (true). Set to false to disable the widget entirely.

Changes take effect on the next session start or after /reload.

🎮 Usage

Slash Commands

Toggle the visibility of the performance dashboard:

• /toggle-token-rate - Show/Hide the stats widget.

Shortcuts

• Ctrl + Shift + T - Toggle the statistics dashboard instantly.

tmux note: Ctrl + Shift + letter shortcuts may not be forwarded reliably by some tmux + terminal setups. If the shortcut does not work inside tmux, verify your terminal/tmux extended key support (for example set -g xterm-keys on) or use /toggle-token-rate instead.

Visuals

When active, you will see a styled box above or below the main interaction area showing:

• Current: The current flow speed.
• Average: Overall average of the current response.
• Tokens: Total tokens in the current turn.
• Elapsed/Summary: Time elapsed and session totals after completion.

🏗 Package Structure

token-rate/
├── package.json    # Pi package manifest (pi.extensions field)
├── src/
│   └── index.ts    # Extension entry point
├── index.ts        # Root re-export for `pi -e ./token-rate`
├── README.md
└── .gitignore

📋 Prerequisites

• pi ≥ 0.1.0
• Node.js (for development only)

🤝 Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

📄 License

MIT © JuanCrg90

---

Built with ❤️ for the Pi ecosystem. Part of the pi-extensions mono-repo.