# Status line



The footer has two rows aligned with the composer prompt. By default the
first shows the model with its reasoning level (`gpt-5.5 xhigh`), and the
second shows the working directory and Git branch. `/statusline` opens an
inline setup view to change what each row shows.

## Configure it [#configure-it]

Row tabs in the header show which footer row is being edited; Tab switches
rows. Fields already on that row are listed first with their position, then
every other field under "Available", tagged when the other row owns it. Each
field shows the value it renders right now, or why it renders nothing (no
open PR, not on a Git branch). Branch and pull-request lookups only run once
a row uses the field, so until then they read "shown once added", then
"checking…". The focused field's description sits above the key hints.

Type to filter, use Up/Down to navigate, Space to add or remove a field, and
Left/Right to change its position. Ctrl-P switches between dim and theme
colors. Enter saves; Escape cancels. Adding a field assigned to the other row
moves it to the current row.

The live footer below previews the draft: an accent bar marks the row being
edited, the focused field's value is bold and underlined, and row 2 shows the
draft even where it would normally show background-shell or agent activity or
hide on short terminals. Enter keeps the layout only after a successful save;
Escape or a failed save restores the saved layout.

## Appearance [#appearance]

Each value's leaf (model, final folder, branch) is one step brighter than its
context (reasoning level, parent folders), and separators recede further. Turn
theme colors on to give the leaves subtle semantic accents that follow
[`/theme`](/docs/build/interactive#slash-commands); context stays muted.

Narrow rows shed detail before clipping: paths collapse from the middle
(`~/…/cluster/build-cli`, down to `~/…/build-cli`), then fields drop in the
order input tokens, output tokens, context window, used tokens, task
progress, pull request, project name, Git branch, context used, context left,
reasoning level. Anything that still overflows ends in an ellipsis. The plan
mode indicator retains priority on narrow terminals.

## Available fields [#available-fields]

Available IDs are `model-with-reasoning`, `current-dir`, `model`,
`reasoning`, `project-name`, `git-branch`, `pull-request`,
`context-remaining`, `context-used`, `context-window-size`, `used-tokens`,
`total-input-tokens`, `total-output-tokens`, and `task-progress`.

Git branch discovery runs only when needed by the footer or setup preview,
outside rendering, and refreshes after turns and shell commands. Project
names reuse startup repository discovery, falling back to the nearest known
project instruction root.

### Pull request [#pull-request]

The optional `pull-request` field shows `PR #123` for an open GitHub PR. When
`gh` reports the PR's web URL, the field is underlined and, in terminals that
support OSC 8 hyperlinks, clicking it opens the PR. Only http(s) URLs link; a
clipped field, a PR without a URL, and `TERM=linux` or `dumb` stay plain.

It reuses the installed GitHub CLI (`gh`) and its existing login: discovery
tries `gh pr view` first, then PRs associated with HEAD in the upstream
repository and fork. It never prompts for authentication. Missing `gh`,
missing login, network errors, detached HEAD, or no open PR leave the field
hidden.

PR lookup runs in the background only when selected in either row or preview,
with an eight-second total timeout. Results (including no PR) are cached for
60 seconds per directory/branch; turns, shell commands, and picker activity
refresh expired entries. Branch or directory changes invalidate the cache
immediately. A newly created or closed PR on the same branch appears on the
next refresh after the cache expires.

### Usage and progress [#usage-and-progress]

Usage fields read the token counts the gateway reports with each model
request and reset when `/clear`, a model switch, or an account change starts
a new conversation. Input counts include cached tokens for every provider.

| ID                    | Example            | Shows                                                 |
| --------------------- | ------------------ | ----------------------------------------------------- |
| `context-remaining`   | `Context 72% left` | Usable context left                                   |
| `context-used`        | `Context 28% used` | Usable context consumed                               |
| `context-window-size` | `1.05M window`     | The model's context window                            |
| `used-tokens`         | `12.3K used`       | Session input plus output, counting cached input once |
| `total-input-tokens`  | `1.2M in`          | Session input, including cached tokens                |
| `total-output-tokens` | `48K out`          | Session output                                        |
| `task-progress`       | `Tasks 2/5`        | Completed steps in the latest plan                    |

The context fields measure the latest request's input plus its completion
against the usable context: the auto-compaction threshold or the model's
window, whichever is smaller (the window alone with auto-compaction off).
They are hidden until the first reply, and again after compaction until the
next one.

The context window comes from `/v1/models`, looked up once per model in the
background, only while a row or the setup preview shows a context field. It
is hidden when the server doesn't report one; a failed lookup retries after
30 seconds.

Counts use at most three significant digits (`950`, `1.23K`, `12.3K`,
`123K`).

## Saved settings [#saved-settings]

Settings are saved together in `~/.cluster/config.toml`:

```toml
[status_line]
items = ["model-with-reasoning"]
secondary_items = ["current-dir", "git-branch", "pull-request"]
use_theme_colors = false
```

Omit `items` for defaults; `items = []` hides first-row context. Omit
`secondary_items` for the default working directory and Git branch, minus
anything already on the first row; `secondary_items = []` leaves the second
row blank. The second row uses the existing bottom padding; it hides below
12 terminal rows and during transient footer hints. Plan mode stays
on row one. Unknown IDs or duplicates within or across rows are
configuration errors. Missing runtime values are omitted, including a branch
in a detached-HEAD checkout.

## Next steps [#next-steps]

* **[Interactive sessions](/docs/build/interactive)** — the full
  slash-command reference.
* **[Config basics](/docs/build/config/basic)** — other settings stored in
  `config.toml`.