# pi-turn-metrics

[![npm](https://img.shields.io/npm/v/pi-turn-metrics.svg)](https://www.npmjs.com/package/pi-turn-metrics)
[![pi-package](https://img.shields.io/badge/pi--package-extension-blue.svg)](https://pi.dev)
[![license](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

[English](README.md) | [中文说明](README.zh.md)

**pi-turn-metrics** is a [Pi Coding Agent](https://pi.dev) 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

```text
# 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

```bash
# 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](https://github.com/deepseek-ai/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](https://github.com/leon-zym)