@opencode-cockpit/status 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codestz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,254 @@
+# @opencode-cockpit/status
+
+A statusline for [OpenCode](https://opencode.ai) you can actually configure — declarative segments,
+your own TypeScript, or the statusline script you already wrote for Claude Code.
+
+![The statusline under an OpenCode conversation: a context bar at 40%, the token total with its cache, input and output parts, the session diff, elapsed time and todo progress](https://raw.githubusercontent.com/Codestz/opencode-cockpit/main/media/statusline.png)
+
+Part of [opencode-cockpit](https://github.com/Codestz/opencode-cockpit). Install it on its own, or
+get it with every other bay through the `opencode-cockpit` bundle.
+
+---
+
+## Install
+
+```jsonc
+// ~/.config/opencode/tui.json
+{ "plugin": ["@opencode-cockpit/status"] }
+```
+
+That's enough. Without any configuration you get a line under the conversation carrying what
+OpenCode does not already tell you.
+
+## What it shows by default, and why it's so little
+
+OpenCode's own furniture already carries a lot: its footer has the path, the branch and the token
+count; its sidebar has the context percentage and the spend; its prompt has the agent and the model.
+
+A statusline that repeats those buys you a second copy of something already on screen — on one
+window the context percentage can end up drawn five times. So the default line is what the host
+leaves out:
+
+| Segment | Says |
+| --- | --- |
+| `session.status` | working, or `retry 2 in 5s` — OpenCode shows a spinner, not why it stalled |
+| `git.diff` | `+150 / -30` for this session |
+| `todo` | `3/7 todo`, and nothing once the list is done |
+| `session.time` | `12m04s` |
+| `diagnostics` | only when an LSP or MCP server is unhealthy |
+
+Everything else is one line of config away — including the things the host shows, if you want them
+in both places.
+
+## Configuration
+
+`~/.config/opencode-cockpit/config.json` for every project, `<project>/.cockpit.json` for one, and
+the plugin entry itself beats both.
+
+```jsonc
+{
+  "statusline": {
+    "surface": "bottom",
+    "separator": " │ ",
+    "segments": [
+      "git.diff",
+      { "type": "context", "style": "gradient", "width": 16 },
+      { "type": "cost", "color": "#e8b923" },
+      "diagnostics"
+    ]
+  }
+}
+```
+
+A segment is a built-in's name, or that name with settings. Unknown names are skipped rather than
+fatal, so a config written against a newer version costs you a segment and not the line.
+
+### Surfaces
+
+Two, each with a job.
+
+| `surface` | Where | Good for |
+| --- | --- | --- |
+| `bottom` | full-width line under the conversation | everything, when no sidebar is open |
+| `sidebar` | the sidebar, stacked vertically by default | the time dimension: trends, composition |
+
+Use `lines` for more than one at once:
+
+```jsonc
+{
+  "statusline": {
+    "lines": [
+      { "surface": "bottom", "segments": ["git.diff", "todo", "session.time"] },
+      { "surface": "sidebar", "segments": ["context", "cost"] }
+    ]
+  }
+}
+```
+
+Each line takes its own `separator`, `stack` (`horizontal` / `vertical`), `maxRows`, `icons` and
+`paddingLeft` / `paddingRight` / `paddingTop` / `paddingBottom`. The padding defaults line each
+surface up with OpenCode's own content.
+
+### When the terminal is narrow
+
+Segments carry a priority, and a line too wide for its surface drops the lowest-priority ones until
+it fits. How full the context is survives a 60-column window; the version string does not. Set
+`priority` on any segment to change what goes first. A vertical line drops by `maxRows` instead.
+
+## Built-in segments
+
+| Name | Shows | Settings |
+| --- | --- | --- |
+| `cwd` | folder, relative to the worktree | `maxWidth` |
+| `git.branch` | current branch, dimmed on the default branch | |
+| `session.diff` | `+150 / -30` — what **this session** changed, not the working tree | |
+| `model` | `claude-opus-5` | `full` |
+| `context` | how full the window is | `style`: `percent` \| `bar` \| `gradient` \| `split`, `width`, `warnAt`, `dangerAt` |
+| `tokens` | `78.5k tok` | |
+| `cost` | session spend | `currency`, `showZero` |
+| `todo` | `3/7 todo` | `showComplete` |
+| `session.status` | working, or a retry and its countdown | |
+| `session.time` | elapsed | `coarse` |
+| `diagnostics` | unhealthy LSP and MCP servers | |
+| `version` | this bay's version | |
+| `text` | literal text | `value` |
+| `command` | the output of a shell command | `name`, `row` |
+
+Every segment takes `prefix`, `suffix`, `priority`, `color` (a tone name or `#rrggbb`) and `icon`.
+
+`session.diff` reports what OpenCode's own Files list shows: the files **this session** changed. A
+file you edited by hand was never part of the session and will not appear.
+
+For the **working tree**, pair a command with the `worktree` segment in `examples/bottom.ts` — a
+built-in that shelled out would stop being a pure function of the snapshot, which is what makes
+every one of them testable without a filesystem:
+
+```jsonc
+{
+  "commands": { "tree": { "run": "git diff --shortstat", "intervalMs": 5000 } },
+  "segments": [
+    { "type": "session.diff", "prefix": "session " },
+    { "type": "worktree", "prefix": "tree " }
+  ]
+}
+```
+
+`session.diff` also answers to `git.diff`, its old and more misleading name.
+
+**A segment with nothing to say says nothing.** `cost` hides itself where nobody declared prices
+rather than reporting `$0.00`; `context` hides itself where nobody declared a window rather than
+inventing a denominator; `diagnostics` is silent while everything is healthy. That rule matters
+behind a proxy — see [Proxies](#proxies-litellm-and-friends).
+
+## Your own segments, in TypeScript
+
+The declarative config covers the usual line and a shell command covers anything with a CLI. Neither
+can read the session and decide, or remember what it saw a minute ago. A module can.
+
+```ts
+// ~/.config/opencode-cockpit/statusline.ts
+import type { CustomModule, StatusContext } from "@opencode-cockpit/status/segment"
+
+export default {
+  segments: {
+    burn(ctx: StatusContext) {
+      const session = ctx.session
+      if (!session?.priced || session.cost <= 0) return undefined
+      const minutes = (ctx.now - (session.startedAt ?? ctx.now)) / 60_000
+      if (minutes < 1) return undefined
+      const rate = session.cost / minutes
+      return { text: `$${rate.toFixed(2)}/min`, tone: rate > 0.5 ? "warning" : "muted" }
+    },
+  },
+} satisfies CustomModule
+```
+
+```jsonc
+{
+  "statusline": {
+    "modules": ["~/.config/opencode-cockpit/statusline.ts"],
+    "segments": ["burn", "git.diff"]
+  }
+}
+```
+
+The name is then usable anywhere a built-in is, and reusing a built-in's name replaces it. A segment
+returns a string, a `{ text, tone }`, or `{ runs: [...] }` for several styles in one segment — an
+icon in one colour, a figure in another, a bar whose cells are coloured by what fills them.
+
+Paths take `~`, an absolute path, or one relative to the project. A module in your config directory
+works even though nothing is installed next to it: the authoring import is resolved against the
+installed bay rather than against the module's own folder.
+
+A module is handed the same snapshot the built-ins get and touches no OpenCode api, which makes a
+custom segment exactly as testable as a built-in. It is loaded once and its segments are called on
+every repaint, so it can keep history — which is how a sparkline or a rate is possible at all.
+
+Returning `undefined` hides the segment. A segment that throws loses only its own place on the line.
+A module that will not load raises a toast naming the file, rather than silently dropping segments.
+
+**Worked examples** live in [`examples/`](./examples): `bottom.ts` is a complete line for a window
+with no sidebar; `sidebar.ts` is a quiet column beside OpenCode's own Context block. Both are loaded
+and asserted by the test suite, so neither can rot.
+
+## Your Claude Code statusline
+
+A shell command, fed the same JSON on stdin that Claude Code's `statusLine` hook sends:
+
+```jsonc
+{
+  "statusline": {
+    "commands": { "mine": { "run": "~/.claude/statusline.sh", "intervalMs": 2000 } },
+    "segments": [{ "type": "command", "name": "mine" }]
+  }
+}
+```
+
+An existing script works unchanged. The payload carries `session_id`, `cwd`, `workspace`, `model`,
+`version`, `cost.*` and — when a window was actually declared — `context_window.*` and
+`current_usage.*`. `rate_limits` is deliberately absent: it describes an Anthropic plan's quota,
+which has no meaning behind a proxy.
+
+Two differences from Claude Code, both improvements:
+
+- **It is not on the draw path.** The command runs on its own interval and the line renders whatever
+  it last returned, so a slow script makes the value stale rather than making the interface stutter.
+  A failing run leaves the last good value in place.
+- **Its colours survive.** The SGR escapes are parsed rather than stripped: 24-bit `38;2;r;g;b` and
+  the 256-colour cube become exact colours, and the basic sixteen become theme tones so a ported
+  script still follows the theme you run. Multi-row scripts keep their rows — pick one with `row`.
+
+## Proxies, LiteLLM and friends
+
+Tokens always work: they come from the provider's response. Cost and the context percentage are
+computed locally from your model catalogue, so behind a proxy they need declaring in OpenCode's own
+config:
+
+```jsonc
+{
+  "provider": {
+    "litellm": {
+      "npm": "@ai-sdk/openai-compatible",
+      "options": { "baseURL": "https://llm.corp/v1" },
+      "models": {
+        "claude-opus-5": {
+          "cost": { "input": 5, "output": 25, "cache_read": 0.5 },
+          "limit": { "context": 200000, "output": 64000 }
+        }
+      }
+    }
+  }
+}
+```
+
+Without them the `cost` and `context` segments stay silent instead of reporting `$0.00` and `0%`.
+If your proxy knows the real spend — LiteLLM's `/spend` endpoints do — a `command` segment can read
+it, which is better than any locally multiplied estimate.
+
+## Requirements
+
+OpenCode 1.18+ and Bun 1.3.5+.
+
+## Licence
+
+MIT

package/dist/core/ansi.js

@@ -0,0 +1,145 @@
+/**
+ * Turning a script's coloured output into styled runs.
+ *
+ * Statusline scripts written for Claude Code colour themselves with SGR escapes — true-colour
+ * `\\e[38;2;R;G;Bm` in the good ones. Stripping those and drawing the text grey throws away most
+ * of what the author wrote; parsing them means a script someone already tuned looks the same here
+ * as it does there, without a line of it changing.
+ *
+ * Only SGR is understood. Cursor movement and the rest are dropped, because a statusline that
+ * moves the cursor is not a statusline.
+ */
+
+const SGR = new RegExp(`${String.fromCharCode(27)}\\[([0-9;]*)m`, "g");
+
+/** The 16 basic colours, mapped to tones so they follow the user's theme rather than fighting it. */
+const BASIC_TONE = {
+  30: "text",
+  31: "error",
+  32: "success",
+  33: "warning",
+  34: "info",
+  35: "accent",
+  36: "info",
+  37: "text",
+  90: "muted",
+  91: "error",
+  92: "success",
+  93: "warning",
+  94: "info",
+  95: "accent",
+  96: "info",
+  97: "text"
+};
+const CLEAR = {};
+function hex(r, g, b) {
+  return `#${[r, g, b].map(n => Math.max(0, Math.min(255, n)).toString(16).padStart(2, "0")).join("")}`;
+}
+
+/**
+ * The xterm 256-colour cube, so `\\e[38;5;208m` is the orange the author meant rather than a
+ * guess. 0-15 are the basics, 16-231 a 6×6×6 cube, 232-255 a grey ramp.
+ */
+const CUBE = [0, 95, 135, 175, 215, 255];
+function from256(n) {
+  if (n < 16) return undefined; // a basic colour: let the tone mapping handle it
+  if (n < 232) {
+    const index = n - 16;
+    return hex(CUBE[Math.floor(index / 36) % 6], CUBE[Math.floor(index / 6) % 6], CUBE[index % 6]);
+  }
+  const grey = 8 + (n - 232) * 10;
+  return hex(grey, grey, grey);
+}
+
+/** Applies one escape's parameters to the running style. */
+function apply(style, params) {
+  let next = {
+    ...style
+  };
+  for (let i = 0; i < params.length; i++) {
+    const code = params[i];
+    if (code === 0) {
+      next = {
+        ...CLEAR
+      };
+    } else if (code === 1) {
+      next.bold = true;
+    } else if (code === 2) {
+      next.dim = true;
+    } else if (code === 22) {
+      next.bold = false;
+      next.dim = false;
+    } else if (code === 39) {
+      next.color = undefined;
+      next.tone = undefined;
+    } else if (code === 49) {
+      next.bg = undefined;
+    } else if (code === 38 || code === 48) {
+      // Extended colour: 5;n for the 256 palette, 2;r;g;b for true colour.
+      const mode = params[i + 1];
+      if (mode === 5) {
+        const value = params[i + 2];
+        const colour = from256(value);
+        if (code === 38) {
+          next.color = colour;
+          next.tone = colour ? undefined : BASIC_TONE[value < 8 ? value + 30 : value + 82];
+        } else if (colour) {
+          next.bg = colour;
+        }
+        i += 2;
+      } else if (mode === 2) {
+        const colour = hex(params[i + 2], params[i + 3], params[i + 4]);
+        if (code === 38) {
+          next.color = colour;
+          next.tone = undefined;
+        } else {
+          next.bg = colour;
+        }
+        i += 4;
+      }
+    } else if (BASIC_TONE[code]) {
+      next.tone = BASIC_TONE[code];
+      next.color = undefined;
+    }
+  }
+  return next;
+}
+
+/**
+ * Parses one line of a script's output into runs. Text with no escapes comes back as a single
+ * muted run, which is what a plain script should look like.
+ */
+export function parseAnsi(line) {
+  const runs = [];
+  let style = {
+    ...CLEAR
+  };
+  let at = 0;
+  SGR.lastIndex = 0;
+  for (let match = SGR.exec(line); match !== null; match = SGR.exec(line)) {
+    const text = line.slice(at, match.index);
+    if (text) runs.push(toRun(text, style));
+    const body = match[1] ?? "";
+    style = apply(style, body === "" ? [0] : body.split(";").map(part => Number.parseInt(part, 10) || 0));
+    at = match.index + match[0].length;
+  }
+  const rest = line.slice(at);
+  if (rest) runs.push(toRun(rest, style));
+  // Anything left over (a line of pure escapes) is nothing to draw.
+  return runs;
+}
+function toRun(text, style) {
+  const run = {
+    text
+  };
+  if (style.color) run.color = style.color;else run.tone = style.tone ?? "muted";
+  if (style.bg) run.bg = style.bg;
+  if (style.bold) run.bold = true;
+  if (style.dim) run.dim = true;
+  return run;
+}
+
+/** Every line of a script's output, parsed. Claude Code statuslines may print several rows. */
+export function parseAnsiLines(stdout) {
+  return stdout.replace(/\r/g, "").split("\n").map(line => parseAnsi(line)).filter(runs => runs.length > 0);
+}

package/dist/core/authoring.js

@@ -0,0 +1,13 @@
+/**
+ * The public surface a statusline module writes against, published as
+ * `@opencode-cockpit/status/segment`.
+ *
+ *   import type { StatusContext, CustomModule } from "@opencode-cockpit/status/segment"
+ *
+ * Everything here is a type or a pure helper: a module never touches OpenCode's plugin api, only
+ * the snapshot it is handed. That is what makes a custom segment as testable as a built-in.
+ */
+
+export { contextRatio, contextUsed, todoRemaining, unhealthy } from "./context.js";
+export { bar, basename, compact, duration, gradient, money, percent, preciseDuration, shortModel, shortPath, truncate, truncateStart } from "./format.js";
+export { cutSegment, runsOf, segmentText, segmentWidth } from "./segments.js";

package/dist/core/builtins/index.js

@@ -0,0 +1,10 @@
+import { SEGMENTS as model } from "./model.js";
+import { SEGMENTS as place } from "./place.js";
+import { SEGMENTS as session } from "./session.js";
+import { SEGMENTS as system } from "./system.js";
+
+/**
+ * Every built-in, grouped by what it talks about rather than listed in one file: adding a segment
+ * should mean opening the twenty lines it belongs with, not four hundred.
+ */
+export const BUILTINS = [...place, ...model, ...session, ...system];

package/dist/core/builtins/model.js

@@ -0,0 +1,204 @@
+/** The model in play, how full its context window is, and what the session is spending. */
+
+import { contextRatio, contextUsed } from "../context.js";
+import { bar, compact, gradient, money, percent, shortModel } from "../format.js";
+import { formatted, num, str } from "./settings.js";
+export const SEGMENTS = [{
+  name: "model",
+  icon: "◆",
+  priority: 60,
+  render(ctx, config) {
+    const model = ctx.session?.model;
+    if (!model) return undefined;
+    const text = config.full === true ? model.modelID : shortModel(model.modelID);
+    return {
+      text,
+      tone: "muted"
+    };
+  }
+}, {
+  name: "context",
+  priority: 85,
+  icon: "◔",
+  render(ctx, config) {
+    const ratio = contextRatio(ctx.session);
+    // No declared context window (a proxy, a custom provider) means no denominator. Say nothing
+    // rather than invent one.
+    if (ratio === undefined) return undefined;
+    const warnAt = num(config, "warnAt", 0.75);
+    const dangerAt = num(config, "dangerAt", 0.9);
+    const tone = ratio >= dangerAt ? "error" : ratio >= warnAt ? "warning" : "muted";
+    const style = str(config, "style") ?? "percent";
+    const width = num(config, "width", 10);
+    if (style === "split") {
+      // What is actually in the window, by where it came from: cache reads are the cheap part,
+      // fresh input the expensive one, output what the model has added. One bar, three colours,
+      // so the shape of the session is readable without a second segment.
+      const tokens = ctx.session?.tokens;
+      if (!tokens) return undefined;
+      const limit = ctx.session?.model?.contextLimit;
+      const cells = n => Math.round(n / limit * width);
+      const cached = cells(tokens.cache.read + tokens.cache.write);
+      const fresh = cells(tokens.input);
+      const out = cells(tokens.output + tokens.reasoning);
+      const used = Math.min(width, cached + fresh + out);
+      return {
+        runs: [{
+          text: "▐",
+          tone: "muted",
+          dim: true
+        }, {
+          text: "█".repeat(cached),
+          tone: "success"
+        }, {
+          text: "█".repeat(fresh),
+          tone: "info"
+        }, {
+          text: "█".repeat(out),
+          tone: "accent"
+        }, {
+          text: "·".repeat(Math.max(0, width - used)),
+          tone: "muted",
+          dim: true
+        }, {
+          text: "▌",
+          tone: "muted",
+          dim: true
+        }, {
+          text: ` ${percent(ratio)}`,
+          tone
+        }]
+      };
+    }
+    if (style === "gradient") {
+      // Every cell carries the colour of the level it stands for, interpolated rather than
+      // bucketed, so the bar reads as a measurement instead of three states.
+      const filled = Math.round(ratio * width);
+      const runs = [];
+      for (let cell = 0; cell < width; cell++) {
+        runs.push(cell < filled ? {
+          text: "█",
+          color: gradient((cell + 1) / width)
+        } : {
+          text: "░",
+          tone: "border"
+        });
+      }
+      runs.push({
+        text: ` ${percent(ratio)}`,
+        color: gradient(ratio),
+        bold: ratio >= 0.85
+      });
+      return {
+        runs
+      };
+    }
+    if (style === "bar") {
+      const filled = bar(ratio, width);
+      /**
+       * The fill carries its own meaning: green while there is room, amber as it tightens, red
+       * when it is nearly gone. It used to take the same tone as the text, which is muted below
+       * the warning threshold -- so the bar sat grey and dead for most of a session, saying
+       * nothing while occupying the widest part of the line.
+       */
+      const fill = ratio >= dangerAt ? "error" : ratio >= warnAt ? "warning" : "success";
+      return {
+        runs: [{
+          text: "▐",
+          tone: "border"
+        }, {
+          text: filled.trimEnd(),
+          tone: fill
+        }, {
+          text: "·".repeat(filled.length - filled.trimEnd().length),
+          tone: "border"
+        }, {
+          text: "▌",
+          tone: "border"
+        }, {
+          text: ` ${percent(ratio)}`,
+          tone: fill,
+          bold: ratio >= dangerAt
+        }]
+      };
+    }
+    return {
+      text: `${percent(ratio)} ctx`,
+      tone
+    };
+  }
+}, {
+  name: "tokens",
+  icon: "⧉",
+  priority: 30,
+  /**
+   * The total by default, and every part of it through `format` — which is the only way to see
+   * what a session is actually made of. A cache share of 99% looks wrong until you can read the
+   * figures behind it; with prompt caching it is usually right, and the way to know is to look.
+   *
+   *   { "type": "tokens", "format": "{total} tok · in {input} · cache {cacheRead}" }
+   */
+  render(ctx, config) {
+    const tokens = ctx.session?.tokens;
+    const used = contextUsed(tokens);
+    if (!tokens || used === 0) return undefined;
+    const shaped = formatted(config, {
+      total: compact(used),
+      totalExact: used,
+      input: compact(tokens.input),
+      output: compact(tokens.output),
+      reasoning: compact(tokens.reasoning),
+      cacheRead: compact(tokens.cache.read),
+      cacheWrite: compact(tokens.cache.write),
+      cache: compact(tokens.cache.read + tokens.cache.write)
+    });
+    if (shaped) return shaped;
+
+    /**
+     * The parts, coloured by what they are rather than labelled in a row of equal-weight text:
+     * cache green, fresh input blue, output accent — the same three colours the split bar uses,
+     * so the same quantity reads the same wherever it appears. A part that is zero is left out;
+     * "write 0" is a column spent saying nothing happened.
+     */
+    if (str(config, "style") === "parts") {
+      const parts = [["cache", tokens.cache.read + tokens.cache.write, "success"], ["in", tokens.input, "info"], ["out", tokens.output + tokens.reasoning, "accent"]];
+      const runs = [{
+        text: compact(used),
+        tone: "text",
+        bold: true
+      }];
+      for (const [label, value, tone] of parts) {
+        if (value === 0) continue;
+        runs.push({
+          text: ` ${label} `,
+          tone: "muted",
+          dim: true
+        });
+        runs.push({
+          text: compact(value),
+          tone
+        });
+      }
+      return {
+        runs
+      };
+    }
+    return {
+      text: `${compact(used)} tok`,
+      tone: "muted"
+    };
+  }
+}, {
+  name: "cost",
+  priority: 65,
+  render(ctx, config) {
+    const session = ctx.session;
+    // Unpriced is not the same as free: hide rather than claim a number nobody configured.
+    if (!session?.priced) return undefined;
+    if (session.cost <= 0 && config.showZero !== true) return undefined;
+    return {
+      text: money(session.cost, str(config, "currency") ?? "$"),
+      tone: "muted"
+    };
+  }
+}];