A status line for Claude Code that you knit yourself — every row, every piece of every row, is one line of config.
Features · Install · Configure · Segments · Uninstall
Opus 4.8 │ ✍️ 42% │ acme (main*) │ ◕ high │ ☑ 3/7
current ●●●●○○○○○○ 42% ⟳ 5:00pm
weekly ●●○○○○○○○○ 18% ⟳ jul 27, 5:00pm
That is the default layout. Nothing above is hardcoded: each row is a [[lines]]
block in a TOML file, and each piece of a row is a segment name you can move,
drop, or restyle without touching code.
- 🧶 Compose your own rows. Reorder segments, drop what you do not want, put two on one line — a config edit, not a code edit.
- 🧱 24 built-in segments. Model, context, directory and git, session, effort, todo lists, MCP servers, rate limits, cost, tokens, lines changed, PR.
- 🔢 Cumulative token tracking. Fresh input, cache writes, cache reads and output counted separately, because they are priced separately.
- 🔌 Anything else you want. A
commandsegment runs any shell command, with a timeout and a cache. - 📦 No runtime dependencies. One static binary — no
jq, nocurl, no Node. Installing needsnpx; rendering does not. - ⏱ Fast. No shell pipeline — no
jq, nocurl. A git subprocess runs only when the template asks for{git}, and under a timeout budget so a slow repository cannot stall the line. - 🛟 Never blanks your status line. A failing segment is dropped and the row still draws; a broken config falls back with a marker naming the file.
| Needed | Why |
|---|---|
| Claude Code | What draws the status line. The installer merges one statusLine key into its ~/.claude/settings.json |
| Node 16+ | For npx alone — the status line is a single static binary and needs no runtime |
No minimum Claude Code version: a segment whose stdin field your version does not send is dropped, so an older release renders a shorter line rather than an error.
npx @devemberx/knit-statuslineThen restart Claude Code. That is the whole install.
Pick a starting layout while installing:
npx @devemberx/knit-statusline install --preset minimalWhat the installer touches
| Path | What happens |
|---|---|
~/.claude/knit-statusline |
The binary is copied here |
~/.claude/statusline.toml |
A starting config is written — an existing one is kept unless you pass --force |
~/.claude/settings.json |
One statusLine key is merged in |
~/.claude/settings.json.bak |
Backup of your settings as they were before the first install or uninstall — written once, never overwritten |
Set CLAUDE_CONFIG_DIR and every path above moves beneath it — that is the
directory Claude Code itself reads, and ~/.claude stops being consulted.
Give it an absolute path: a relative one resolves against the working directory
of whichever process reads it, and Claude Code's is not your shell's, so
install and uninstall refuse it rather than write somewhere nothing reads.
The row still draws from a relative root — Claude Code loads that config, so we
do too — but nothing is cached, since the cache would land in each project you
open rather than under one root.
knit-statusline doctor prints the root it resolved and names anything left
behind in the old one.
Your hooks, permissions, plugins and every other setting are read, merged and
written back untouched. If statusLine already pointed at another tool, the
installer reports what it replaced — and leaves it alone on uninstall.
On Windows, a home directory containing a space or one of & ' needs Git Bash
present — it comes with Git for Windows.
Install without npm
Download the archive for your platform from Releases, unpack it, and run the binary's own installer:
./knit-statusline installBuilds ship for macOS, Linux and Windows on amd64 and arm64 — everywhere
Claude Code runs.
Verify it works
knit-statusline preview # render sample data — no Claude Code restart needed
knit-statusline doctor # config problems, with line numbers, and every available fieldpreview --sparse shows the same layout at the start of a fresh session,
before the first API call. preview --unknown shows a resumed session that
has not reported anything yet — what a legitimate … placeholder looks like,
as opposed to a segment that drops out of the row silently.
Everything lives in ~/.claude/statusline.toml, and a project can override it
with its own .claude/statusline.toml. Each [[lines]] block is one row, and
segments is what goes on it, in order:
[[lines]]
segments = ["model", "context", "dir", "effort"]
# A block with no segments is a deliberate blank row.
[[lines]]
[[lines]]
segments = ["limit.5h", "limit.7d"]
separator = " "Reorder the names, delete one you do not want, or move two onto the same row —
that is the whole customisation model. A row whose segments all turn out empty is
dropped along with its separators, so a missing value never leaves │ │ behind.
Start from a preset and edit from there:
| Preset | What it is |
|---|---|
reference |
The default. Reproduces the layout shown above. |
minimal |
One row: model, context, directory. No subprocess, no file reads. |
verbose |
Everything, including cumulative tokens, cost and lines changed. |
api |
For API-key users: rate limit rows drop out, tokens and cost take their place. |
Each preset is written out with its comments intact, so it doubles as a worked example.
- Configuration — the layout model, all 24 segments and their fields, templates and alignment, every option, presets, and per-project overrides.
- Contributing — setup, commit format, and the review conventions.
Two commands answer most questions without leaving the terminal:
knit-statusline preview # render sample data after an edit
knit-statusline doctor # config problems, and every available fieldknit-statusline uninstallRemoves the statusLine key from your settings and deletes the installed
binary — every other setting is left as it was. Your statusline.toml stays put,
so reinstalling resumes rather than starting over.
The default layout is modelled on nilbuild/claude-statusline by Kamran Ahmed. This is a rewrite rather than a fork: that implementation assembles its output as hardcoded strings, so changing what appears means editing the script.
Built against the Claude Code status line and plugin references. The contribution conventions — commit format, git hooks, PR template — are adapted from mcp-server-polarion.