Per-repo settings

One key, one file, written by hand — and nothing creates it for you.

You probably do not need this file

The project segment names your repository whether or not this file exists. With no configuration anywhere, it draws the repository’s owner/repo from its origin remote on a GitHub or GitLab host, and without one the parent/base of its directory — a clone of acme/widget reads acme/widget; an unpushed repository in ~/src/my-repo reads src/my-repo.

So this file exists for one purpose: calling a repository something other than that. If the derived name is already the right thing, there is nothing to write.

The segment is omitted in exactly one case — you are not inside a git repository, so there is nothing to identify.

The file

<repo-root>/.config/claude-status.json

<repo-root> is the git root of the repository you are working in — the directory that contains .git, not the directory you happen to have cd’d into. Below it, .config/claude-status.json. In a linked worktree that is the worktree itself, while the name the bar derives comes from the main checkout — the two differ on purpose: the file describes the checkout you are in, the name describes the repository it belongs to.

Nothing creates this file. Not --configure, not the render, not a first run. If you want one, you write it:

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

That is the whole thing. The $schema line is optional and buys you editor completion; projectName is the only key that does anything.

What it does

projectName is the name the project segment draws, for that repository and no other. It replaces the derived name and nothing else — the glyph in front of it is chosen by how the repository was identified (symbols.projectGit, projectRemote, projectGithub or projectGitlab), and the name does not change that.

The name is resolved in this order, first match winning:

1. projectName in this file — that repository, and no other.
2. projectName in your user config. This is not inert: the user layer is merged whole, so a name set there applies to every repository that has not named itself. Setting it there is almost never what you want, and Configure says so.
3. The derived identity — owner/repo from origin, or parent/base of the identity root. The table in Segments has every case.

It is the only key this file may set. It is not in the shipped defaults, because a default name would be a name that was never about your repository.

Every other key is ignored

Not merged, not partially honoured — dropped. A repository you cloned cannot change how your bar looks, cannot raise your caps, and cannot repaint your segments.

And it does not fail silently. claude-status --doctor names each key it dropped:

CONFIG LAYERS (low to high)
  embedded loaded         <embedded>
  user     using defaults ~/.config/claude-status/config.json (no file)
  repo     loaded         /path/to/repo/.config/claude-status.json
           ignored        caps — a repo layer may set projectName only

No git root, no repo layer

If the directory you are in is not inside a git repository, there is no repo root to look under and the layer simply does not exist. --doctor says so:

repo     using defaults <no git root>

That is normal. The bar renders from the defaults and your user config, and the project segment sits out.

Committing it

The file is ordinary repository content — commit it and everyone who clones the repository gets the same name in their bar, which is usually the point. Nothing in it can affect anything else about their setup, which is why committing it is safe in a way a general-purpose config file would not be.

See Configure for the layer above it, and Segments for what project draws.