pi-turn-metrics

English | 中文说明

pi-turn-metrics is a Pi Coding Agent footer status bar extension for real-time tracking of conversation Turns, autonomous Steps, LLM response times, Tool call durations, TTFT (Time-to-First-Token), and TPS (Tokens-per-Second).

Designed with full calculation and formatting parity with Deepseek Harness, plus automatic terminal width adaptation.

---

📸 Preview

# Standard Style (Default / Terminal width ≥ 80 cols)
1 turns · 4 steps | LLM 34.1s · Tool call 0.6s | TTFT avg 3.9s · 68 tok/s

# Compact Style (Automatic on narrow screens < 80 cols)
1t·4s | LLM 34.1s · Tool 0.6s | TTFT 3.9s · 68 tok/s

---

⚡ Quick Start

# Install via npm
pi install npm:pi-turn-metrics

# Or install from git
pi install git:github.com/leon-zym/pi-turn-metrics

# Try without installing
pi -e npm:pi-turn-metrics

Inside an active Pi session, use /reload to apply updates immediately.

---

🎯 Metrics & Features

Pi's built-in status line focuses on Token accounting and Context Window Occupancy (↑ Input, ↓ Output, R Cache Read, CH Cache Hit %, Used Context / Capacity). pi-turn-metrics adds the missing execution and timing dimension:

Group	Example	Description
Execution Counts	1 turns · 4 steps	User conversation turns and inner agent autonomous steps.
Execution Timings	LLM 34.1s · Tool call 0.6s	Pure model inference time vs. local tool execution duration.
Throughput & Speed	TTFT avg 3.9s · 68 tok/s	Average Time-To-First-Token latency and decode token speed.

• Bottleneck Diagnostics: Instantly see if a long run was waiting on the model or on local build/test tools.
• Adaptive Layout: Dynamically monitors terminal width (process.stdout.columns and resize events) to toggle between full and compact TUI modes.

---

📐 Calculation Logic (Deepseek Harness Parity)

Aligned with the Deepseek Harness sessionStats specification:

• Turns & Steps: turns increments per user prompt; steps increments on each completed assistant message.
• LLM & Tool Durations: LLM sums request-to-response wall time; Tool call pairs tool_execution_start and tool_execution_end by call ID (supports concurrent tools).
• TTFT (Time-To-First-Token): Captures the first non-empty token delta chunk (text, reasoning, or tool call), averaged across recorded steps.
• TPS (Tokens Per Second): Sum of provider output tokens divided by sum of decode durations (first token to message end).

---

📄 License

MIT © 2026 zhangyiming