Codex Cost

View saved version →

---
name: codex-cost
description: Explore local Codex usage in an animated, colored ASCII terminal dashboard or static charts. Use for token totals, model breakdowns, cumulative API-equivalent cost, cost by repo, or the GPT-3 era comparison from local Codex history.
---

# Codex Cost

This skill includes its own portable tool. Resolve this skill's directory, following a symlink if necessary, and open the dashboard with `scripts/open.sh`. Do not call `node` yourself: the `node` on PATH is often older than 22.13. It needs no checkout, npm dependencies, API key, or account sign-in. A source copy without that script must first be built using this repository's skill build instructions; do not substitute a registry package with the same name.

## Opening the dashboard

When the user invokes this skill or asks to open, show, or run their dashboard, start the **animated dashboard in a new Terminal window**. A new tab cannot be created from Codex: writing into the front window pastes the command into the current Codex tab, and it never runs. The Codex TUI has no terminal of its own, so do not paint on `/dev/tty`, do not pass `--takeover`, and do not ask the user to press Ctrl+Z or q in the current tab.

```bash
/bin/sh "/absolute/path/to/codex-cost/scripts/open.sh"
```

Resolve the skill's real directory first. Append dashboard flags when asked, for example `--range 30d` or `--metric cost`. Do not pass `--takeover`, `--seconds`, or `--width` unless the user asked for a narrower chart.

The script starts the dashboard itself in a new Terminal window. Never type the launcher into the current tab. Do not claim it opened unless the command succeeded. Do not tell the user to press q in the current tab.

**This needs permission to control Terminal.app.** If the command reports that it is sandboxed or cannot reach Terminal, request approval and re-run **the same `open.sh` command**. Do not switch to a static ASCII report, and do not offer a Ctrl+Z handoff.

Do not use a desktop or computer-use tool to launch the dashboard. `open.sh` is the only launch path.

## Charts in the conversation

Use this only when the user asks for charts in the conversation, a saved report, or noninteractive output:

```bash
/bin/sh "/absolute/path/to/codex-cost/scripts/run.sh" --terminal --ascii --no-color --width 80
```

**Return the command's real output, verbatim, in a fenced `text` block.** Do not summarize it, retype it, reformat it into your own bullet list, or drop the ASCII charts — the charts are the point of running this, and a prose summary of them is not an acceptable substitute. Include the coverage and warning lines as printed. See [Static charts or structured data](#static-charts-or-structured-data) for the range, bucket, metric, and detail flags.

Only run the static command when the user asked for charts in the conversation, a saved report, or noninteractive output. A failed window launch is not that request.

## Dashboard window

The dashboard animates by owning a screen: alternate screen buffer, hidden cursor, and a repaint timer. That cannot happen inside the Codex TUI or the conversation transcript. `open.sh` starts it in a new Terminal window, where the page keys work. Press `q` in that window to quit.

## Dashboard reference

When the user asks for animation, this is the colored interactive dashboard that `open.sh` starts in a new Terminal window. It starts with ASCII characters; the `a` key switches to Unicode/Braille. Its six full-page charts are Activity, Cumulative cost, Models, Token mix, GPT-3 era, and Cost by repo. Every page summarizes the full selected range; changing pages keeps the same range and aggregate totals.

The launcher starts with colored ASCII charts. Its explicit `--no-color` option or the dashboard's `c` key switches to monochrome. For a requested range or other flags, append them to the launcher command; it passes them through. Do not claim the dashboard started unless you actually saw it run.

Controls:

- Left/Right

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 16 — file references are metadata, not package contents.