@willh/copilotstatusline 0.2.2 → 0.2.4

package/docs/DEVELOPMENT.md

@@ -23,6 +23,8 @@ bun run example
 
 The external Copilot payload is parsed into `NormalizedCopilotStatus` before rendering. This boundary prevents payload aliases and nullable fields from spreading through widget logic.
 
+Piped mode also passes the normalized payload to the local usage recorder before rendering. The recorder keeps bounded per-session state, appends TokenUsageInsights-compatible JSONL under `COPILOT_HOME`, and treats recording failures as non-fatal so filesystem problems cannot hide the status line.
+
 Formatter settings and Copilot CLI settings are separate:
 
 - formatter settings control lines, widgets, colors, Powerline, and local command behavior;

package/docs/USAGE.md

@@ -6,6 +6,29 @@ GitHub Copilot CLI executes the configured shell command and sends a JSON object
 
 Unknown payload fields are accepted for forward compatibility. Missing optional fields hide the corresponding widgets. Invalid known field types fail the invocation with a concise stderr message and a nonzero exit code.
 
+## Automatic token usage recording
+
+After a payload is validated, `copilotstatusline` automatically records cumulative and per-turn token usage locally. This requires no formatter option and uses the JSONL layout consumed by TokenUsageInsights.
+
+Default files:
+
+```text
+~/.copilot/usage/usage-YYYY-MM-DD.jsonl
+~/.copilot/copilotstatusline-usage-state.json
+```
+
+`COPILOT_HOME` changes both paths. The daily filename and entry timestamp use the local date and time-zone offset. Each entry can contain the Copilot session name, transcript path, working directory, version, model, token counters, context usage, durations, premium requests, and changed-line counts. These files remain local; recording and rendering make no network requests.
+
+Only a positive increase in cumulative total tokens creates a JSONL entry. Per-session state prevents interleaved Copilot sessions from affecting one another. Missing session IDs are not fabricated and therefore are not recorded. File or lock errors are reported on stderr without suppressing status-line output.
+
+Disable recording explicitly with:
+
+```sh
+COPILOTSTATUSLINE_DISABLE_USAGE_RECORDING=1 copilotstatusline
+```
+
+When Copilot invokes the command, set the same environment variable in its environment. Removing the integration does not delete recorded history. If TokenUsageInsights is configured with `COPILOT_DIR`, point it to the same directory as `COPILOT_HOME`.
+
 ## Installation
 
 Interactive installation:
@@ -44,6 +67,8 @@ Uninstallation removes `statusLine` only when its command is recognized as belon
 
 ## Formatter settings
 
+The interactive editor accepts Up/Down arrows or Vim-style `k`/`j` for vertical navigation. The same shortcuts move lines and widgets while move mode is active. Widget search and text-editing fields keep `j` and `k` as normal text input. In the widget editor, `y` clones the selected widget.
+
 Default path:
 
 ```text
@@ -118,6 +143,21 @@ The normalized widgets currently use:
 - cost: API duration, total duration, premium requests, and added/removed lines;
 - permission state: `allow_all`.
 
+Widget availability is divided by source:
+
+| Source | Widgets | Availability |
+| --- | --- | --- |
+| Copilot payload | Model, Model ID, Copilot Version, Session ID, Current Directory | Shown when Copilot supplies the corresponding field or supported alias. |
+| Optional Copilot payload | Reasoning, Session Name | Hidden when the active model has no reasoning effort or the session has no name. |
+| Copilot token payload | Input Tokens, Output Tokens, Cache Read, Cache Write, Reasoning Tokens, Total Tokens, Last Call Input, Last Call Output | Zero is shown as a real value; a missing field is hidden instead of being converted to zero. |
+| Copilot context payload | Current Context, Context Limit, Context Used, Context Remaining | Used percentage comes from the payload, or is derived when both the current value and limit are available. |
+| Copilot cost payload | Premium Requests, API Duration, Session Duration, Lines Added, Lines Removed | Shown when the corresponding cumulative counter is available. |
+| Copilot permission payload | Allow All | `Allow All: ON` and `Allow All: OFF` are rendered distinctly; a missing field is hidden. |
+| Repository probes | Git Branch, Git Changes, Jujutsu Change | Requires the matching executable and repository. Failed or timed-out probes are hidden. |
+| Local runtime | Terminal Width, Free Memory | Read from the current terminal and operating system. |
+| User configuration | Custom Text, Custom Command | Requires configured text or a command that produces output. |
+| Layout | Separator, Flex | Always available as formatting controls and does not represent Copilot payload data. |
+
 ## Diagnostics
 
 Inspect integration status:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@willh/copilotstatusline",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "bugs": {
     "url": "https://github.com/doggy8088/copilotstatusline/issues"
   },