Generate a config

A form built from the schema, and a file containing only what you changed.

The form

Where it goes

~/.config/claude-status/config.json

That is the user layer, the middle of the three. See Configure for how the layers merge, and Per-repo for the one key that belongs somewhere else.

Nothing creates this file for you except claude-status --configure, which writes exactly the same file the generator produces.

Three rules decide what comes out

Read these before you wonder why the download looks smaller than the form.

1. Only what you changed

The file carries $schema and every value that differs from the shipped defaults. Nothing else. A key you leave alone follows the binary forward when you upgrade — that is the entire point, and a generator that handed you a full config would freeze today’s defaults on your machine forever.

So a file with one line in it is the normal outcome, not a mistake:

{
  "$schema": "https://raw.githubusercontent.com/virajp/claude-status/main/schemas/claude-status.schema.json",
  "defaultFg": "aqua"
}

Objects are compared key by key, at every depth. Change one palette colour and you get that one colour, not the whole palette.

2. Lists come out whole

Arrays replace wholesale when the layers merge, so a list has to be written out complete or the parts you did not touch would vanish. Reorder one segment in lines and the download carries both rows, including the row you never opened. That looks like rule 1 breaking; it is rule 1 being kept.

3. “Remove” means “revert to shipped”

A config file has no way to say delete this key — the merge has no delete operator, so {"palette": {}} does nothing at all. Removing a row that the defaults ship therefore restores the shipped value, and the button says so. A row you added is genuinely removable, because removing it just stops it being written.

The one thing you can clear is a colour or a bold: setting either to null is how you turn off something the defaults switched on, and it is what the “clear” mode emits.

Colours

A colour is one of four things, anywhere one is expected:

Prefer the name. The shipped defaults reference colours by name, so a segment set to "aqua" changes when you change palette.aqua, and a segment set to [104, 157, 106] never does again.

null makes a segment fall through to defaultFg, which is the only way to undo a shipped colour.

The keys

Every key, its shape, and what it does is on the Configure page, and the generator is built from the published schema rather than from a list written here — so the two cannot drift. Each field shows the schema’s own description beside it.

Five of the keys are open maps: you choose the keys as well as the values.

subagent.statuses is the odd one: order is behaviour. Buckets are tried top to bottom and the first whose match regex hits the task status wins; the entry with an empty match is the fallback.

Three key names can never take effect — __proto__, constructor and prototype are dropped by the config merge at every depth, and the form refuses them.

Per-repo settings

The repo layer is not a form, because it takes one key. Write this at <repo-root>/.config/claude-status.json by hand:

{
  "$schema": "https://raw.githubusercontent.com/virajp/claude-status/main/schemas/claude-status.schema.json",
  "projectName": "my-repo"
}

$schema is optional and buys editor completion; projectName is the only key a repo layer may set, and every other key in that file is ignored and named by --debug. Per-repo has the rest.

projectName appears in the generator because it is in the schema, and the generator writes your user config — so this is the one field to leave alone here. A projectName in the user config is not inert: the user layer merges whole, so the name applies to every repository you open that has not set one of its own. Put it in <repo-root>/.config/claude-status.json instead, which is the only layer narrowed to this key. Per-repo shows how.

No preview yet

This page does not draw your bar. Drawing it would mean a second implementation of the renderer in JavaScript, and a preview that is plausible but wrong is worse than no preview — wrong exactly where you are doing something unusual, which is when you are most likely to be here.

To see the real thing, save the file and run:

claude-status --debug

which prints the resolved config, every layer that fed it, and the bar itself. See Diagnosing.