pi-idle-time

Pi extension that makes the AI aware of wall-clock time, idle duration, and previous turn execution time. Includes an opt-in idle heartbeat that sends a keepalive message to refresh the Anthropic prompt cache.

Features

• Per-prompt timing context — every user message gets a hidden [timing] block with the current time, idle duration since the last response, and the previous turn's execution duration.
• Statusline — shows the elapsed time since the last response in the pi statusline (turn duration while the agent is active, idle timer when stopped). Displays --- when the model changes mid-session.
• Idle heartbeat — opt-in tool that sends a keepalive user message after a configurable idle period. Triggers a real LLM turn, which refreshes the Anthropic prompt cache (default 5 min, extended 1 hour).
• Compact TUI rendering — the heartbeat tool result and the keepalive message both render as one-liners in the transcript (♥ cache keepalive · 14:32:15 · 4.5m). Press Ctrl+E to expand.
• Steer-aware — steering an active agent does not reset idle state.
• Persistent toggle — the heartbeat enabled state survives /reload via a global state file.
• Idle goal reminders — /idle-goal <description> sets a goal the model is reminded of after the heartbeat interval. Goal reminders take precedence over the keepalive while a goal is active.

Installation

pi install /path/to/pi-idle-time
# or from npm (when published):
# pi install npm:pi-idle-time

What the model sees

On the first prompt, the extension injects a hidden timing block:

[timing]
local_time=2026-04-17T16:04:19+10:00
[/timing]

On subsequent prompts, the block includes idle and execution time:

[timing]
2026-04-17T16:05:19+10:00
idle_for=57.0s
last_turn_dur=88.2s
[/timing]

This is a display: false custom message — it is sent to the LLM as a user-role message but does not appear in the TUI transcript.

When the user has been idle for more than idleMessageThresholdSeconds (default 10s), a visible system message appears in the TUI:

[after 5m 2s]

Commands

Command	Description
/idle-time-reset	Reset state for the current session
/idle-time-reset --all --yes	Wipe all sessions and logs
/idle-time-status	Show plugin status (data dir, state, config)
/idle-time-config	Show current configuration
/idle-time-heartbeat on	Enable the idle heartbeat (persists across /reload)
/idle-time-heartbeat off	Disable the idle heartbeat
/idle-time-heartbeat / toggle	Flip the current state
/idle-time-heartbeat status	Show whether the heartbeat is on or off
/idle-time-heartbeat on 10	Enable with a 10-minute override
/idle-goal <description>	Set an idle goal reminder
/idle-goal / /idle-goal --status	Show the active goal
/idle-goal --complete	Mark the active goal complete

When toggled, the command:

• Updates in-memory heartbeatEnabled
• Persists to global state (survives /reload)
• Shows a UI-only notification via ctx.ui.notify (NOT sent to LLM)

The notification is a plain-text toast:

on: ♥ idle heartbeat on · 4.5m off: ♥ idle heartbeat off

The notification is plain text rather than the custom compact one-liner the keepalive uses, because the runtime's display: true path also adds the message to LLM context. There is no built-in way to show a custom message in chat without it being sent to the model. Toggling is a pure UI state change, so we use ctx.ui.notify to keep it out of the LLM's context.

Tool: idle_time_heartbeat_control

LLM-callable tool that controls the idle heartbeat and idle goal for the current session.

idle_time_heartbeat_control(enabled: true, minutes: 4.5)
idle_time_heartbeat_control(enabled: false)
idle_time_heartbeat_control(goal: "draft release notes for v0.4.1")
idle_time_heartbeat_control(completeGoal: true)

• enabled (boolean, optional) — whether the heartbeat should be active. Omit when only changing the goal.
• minutes (number, optional) — override the interval. Must be positive. Falls back to config.idleHeartbeatMinutes, then 4.5. Remembered per session per mode (heartbeat vs. goal).
• goal (string, optional) — set the idle goal description. Pass an empty string to clear without completing.
• completeGoal (boolean, optional) — mark the active goal complete and resume the heartbeat if enabled. Ignored when goal is also set.

The enabled state persists across /reload via ~/.pi/idle-time/global.json. The active goal persists per session in ~/.pi/idle-time/sessions/<id>.json. Users can also toggle directly with the /idle-time-heartbeat and /idle-goal slash commands (see Commands above).

Idle goal reminders

/idle-goal <description> sets a per-session goal. After the configured interval of inactivity the extension sends the LLM:

[goal reminder] HH:MM:SS
<description>

<system-reminder>Use idle_time_heartbeat_control with completeGoal=true to mark the goal complete.</system-reminder>

The user sees a compact TUI render (🎯 idle goal · <preview> · <time> · <interval>). Goal reminders take precedence over the keepalive heartbeat while a goal is active, and fire regardless of the heartbeat's enabled flag.

Statusline

The extension publishes a statusline via ctx.ui.setStatus("idle-time", text):

• Agent active: live turn duration counting up (12s, 2m15s, 1h12m, 1d4h)
• Just stopped, idle < 1s: turn duration with idle indicator (40s|💤)
• Idle ≥ 1s: turn duration with idle timer (40s|💤2m15s)
• Model changed since last stop: ---
• Format options: drops seconds after 15 min (configurable via dropSecondsAfterSeconds); format days+hours at 1 day (configurable via formatHoursAsDays)

Idle heartbeat (cache keepalive)

The heartbeat is opt-in and disabled by default. When enabled, it sends a short keepalive user message after a configurable idle period (default 4.5 minutes). This triggers a real LLM turn, which keeps the Anthropic prompt cache warm.

What the model sees

[cache keepalive] 14:32:15 — disable via idle_time_heartbeat_control tool.

The [cache keepalive] prefix tags the message; the trailing hint points at the tool to disable. The message is deliberately informational — the model is not instructed to reply or take action.

Compact TUI rendering

The keepalive is delivered via pi.sendMessage with customType: "idle-time-heartbeat" and a custom message renderer (see src/heartbeat-message-renderer.ts, modeled on the pi compact TUI recipe). The keepalive collapses to a single line in the transcript:

♥ cache keepalive · 14:32:15 · 4.5m

Press Ctrl+E to expand and see the full body.

Configuration

{time} is replaced with the current local HH:MM:SS. The message template is configurable per session.

Configuration

Create ~/.pi/idle-time/config.json to override defaults:

{
  "idleMessageThresholdSeconds": 10,
  "idleMessageDropSecondsAfterSeconds": 3600,
  "dropSecondsAfterSeconds": 900,
  "formatHoursAsDays": true,
  "idleHeartbeatMinutes": null,
  "idleHeartbeatMessage": "[cache keepalive] {time} — disable via idle_time_heartbeat_control tool."
}

Key	Default	Description
idleMessageThresholdSeconds	10	Min idle gap (s) before the visible [after Xs] system message appears in the TUI
idleMessageDropSecondsAfterSeconds	3600	Drop trailing seconds in the system message after this many seconds (1 hour)
dropSecondsAfterSeconds	900	Statusline drops seconds after this many seconds (15 min)
formatHoursAsDays	true	Format [after 1d 4h] instead of [after 28h 0m]
idleHeartbeatMinutes	null	Default heartbeat interval in minutes; null disables it
idleHeartbeatMessage	[cache keepalive] {time} — disable via idle_time_heartbeat_control tool.	Keepalive message template; {time} is replaced with current local HH:MM:SS

Data directory

State is stored in ~/.pi/idle-time/:

~/.pi/idle-time/
  config.json                  # optional user overrides
  global.json                  # global state (survives /reload)
  sessions/
    <session-id>.json          # per-session timing state
    <session-id>.lastresponse  # flat timestamp for fast reads
  logs/
    <session-id>.log           # per-session NDJSON error log

global.json schema

{
  "heartbeatEnabled": false
}

heartbeatEnabled is written by the idle_time_heartbeat_control tool and read on every session_start. This is why the heartbeat toggle survives /reload — it is not tied to any session.

sessions/<id>.json schema

{
  "sessionId": "019ecfd3-30e5-79d5-889a-bb22a34f01d4",
  "lastUserPromptAt": "2026-06-17T08:09:00.000+10:00",
  "lastStopAt": "2026-06-17T08:09:43.000+10:00",
  "lastAssistantMessageAt": "2026-06-17T08:09:43.000+10:00",
  "lastTurnExecMs": 42137,
  "modelAtLastStop": "claude-opus-4-5",
  "modelAtLastStopAt": "2026-06-17T08:09:43.000+10:00"
}

Behavior notes

• Steering an active agent is not a new turn. When the user types while the agent is processing, the input handler does NOT reset idle state or inject a new timing block. Steer events are ignored for idle-tracking purposes.
• Statusline idle threshold is 1 second (not 10). The statusline indicator 💤 appears after just 1s of idle; the duration counter starts at the same point.
• Heartbeat only fires when the agent is idle. The timer is stopped on agent_start and input. When the timer fires, the message is sent with deliverAs: "followUp" so it queues properly if the agent is busy.
• Timing block uses display: false. It is sent to the LLM as a user-role message but does not appear in the TUI transcript. The agent_end event also fires a display: false idle-time message with the same content if needed.

Development

pnpm install
pnpm test    # 175 tests
pnpm check   # typecheck

Run tests with a timeout to be safe:

timeout 30 node --import tsx --test tests/*.test.ts

Module layout

src/
  index.ts                       — Pi extension entry point (lifecycle hooks, statusline, commands, heartbeat)
  heartbeat.ts                   — Idle heartbeat timer for cache keepalive
  heartbeat-tool-renderer.ts     — Compact renderer for the heartbeat control tool
  heartbeat-message-renderer.ts  — Compact renderer for [cache keepalive] deliverable
  goal.ts                        — Idle goal reminder message formatting
  goal-message-renderer.ts       — Compact renderer for [goal reminder] deliverable
  global-state.ts                — Global state file (heartbeatEnabled, survives /reload)
  time.ts                        — ISO timestamp utilities
  duration.ts                    — Elapsed time formatting for statusline
  format.ts                      — Timing block and idle system message formatting
  sanitize.ts                    — Session ID sanitization
  config.ts                      — Config loading with validation and defaults
  log.ts                         — Per-session NDJSON error logger
  last-response.ts               — Flat .lastresponse file for fast statusline reads
  state.ts                       — Per-session state persistence with atomic writes
  statusline.ts                  — Statusline text formatting