Statusline
GAIA adds a statusline (opens in a new tab) to Claude Code: the row under the prompt. It has two sides, and each answers a different question:
- The left side is about the session you are in: which project and branch, which model, and how full Claude’s context is.
- The right side is about the project: which GAIA commands are due, and why.
Both sides share one row, the left side first and the nudges right-aligned beside it. They are shown separately below, in the colors the statusline uses.
The left side
Section titled “The left side”my-app │ 🌳 feat/login │ Opus 5.5 (High) │ ▓▓░░░░░░░░ 18%| Segment | What it shows |
|---|---|
| Project | The main checkout’s folder name. A linked worktree shows the same name, so you always see which project you are in. |
| Branch | The branch the session is on. A 🌳 in front means the session is in a linked worktree, a separate copy of the repo on its own branch. |
| Model and effort | The model, with its effort level in parentheses when one is set: Low, Medium, High, XHigh, or Max. |
| Context bar | How full the context window is: ten cells, then the percentage of the window used. |
The context bar
Section titled “The context bar”Claude cannot see how full its own context is, so the bar shows it for you. A model’s answers get worse as its context fills, so knowing where you stand tells you when to clear and resume before quality drops. The bar’s color follows the same bands GAIA uses to decide when to ask you to clear:
| Band | Bar |
|---|---|
| Green | ▓░░░░░░░░░ 9% |
| Yellow | ▓▓▓░░░░░░░ 26% |
| Red | ▓▓▓░░░░░░░ 31% |
| 🔥 | ▓▓▓▓░░░░░░ 38% 🔥 |
| 💀 | ▓▓▓▓▓░░░░░ 46% 💀 |
The examples use a 1M-token window. Where each band starts is on Token efficiency, and what Claude does when the context reaches one is on Work lifecycle.
The statusline also saves each reading, which is how GAIA tells Claude when the context reaches a band. Without GAIA’s statusline, Claude gets no band warnings, and the audit checkpoint falls back to counting rounds.
Using your own statusline
Section titled “Using your own statusline”If you already have a global statusline (statusLine.command in ~/.claude/settings.json), /setup-gaia asks which one draws the left side: GAIA’s bar or yours. The answer applies to this machine only. The right side shows GAIA’s nudges either way.
If the left side cannot be drawn, the statusline shows Claude Code there instead.
The right side
Section titled “The right side”The right side names GAIA commands that have work to do, so upkeep comes to you instead of depending on you to remember it. Each one is a nudge: an emoji, the command, and a short reason in parentheses. Run the command, and the nudge clears once the work is done. /update-gaia, /update-deps, /gaia-wiki, /gaia-cleanse, and /gaia-debt also start when you ask Claude in plain language. /setup-gaia, /gaia-fitness, /gaia-codify, and /gaia-residue start only when you type them.
🚀 /update-gaia (2.1.0) │ 📦 /update-deps (4 outdated, 1 security)Nudges
Section titled “Nudges”Nudges always appear in this order, which is also their priority when space runs out:
| Nudge | Shows when |
|---|---|
⚙️ /setup-gaia (2 choices pending) | A setup choice is waiting for this machine, usually after a GAIA update adds one. See /setup-gaia. |
🚀 /update-gaia (2.1.0) | A newer GAIA release is out. See /update-gaia. |
📦 /update-deps (4 outdated, 1 security) | Packages are outdated or have open security advisories. See /update-deps. |
🔎 /gaia-cleanse (12 new memories) | Claude’s memory or startup files need a review. See /gaia-cleanse. |
💪 /gaia-fitness (grade B+) | Your Claude setup has something to improve, an update combined your edits with GAIA’s in harness files, or your team has changed those files often since the last check. See /gaia-fitness. |
🔨 /gaia-codify (2 recurring patterns) | The audit keeps finding the same kind of problem. See /gaia-codify. |
🐛 /gaia-debt (3 issues) | Open tech-debt issues are waiting. See /gaia-debt. |
🧹 /gaia-residue (6 residuals) | Trade-offs accepted at merge have piled up. See /gaia-residue. |
🧠 /gaia-wiki (24 commits) | The wiki has fallen behind the code. See /gaia-wiki. |
Each command’s page explains what triggers its nudge and what the reason text means.
The /update-gaia nudge has three more forms:
🚀 /update-gaia (pull 2.1.0): your teammates already updated GAIA on the default branch. Pull it instead of running a new update.🚀 /update-gaia (resume 2.1.0): you have an unfinished update of your own. Running the command picks it up.⌛️ GAIA 2.1.0 in progress (@teammate): a teammate is updating GAIA right now. There is nothing for you to run, so this form names no command.
Before setup is done
Section titled “Before setup is done”Until this machine has run its setup, the right side shows one nudge and nothing else:
⚙️ /setup-gaia (Required)While /gaia-init is still setting up a new project, the right side stays empty.
In a linked worktree
Section titled “In a linked worktree”Maintenance commands run from the main checkout, so a linked worktree shows no nudges. The one exception is ⚙️ /setup-gaia (Required), which shows everywhere until setup is done.
On a narrow terminal
Section titled “On a narrow terminal”When the nudges do not fit, they shrink one step at a time, starting with the lowest-priority one:
- The full form:
📦 /update-deps (4 outdated, 1 security) - A shorter reason, when the nudge has one:
📦 /update-deps (5) - The command alone:
📦 /update-deps - The emoji, with its count when there is one, in the default text color:
📦 5 - Hidden, and counted in a
+Nat the end of the row
A narrow row might look like this:
🚀 │ 📦 5 │ 🐛 3 +1A teammate’s GAIA update in progress never shrinks past ⌛️ GAIA 2.1.0 (@teammate), so you always see who is on it.
When it updates
Section titled “When it updates”- Every 15 seconds, Claude Code redraws the statusline, so a resized terminal or a new context reading shows up within that time.
- Every 6 hours at most, the main checkout refreshes the nudges in the background. The redraw itself never touches the network.
A redraw every 15 seconds costs next to nothing. It is a local shell script, not a call to Claude, so it uses no tokens. It reads the nudges from a cached file instead of checking GitHub or your packages, and runs no pnpm command. The slow checks run only in the background refresh, at most once every 6 hours.
- When a command finishes, it clears or refreshes its own nudge, so you are not told to run something you just ran.
- The
/gaia-debtcount also refreshes after Claude files, claims, or closes an issue, and at the start of each session.
Installing it
Section titled “Installing it”/gaia-init adds the statusline to the project’s .claude/settings.json. /setup-gaia makes its scripts executable on each machine, and warns you when the statusline Claude Code actually runs is not GAIA’s, for example because a statusLine in .claude/settings.local.json overrides it.