claude-statusline: Instructions file for Codex

Agent Install Guide

This file is for coding agents (Claude Code, Cursor, Aider, Continue, Cline, etc.) acting on a user's behalf. It contains the exact non-interactive commands needed to install, verify, update, and uninstall claude-status — the zero-dependency status line for Claude Code.

If you are a human reader: the regular README has a friendlier walkthrough.

TL;DR install (one block)

pip install -U claude-status && claude-status --install && claude-status --print-config

After this command:

• The package is installed (or upgraded) from PyPI.
• ~/.claude/settings.json has statusLine.command = "claude-status" (any prior config is backed up to ~/.claude/settings.json.bak).
• --print-config prints the current install state in a machine-readable form so you can confirm success.

The user must restart Claude Code for the status line to appear. Tell them this explicitly.

Verify a clean install

claude-status --print-config

A successful install prints 9 key=value lines in stable order (8 original + subagent, appended in v0.13.0 — key=value and first-8-lines parsers keep working; a parser asserting an exact 8-line count needs updating) — values are always present (empty string when absent) so a parser can rely on a fixed line count:

installed=true
command=claude-status
type=command
refreshInterval=<integer or empty>
theme=<theme name; "default" when --theme not specified>
version=<package version, e.g. 0.5.5>
settings_path=<absolute path to settings.json>
settings_state=ok
subagent=<installed | installed_missing_flag | not_installed>

subagent reports the optional subagentStatusLine hook (per-task agent rows, v0.13.0+). To enable it on the user's behalf, add to settings.json alongside statusLine:

"subagentStatusLine": {"type": "command", "command": "claude-status --subagent"}

Exit codes (relied on by scripts):

• 0 — installed and ready
• 1 — not installed (settings missing, statusLine missing, or statusLine points at a different tool)
• 2 — settings.json exists but is corrupt or unreadable. Agents must NOT auto-install on exit code 2 — running --install would overwrite recoverable user config. Surface the stderr diagnostic to the user and stop.