claude-code - 💡(How to fix) Fix [DOCS] Status line docs missing `refreshInterval` setting [1 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/statusline

Section/Topic

"Manually configure a status line" and "How status lines work"

Current Documentation

The docs currently say:

Add a statusLine field to your user settings (~/.claude/settings.json, where ~ is your home directory) or project settings. Set type to "command" and point command to a script path or an inline shell command.

{ "statusLine": { "type": "command", "command": "~/.claude/statusline.sh", "padding": 2 } }

And the update behavior section says:

Your script runs after each new assistant message, when the permission mode changes, or when vim mode toggles. Updates are debounced at 300ms, meaning rapid changes batch together and your script runs once things settle. If a new update triggers while your script is still running, the in-flight execution is cancelled.

The settings reference also currently shows only:

statusLine | Configure a custom status line to display context. See statusLine documentation | {"type": "command", "command": "~/.claude/statusline.sh"}

What's Wrong or Missing?

Claude Code v2.1.97 added a refreshInterval status line setting to re-run the status line command every N seconds, but the status line docs do not document that field at all.

The current page only documents event-driven re-execution and only shows type, command, and padding in configuration examples. Users cannot discover that periodic refresh is supported, what the setting name is, what units it uses, or how it interacts with the existing update triggers and cancellation behavior.

Suggested Improvement

Add refreshInterval to the status line configuration docs and the settings reference.

Suggested minimum addition under "Manually configure a status line":

refreshInterval re-runs the status line command on a timer in addition to the normal event-driven updates. The value is in seconds.

Add an example such as:

{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh",
"refreshInterval": 5,
"padding": 2
}
}

The docs should also clarify:

• whether the timer supplements or replaces the existing "after each assistant message / permission mode change / vim mode toggle" updates
• whether the interval is measured in seconds
• any default behavior when refreshInterval is omitted
• how timer-driven reruns interact with cancellation of in-flight status line commands

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 2 pages affected

Source: Changelog v2.1.97

Exact changelog entry:

Added refreshInterval status line setting to re-run the status line command every N seconds