Statusline setup

/statusline-setup

Configure the claude-code-cli-statusline for this user: interview them for their preferences, write a config file, copy the render script to a stable location, wire it into their Claude Code settings.json, and verify it renders. After setup the statusline runs independently of this plugin, so the plugin can be uninstalled if they like.

Work through the phases in order. Each phase states what it needs and produces.

Phase 0 — Detect the environment

Inputs: none. Outputs: confirmed prerequisites + the target settings.json path.

1. Confirm bash and python are available (python --version; if missing, try python3). The render script parses JSON with python — if neither exists, stop and tell the user to install Python 3, then resume.
2. Locate the target settings.json:
   • If $CLAUDE_CONFIG_DIR is set, use $CLAUDE_CONFIG_DIR/settings.json.
   • Otherwise use ~/.claude/settings.json.
3. Read the existing settings.json (if any) and note whether a statusLine block is already configured — you'll back it up before overwriting.

Phase 1 — Interview the user

Inputs: none. Outputs: the chosen settings, held for Phase 2.

Ask with AskUserQuestion. Keep it to a few focused questions; offer sensible defaults so the user can accept everything quickly.

1. Identity label — the user@host prompt on line 1. Offer: keep the auto default (login name + hostname), a custom value, or hide it.
2. Account badge — optional [label] on line 2 for tagging a profile (e.g. work, personal). Default: none.
3. Segments to show — a multi-select over: git status, model, time, cost, token gauge, compression warning, rate limits. Default: all on.
4. Colors — offer "keep the default scheme" or customize specific segments (map their choices to STATUSLINE_COLOR_* ANSI codes; see statusline.conf.example for the keys).
5. Compression thresholds — offer the auto-scaling default (85% / 70% of the context window) or explicit token counts.

Phase 2 — Write the config and copy the script

Inputs: the Phase 1 choices. Outputs: ~/.claude-statusline/statusline.conf and a stable copy of the render script.

1. Create ~/.claude-statusline/ if it does not exist.
2. Write ~/.claude-statusline/statusline.conf from the chosen settings — only the keys the user changed from default (a minimal file is easier to read later). Use the KEY=value format documented in statusline.conf.example.
3. Copy the render script out of the plugin to a stable path so it survives plugin removal:

   cp "${CLAUDE_PLUGIN_ROOT}/scripts/statusline-script.sh" "$HOME/.claude-statusline/statusline-script.sh"
   chmod +x "$HOME/.claude-statusline/statusline-script.sh"
   

Phase 3 — Wire it into settings.json

Inputs: the settings.json path from Phase 0. Outputs: an updated settings.json.

1. Back up first: copy the existing settings.json to settings.json.bak (if it exists).
2. Set the statusLine block, pointing at the copied-out script (NOT the plugin copy — the plugin path disappears on uninstall). Use a bash-invoked forward-slash path:

   "statusLine": {
     "type": "command",
     "command": "bash <HOME>/.claude-statusline/statusline-script.sh"
   }
   

   Substitute <HOME> with the user's home in the form bash expects (on Windows/git-bash use /c/Users/<name>/...; on Linux/macOS $HOME expands fine — you may write the literal absolute path). Merge into existing settings.json without dropping other keys.

Phase 4 — Verify and offer uninstall

Inputs: the wired settings.json. Outputs: a rendered preview + next-steps note.

1. Render a preview by piping a representative statusline JSON through the copied script, e.g.:

   printf '%s' '{"workspace":{"current_dir":"'"$PWD"'"},"context_window":{"used_percentage":42,"total_input_tokens":85000,"context_window_size":200000},"model":{"id":"claude-opus-4-8"},"cost":{"total_cost_usd":1.2},"rate_limits":{"five_hour":{"used_percentage":12,"resets_at":1752000000}}}' \
     | bash "$HOME/.claude-statusline/statusline-script.sh"
   

   Show the output and confirm the segments/colors match what they chose. If not, go back to Phase 1 and adjust the config.
2. Tell the user setup is complete and the statusline now runs independently. They can:
   • Keep the plugin installed to re-run /statusline-setup later or receive updates, or
   • Uninstall it (/plugin uninstall) for a clean setup — the statusline keeps working because it references the copied-out script, not the plugin.
3. Note that the new statusline appears the next time Claude Code renders it (usually the next prompt / session).

Rules

• Never source a user's config or run untrusted lines — the render script already parses the .conf safely; you only write it.
• Always back up an existing settings.json before modifying it.
• Point settings.json at the copied-out script (~/.claude-statusline/…), never at ${CLAUDE_PLUGIN_ROOT}/… (that path vanishes on uninstall, and ${CLAUDE_PLUGIN_ROOT} is not reliably expanded inside the user's settings.json).
• Write only the config keys the user changed; leave the rest on their built-in defaults.