Statusline Reference

internal

Category:: Configuration
Type:: Reference documentation (not a runnable slash command)

Overview

The GAIA statusline renders a single line of project context on every Claude Code prompt cycle. In the default theme it looks like this:

◆ GAIA 1.127.2 | claude-opus-4-6 | my-project/feat-login | 42%

The statusline is driven by ~/.claude/gaia-statusline/statusline.sh and configured via ~/.claude/settings.json. It runs on Claude Code's built-in refreshInterval (default: 1 hour for background update checks; prompt rendering is synchronous on every cycle).

Themes

Set the theme with the GAIA_STATUSLINE_THEME environment variable. Three themes are available:

`minimal`

Model and context percentage only.

◆ claude-opus-4-6 | 42%

`default`

Version, model, project/branch, and context percentage.

◆ GAIA 1.127.2 | claude-opus-4-6 | my-project/feat-login | 42%

`rich`

Adds a second line with sprint, story, and active agent.

◆ GAIA 1.127.2 | claude-opus-4-6 | my-project/feat-login | 42%
  ▷ sprint-12 · E28-S177 · dev-fullstack

Width behavior across terminal sizes

Examples at progressively narrower terminal widths (default theme):

# 80 cols (full)
◆ GAIA 1.127.2 | claude-opus-4-6 | my-project/feat-login | 42%

# 60 cols (dirty marker dropped)
◆ GAIA 1.127.2 | claude-opus-4-6 | my-project/feat-login | 42%

# 50 cols (branch dropped BEFORE project)
◆ GAIA 1.127.2 | claude-opus-4-6 | my-project | 42%

# 40 cols (bare model only)
◆ claude-opus-4-6

See Width ladder for the full drop order.

Glyph palette

The statusline uses a fixed set of glyphs. Two alternate rendering modes are available for terminals that lack Unicode support or have Nerd Font installed.

Purpose	Unicode	Nerd Font	ASCII
Brand	`◆`	`◆`	`*`
Branch	`⎇`	Nerd Font branch glyph	`@`
Dirty marker	`*`	`*`	`*`
Context bar	`◷`	Nerd Font clock glyph	`%`
Update available	`↑`	Nerd Font arrow-up glyph	`[update]`
Rich-line separator	`▹`	`▹`	`>`
Rich-line item separator	`·`	`·`	`.`

Select a rendering mode with GAIA_STATUSLINE_NERDFONT=1 or GAIA_STATUSLINE_ASCII=1.

Color tokens

Colors are applied via ANSI escape sequences. The brand color is #7B61FF (GAIA purple). Color output is suppressed when NO_COLOR is set. True-color rendering requires COLORTERM=truecolor.

Token	Value	Usage
Brand	`#7B61FF`	The `◆ GAIA` prefix
Version (normal)	Default foreground	Version string when up to date
Version (update)	Bold	Version string when an update is available
Separator	Dim	The `\|` pipe characters
Context (low)	Green	Context usage below 60%
Context (medium)	Yellow	Context usage 60--80%
Context (high)	Red	Context usage above 80%

Width ladder

When the terminal is too narrow to fit the full statusline, segments are dropped right-to-left in this order:

Rich-line 2 (the rich theme's second line)
Dirty marker (*)
Branch name
Project name
Version string
Context bar
Bare model (last segment standing)

Key rule: at terminal widths below 50 columns, the branch is dropped before the project name. This preserves project identity at narrow widths where branch detail would be truncated anyway.

OSC-8 hyperlinks

The brand chunk (◆ GAIA) is wrapped in an OSC-8 hyperlink that opens the GAIA documentation. This is only enabled on terminals known to support OSC-8:

iTerm.app
Kitty
WezTerm

All other terminals receive the plain text -- no broken escape sequences.

Environment variables

Variable	Values	Effect
`GAIA_STATUSLINE_THEME`	`minimal`, `default`, `rich`	Selects the theme. Default: `default`.
`GAIA_STATUSLINE_NERDFONT`	`1`	Uses Nerd Font glyphs for branch, context, and update indicators.
`GAIA_STATUSLINE_ASCII`	`1`	Falls back to pure ASCII glyphs. Takes precedence over Nerd Font.
`NO_COLOR`	(any value)	Suppresses all ANSI color output.
`COLORTERM`	`truecolor`	Enables 24-bit true-color rendering for the brand color.

Source of truth

The version number displayed in the statusline is read from gaia-framework/plugins/gaia/.claude-plugin/plugin.json (the .version field). It is not read from CLAUDE.md. This ensures the statusline always reflects the installed plugin version.

Update check

The statusline includes a background update check that runs on Claude Code's refreshInterval (default: 1 hour). The check works as follows:

The fetcher writes the latest release metadata to ~/.claude/gaia-statusline/cache/latest-release.json.
The cache file has a 24-hour TTL (writer-side). The fetcher skips the network call if the cache is fresh.
The reader applies a 7-day stale fence. If the cache is older than 7 days, the update indicator is suppressed rather than showing stale data.
The hot path (prompt rendering) performs zero network calls. It reads only the local cache file.

When an update is available, three signals appear simultaneously:

The ↑ glyph (or [update] in ASCII mode) is appended.
The version string is rendered in bold.
In ASCII mode, a [update] prefix appears.

Performance

The statusline has a strict performance budget:

p95: under 100 ms
Ceiling: 300 ms (hard maximum)

These targets are met by reading only local files on the hot path and deferring network activity to the background refresh interval.

Enable / disable

Three surfaces control the statusline:

Surface	What it does
Claude Code built-in `/statusline`	Native toggle for Claude Code's statusline feature.
`install-statusline.sh`	One-shot installer. Copies the runtime to `~/.claude/gaia-statusline/` and enables the statusline in `settings.json`.
`/gaia-statusline-enable` / `/gaia-statusline-disable`	GAIA slash skills that add or remove the `statusLine` block in `settings.json`. Idempotent.

Troubleshooting

Statusline not appearing

Check that ~/.claude/gaia-statusline/statusline.sh exists and that ~/.claude/settings.json contains a statusLine block. Run /gaia-statusline-enable to add it.

Garbled glyphs

Your terminal may not support Unicode. Set GAIA_STATUSLINE_ASCII=1 to fall back to plain ASCII characters.

No colors

Check that NO_COLOR is not set in your environment. For true-color brand rendering, ensure COLORTERM=truecolor is set.

Update indicator stuck

Delete ~/.claude/gaia-statusline/cache/latest-release.json to force a fresh check on the next refresh interval.

Slow prompt rendering

The statusline's hot path reads only local files and should complete in under 100 ms. If you observe delays, check disk I/O. The statusline performs zero network calls on the hot path.