# Footer reference

## Default layout

When `footerFormat` is empty, the HUD displays four semantic groups:

```text
Project  · pi-sakura ·  main ·  24.18
Session  · gpt-5.3 · Thinking level: high · Turn 8
Activity · Agent idle · Skill 2/3 · MCP 2
Usage    · 35%/200k · ↑ 4.2k · ↓ 1.1k · $ 0.030
```

The MCP segment counts server entries in Pi's agent-directory `mcp.json` and the project's `.pi/mcp.json`. Same-name entries count once; disabled entries are included. This is a raw file-entry count: differently spelled names such as `my-server` and `my_server` remain separate, even though Pi may reject them as a namespace collision. Zero entries hide the segment. Counts refresh with the project state polling interval. This does not report connection state, validate individual server settings, or include servers registered dynamically by extensions. Missing, unreadable, malformed, or larger-than-1-MiB files contribute no entries. Legacy adapter footer statuses remain ordinary third-party statuses.

The category column is sized from visible text so every separator aligns. When a row exceeds the terminal width, complete status segments move to an indented continuation line. Only a single segment that is wider than the available content area is truncated. Third-party extension statuses appear on the Activity group in configured `left`, `middle`, then `right` order.

Control each default-layout row independently:

```text
/zentui row project enable
/zentui row session disable
/zentui row activity toggle
/zentui row usage toggle
```

The command shape is `/zentui row <project|session|activity|usage> <enable|disable|toggle>`. Values persist under `footerRows`; all four default to `true`. Row switches apply only to the default layout and do not alter a custom single-line `footerFormat`.

## Built-in status segments

| Key | Default | Group | Description |
| --- | --- | --- | --- |
| `cwd` | on | Project | Current working directory |
| `gitBranch` | on | Project | Branch name or `HEAD` when detached |
| `gitStatus` | on | Project | Conflicts, staged, modified, untracked, stash, ahead/behind |
| `gitState` | on | Project | Git operation state such as `MERGING` or `REBASING` |
| `gitCounts` | off | Project | Numeric counts embedded in ahead/behind and stash status |
| `gitCommit` | off | Project | Short commit hash and optional exact tag |
| `gitMetrics` | off | Project | Added/deleted lines from `git diff HEAD --numstat` |
| `runtime` | on | Project | Detected language/build system and tool version |
| `packageVersion` | off | Project | Project manifest version |
| `configCounts` | off | Project | Instruction files and installed Pi packages count |
| `os` | on | Project | OS icon/text per platform |
| `username` | off | Project | `user@hostname` |
| `sessionName` | on | Session | Current Pi session name |
| `model` | on | Session | Provider and model ID |
| `thinking` | on | Session | Thinking level when reasoning-capable |
| `turnCount` | on | Session | Current turn index |
| `sessionDuration` | off | Session | Current session duration |
| `runningTools` | on | Activity | Currently running native tools and elapsed time |
| `toolCounts` | on | Activity | Cumulative completed native-tool counts |
| `activeAgents` | on | Activity | Active primary agent runs |
| `agentIdle` | on | Activity | `Agent idle` when no primary agent run is active |
| `skills` | on | Activity | Active/available skills count, e.g. `Skill 1/3` |
| `mcp` | on | Activity | File-configured MCP servers, e.g. `MCP 2` |
| `context` | on | Usage | Context percentage, window size, and/or gauge |
| `inputTokens` | on | Usage | Cumulative input tokens |
| `outputTokens` | on | Usage | Cumulative output tokens |
| `cacheDetails` | on | Usage | Cache read/write tokens and latest hit rate |
| `cost` | on | Usage | Cumulative session cost |
| `codexUsage` | on | Usage | Codex weekly quota remaining |
| `time` | off | Usage | Current time `HH:MM` |

## Template syntax

Set a custom template:

```text
/zentui format "$os  $cwd(  $git_branch)$fill($context)(  $tokens)(  $cost)"
```

Clear it:

```text
/zentui format clear
```

### Variables

- `$name` or `${name}` — variable substitution
- `( ... )` — conditional group; hidden when all contained variables are empty
- `$fill` — layout partition marker (0 = left only, 1 = left/right, 2 = left/middle/right)
- `$sep` — styled ` | ` separator, does not cause a conditional group to show

### Variable list

| Variable | Content |
| --- | --- |
| `$cwd` | Current directory |
| `$git_branch` | Git icon and branch |
| `$git_status` | Git file status and ahead/behind |
| `$git_state` | Rebase, merge, etc. operation state |
| `$runtime` | Runtime icon and tool version |
| `$session_duration` | Session duration |
| `$username` | `user@hostname` |
| `$os` | OS icon/text |
| `$time` | Current time |
| `$context` | Context state |
| `$tokens` | Token summary |
| `$cost` | Session cost |
| `$package` | Package icon and project version |
| `$package_version` | Plain project version text |
| `$git_commit` | Short commit hash and optional tag |
| `$git_tag` | Exact matching tag only |
| `$git_metrics` | Added/deleted lines |
| `$git_added` | Added lines only |
| `$git_deleted` | Deleted lines only |
| `$session_name` | Session name |
| `$model` | Provider/Model |
| `$provider` | Provider ID only |
| `$model_id` | Model ID only |
| `$thinking` | Thinking level |
| `$turn` | Turn index |
| `$cache_read` | Cumulative cache read tokens |
| `$cache_write` | Cumulative cache write tokens |
| `$cache_hit` | Latest cache hit rate |
| `$codex_usage` | Codex subscription summary |
| `$instruction_files` | `AGENTS.md` + `CLAUDE.md` total |
| `$agents_files` | `AGENTS.md` count |
| `$claude_files` | `CLAUDE.md` count |
| `$skills` | Active/available skills, e.g. `Skill 1/3` |
| `$active_skills` | Active skills count only |
| `$extensions` | Installed Pi packages count |
| `$mcp` | File-configured MCP server count |
| `$tool_counts` | Native tool completion counts |
| `$running_tools` | Recently running tools |
| `$active_agents` | Active primary agent runs |
| `$sep` | Styled ` | ` |
| `$fill` | Layout marker, renders nothing |

### Aliases

```text
$directory → $cwd
$branch → $git_branch
$status → $git_status
$state → $git_state
$commit → $git_commit
$tag → $git_tag
$duration → $session_duration
$session → $session_name
$thinking_level → $thinking
$turn_count → $turn
$codex → $codex_usage
$tools → $tool_counts
$agents → $active_agents
$separator → $sep
```

## Model quota

The status line automatically switches quota display based on model provider:

- **openai-codex**: Uses Pi Model Registry's Codex Auth to query ChatGPT usage endpoint; falls back to `codex app-server --listen stdio://`. Shows the remaining 5h window with its reset time plus the weekly limit percentage, e.g. `codex 60% 5h (14:30) 75% wk` (the reset stamp becomes `14:30 12 Feb` when the window rolls over on a later day).
- **token-switch**: Uses `TOKEN_SWITCH_API_KEY` environment variable to query billing subscription and usage. Shows available balance, e.g. `token-switch $750.00`.
- **deepseek**: Uses the credential Pi holds for the DeepSeek provider (the one `/login` stores for `deepseek`, or `DEEPSEEK_API_KEY`) to query `https://api.deepseek.com/user/balance`. Shows the total balance, preferring CNY when the account reports several currencies, e.g. `deepseek ¥110.00`. A balance query without a usable key reads as `balance error` in the footer.

All queries use a 15-second timeout, a 5-minute cache, and auto-refresh. Switching models via `/model` forces a refresh, and `/usage-refresh` refreshes whichever probe currently owns the row.