Skip to content

Session forecasts in your terminal

The companion keeps a compact session display visible by default while you work. It shows the session identity, guard state, forecast availability or estimated remaining range, and spending or guard runway when space permits.

Claude Code

tokenpak claude

An interactive companion launch adds the TokenPak native footer through its temporary settings overlay, including when a custom status line is configured. Your saved settings stay intact. Select auto to keep an existing user or project status line instead:

tokenpak claude --status-surface=auto

Install jq for this adapter. Without it the footer says TokenPak | status unavailable; startup and tokenpak doctor --claude-code report the missing dependency. The reader does not inspect transcripts or make provider requests. The footer refreshes every two seconds, including while idle, using Claude's status line refresh timer.

Codex

tokenpak codex opens a small forecast pane below Codex by default. Inside tmux it uses the current session; outside tmux it opens a private terminal session. The pane closes when that companion exits. No extra flag is needed:

tokenpak codex

The pane requires tmux. If it is missing, the default launch explains the dependency and continues without the footer. Explicit --status-surface=tmux requires it and reports an error when unavailable. A private tmux server uses its own configuration; existing servers, panes, and bindings are preserved. Detaching keeps the session running and prints the command to reattach. This is a terminal pane, not an extension of Codex's built-in /statusline fields.

The optional auto mode never starts a multiplexer. In an ordinary terminal it prints the panel option and leaves Codex's own interface in place. Noninteractive commands such as codex exec, JSON output, and install-only runs create no panel.

Read or disable a display

tokenpak status --line --session YOUR_SESSION_ID
tokenpak status --full --session YOUR_SESSION_ID
tokenpak status --json --session YOUR_SESSION_ID
tokenpak codex --status-surface=off
tokenpak claude --status-surface=off

TOKENPAK_STATUS_SURFACE=off disables both adapters. Supported surface values are on (default), auto, native (Claude), tmux (Codex), and off. An explicit flag overrides the environment variable. Native arguments after -- are forwarded without interpretation.

Use the exact native session ID when reading from a separate terminal. A managed companion binds its own session on startup, resume, and clear; it does not borrow the newest session from another terminal. A session needs completed requests in the local proxy's ledger before its economics can be shown. Starting a display does not backfill earlier traffic or invent missing usage measurements.

Read the estimates correctly

  • est and ~ identify estimates. Remaining ranges carry their 50% interval label; the 90% ceiling appears when there is room.
  • guard limit is the estimated number of turns before a configured constraint, not the number of turns needed to finish your task.
  • learning, no data, and unavailable are real states. Subscription traffic can show subscription rather than a fabricated dollar bill.
  • stale means the cached observation expired. Expired numbers are hidden.
  • Narrow terminals show fewer complete fields, preserving guard information. The display makes no numeric savings claim and triggers no session switch.

One process per managed display refreshes the explicit session's local snapshot about every two seconds. The shell adapters read a pre-rendered cache with a ten-second expiry. Cache files are private, live under the companion's own run directory, and contain bounded session metadata rather than request bodies. The snapshot JSON preserves field sources, timestamps, routing mode, and the original session-economics contract. The optional Pro daemon is not required.