cxstatusline 0.3.0 → 0.4.0

package/README.md

@@ -101,11 +101,67 @@ cxstatusline
 The bare command opens the configuration TUI in an interactive terminal. Choose widgets, colors
 and themes, preview, then save explicitly or press Ctrl+S. Settings live at
 `~/.config/cxstatusline/settings.json` (or your XDG config location).
-Custom command/weather widgets and unsupported Claude-only widgets are not included.
+Claude-only widgets without a Codex data source are not included; see the widget inventory in the
+project notes for the full list and reasons.
 
 For scripts, `cxstatusline render` reads a versioned JSON payload on stdin and prints ANSI rows;
 it never opens the TUI.
 
+## Custom widgets
+
+Three widgets show your own content, with the same settings fields as ccstatusline so presets import unchanged:
+
+| Widget | Field | Shows |
+|---|---|---|
+| Custom Text | `customText` | A fixed label such as `[PROD]` |
+| Custom Symbol | `customSymbol` | One glyph or emoji such as `⚡` |
+| Custom Command | `commandPath` | The first line a shell command prints |
+
+### Custom Command execution and caching
+
+Custom Command runs `commandPath` through your shell (`/bin/sh -c`) with Codex's environment, in
+the session's working directory. It receives the Codex status payload as JSON on stdin plus `terminal_width`.
+Only the first non-empty line is shown; stderr is discarded. Set `preserveColors` (key `p`) to keep
+the command's own colour codes; other escape sequences and control characters are always removed. Configured
+background colours apply in both render modes and survive resets within the command output. `maxWidth`
+(key `w`) truncates with an ellipsis. The TUI preview never runs commands. Imported presets list their
+commands before you confirm.
+
+#### Synchronous execution (default)
+
+When `refreshMs` is unset (or `0`), commands run synchronously on **every footer redraw** (up to five
+times a second while Codex streams).
+
+Codex kills the whole statusline renderer after one second and keeps the previous frame, so
+cxstatusline caps each synchronous command at **300 ms by default, 600 ms maximum** (`timeout`, editor key
+`t`), and all commands on a render share a 600 ms budget. Over budget shows `[Budget]`; a slow
+command shows `[Timeout]`, a failing one `[Exit: N]` or `[Cmd not found]`. Commands terminated by
+external signals before the deadline report `[Signal: <name>]` rather than `[Timeout]`. Keep synchronous
+commands cheap and local: `git status -s | wc -l` and `date +%H:%M` are good fits; network calls are not.
+
+#### Background caching (`refreshMs`)
+
+For commands that take longer or should not run on every redraw, configure `refreshMs` (key `f`).
+
+- **Background refresh:** When `refreshMs` is set, rendering reads the latest result from disk and never
+  blocks the statusline or consumes renderer timeout budget. When an entry is due for an update,
+  cxstatusline spawns a detached background process to refresh it; the refresh outlives the render.
+- **Cold start:** On the very first render before the initial background run completes, the widget shows
+  `[Loading]`.
+- **Failures and timeouts:** A failing background command caches its exit code or error token; if a
+  background refresh stays outstanding or fails beyond 60 seconds, the widget settles on `[Error]` and
+  keeps showing `[Error]` across subsequent renders until a refresh succeeds.
+- **Cache location:** Cached documents live under `~/.cache/cxstatusline/commands/` (or
+  `$XDG_CACHE_HOME/cxstatusline/commands/`). Deleting this cache directory at any time is completely
+  safe; entries are re-created automatically.
+- **Eviction:** Cache entries and temporary files expire and are automatically evicted after 7 days.
+- **Session sharing constraint:** The cache key is derived from `(command, cwd)`, so every Codex
+  session running in the same working directory shares one cache entry and one payload (the payload
+  written by whichever session triggered the refresh). `refreshMs` is intended for commands whose
+  output does not depend on specific session payload details.
+- **Pipeline processes:** As with synchronous mode, `shell: true` terminates `/bin/sh` on timeout,
+  so child processes spawned inside a shell pipeline can outlive the cap. Avoid long-running pipelines.
+
 ## Update
 
 ```sh