dashline

A Claude Code status line configured in settings.json. The default shows the context
window on the left and plan usage on the right. Change it by editing a list of fields.

Why

dashline keeps two numbers on screen: how full the context window is, and how much of the
session and weekly rate limit is used. Both otherwise live behind the /usage command.
Any other field in the payload can be added by name.

Install

A Claude Code plugin cannot set the main status line on its own. Both routes below end
with settings.json pointing at dashline; the plugin route does it for you.

As a plugin (recommended)

/plugin marketplace add ordinarynerds/dashline
/plugin install dashline@ordinarynerds
/dashline:install

Manual

git clone https://github.com/ordinarynerds/dashline.git ~/.claude/dashline
cd ~/.claude/dashline && npm install && npm run build
./scripts/install.sh

The installer backs up settings.json, points statusLine at node dist/dashline.js,
and leaves a settings.json.bak-dashline-* file. Undo with ./scripts/install.sh --uninstall. Start a new session or run /statusline to see it. Requires Node 18+.

Updating

Plugin: enable auto-update in /plugin (Marketplaces tab), or pull on demand:

/plugin marketplace update
/reload-plugins

Manual:

cd ~/.claude/dashline && ./scripts/install.sh --update

Quick start

The config is a dashline key in ~/.claude/settings.json. Each entry in lines is one
row. This is the default:

{
  "dashline": {
    "lines": [
      { "left": ["branch", "model", "context"], "right": ["session", "weekly"] }
    ]
  }
}

An item is one of six shapes:

"branch"                                       // widget
["model", "cyan"]                              // widget + color
["cwd", "basename"]                            // widget + variant
["session", { "bar": "fine", "label": "5h" }]  // widget + options
{ "text": "api", "color": "dim" }              // literal text
"kache stat"                                   // any unrecognized string runs as a shell command

A row is either a bare array like ["branch", "model"] (left-aligned), or a
{ "left": [...], "center": [...], "right": [...] } object spread across the width.

The reference lists every widget and option.

Recipes

Each block is a value for dashline.lines and the status line it renders. Paste one into
your settings.

Cost and PR on the right

{ "left": ["branch", "model", "context"], "right": ["cost", "pr", "session"] }

Usage as bars

{
  "left": ["branch", "context"],
  "right": [
    ["session", "bar"],
    ["weekly", "bar"]
  ]
}

Reference

Widgets

Each widget reads one field of the payload; the right column is its type. A widget with no
data hides itself, and an empty row is skipped. An unrecognized bare string runs as a shell
command, and a { "text": ... } item is printed literally.

context, session, and weekly color themselves by fill (green to red). The usage
pair appears on Pro and Max once the payload carries rate limits. The burn widget, the
history variant, and the trend option read a short history of the session, so they
appear after a few refreshes.

Presentations, by type

A presentation works by type, not by widget: any percent widget takes any percent
presentation. Pass it as the item's variant. The first in each row is the default.

The percent default draws the number, bar, tokens, and countdown when each is present.
The reductive presentations (bar, pct, tokens) draw only that part.

Data options

Object-form keys that change what a widget shows rather than how. Combine them with
variant, bar, and color.

Colors

A color term is one or more of these words, so "bold red" is valid:

red · green · yellow · blue · magenta · cyan · gray · black · white · dim · bold · italic · underline

A term can also be a hex value for 24-bit color: "#4EC9D6", or "#fff" in shorthand.
Mix it with attributes, so "bold #4EC9D6" works.

The bg option fills the background of a text or label item, which makes a badge:
{ "text": " PR ", "color": "black", "bg": "#C678DD" }.

A color on an item overrides its default styling. context, session, and weekly
normally color themselves by fill; a fixed color removes that signal.

Bar styles

Any percent bar takes a bar glyph style. Every style is single-cell, so the bar
stays the same width whichever you pick.

The gradient style colors each filled cell along a green-to-red ramp by its position, so
a fuller bar reads hotter. It uses truecolor, unlike the single-color styles above.

Themes

theme remaps the named colors to a palette in one move, so every widget that uses a named
color, and the fill colors on context, session, and weekly, follow the scheme.
Available: nord, dracula, gruvbox, catppuccin.

{ "dashline": { "theme": "catppuccin", "lines": [["branch", "model", "context"]] } }

Powerline

powerline: true draws each zone as connected segments joined by arrow glyphs, with each
segment's background fading into the next. A segment takes an item's bg, or an alternating
neutral tone when it has none, so it composes with badges. The right zone runs the arrows in
reverse so the ribbon points back toward the content. Needs a Nerd Font.

Icons

icons: true prefixes label widgets (branch, model, cwd, pr, and so on) with a Nerd
Font glyph. An explicit icon on an item wins over the default. Needs a Nerd Font.

Config keys

Alongside lines, the dashline object takes:

Editor autocomplete

The config has a schema at dashline.schema.json. It constrains
only the dashline key and leaves the rest of settings.json alone. Point your editor at
it for autocomplete and validation. In VS Code, add to your settings:

"json.schemas": [
  {
    "fileMatch": ["**/.claude/settings.json", "**/.claude/settings.local.json"],
    "url": "https://raw.githubusercontent.com/ordinarynerds/dashline/main/dashline.schema.json"
  }
]

How it works

Claude Code passes the status-line command a JSON payload on stdin. dashline reads it,
reads the dashline config from the settings files, and prints one line per entry in
lines. It makes no network calls and does not read the transcript.

Each widget is a pure function from the payload to a typed value, which a presenter draws.
The git branch and worktree are not in the payload, so dashline runs git once. Each
command item runs under a 2-second timeout.

The burn widget, the history variant, and the trend option need a history, so when
the config uses one dashline keeps a small dashline-state/ directory next to the settings
with recent context samples per session. Otherwise it holds no state.

Security

dashline can run shell commands. Command sources are restricted:

• Command items run only from your own user settings (~/.claude/settings.json and
  ~/.claude/settings.local.json). Config that arrives through a project, such as a
  .claude/settings.json committed to a repository you cloned, may arrange widgets, but
  any command in it is dropped. Cloning a repo cannot make dashline run code.
• Dynamic values reach your commands through the environment ($DASHLINE_BRANCH,
  $DASHLINE_WORKTREE, $DASHLINE_CWD), never spliced into the command text, so a
  branch named like a shell expression cannot inject anything.
• dashline's own git lookups run without a shell.
• Each command runs under a 2-second timeout.
• A command's output is printed as is, including any terminal escapes it emits. Run only
  tools you trust.

Develop

npm install
npm test          # node's test runner over src
npm run build     # bundle src to dist/dashline.js
npm run typecheck

Source is in src/: widgets/ holds one file per field, present/ draws each data
type, render.ts lays out the zones, layout.ts justifies a line, and config.ts reads
and merges settings. Adding a widget is one file plus one line in widgets/registry.ts.

Releases run on release-please: commit
with Conventional Commit messages. Merging its
release PR bumps the version, writes CHANGELOG.md, and tags a release.

License

MIT © Ordinary Nerds. See LICENSE.