Module segments 

Segment trait and layout-intent types. Full contract lives in docs/specs/segment-system.md; this module carries the subset the layout engine uses today: visibility, cell width, priority, separator preference, and theme role.

Modules

agent

Agent segment: renders Claude Code’s active sub-agent name from agent.name. Hidden when the payload doesn’t carry it. Opt-in: not in the default segment list.

builder

Config → Vec<Box<dyn Segment>> with validation. Hides built-in registry lookup, duplicate handling, unknown-ID warnings, per-segment override merging, and plugin-registry consultation.

context_bar

context_bar segment: visual bar for context-window fill.

context_window

Context window segment: renders {used}% · {size} where size is formatted in thousands (200k, 1M). Hidden when the payload doesn’t carry context-window data.

cost

Cost segment: renders session cost in USD. Hidden when the payload doesn’t carry cost metrics (currently always present in Claude Code).

effort

Effort segment: renders the current /effort level. Hidden when the payload doesn’t carry it.

extra_usage

extra_usage segment: monthly overage credits. Auto-hides when the account has not enabled overage (is_enabled = false); surfaces error strings for fetch failures per spec §Render semantics.

extras

Workspace-level helpers for reading [segments.<id>] TOML extras.

git_branch

git_branch segment: branch name + dirty indicator.

model

Model segment: renders the current model’s display name.

output_style

Output style segment: renders Claude Code’s active output_style.name (e.g. “default”, “concise”, “explanatory”). Hidden when the payload doesn’t carry it. Opt-in: not in the default segment list.

rate_limit

Rate-limit segment family. Renders the 5-hour and 7-day usage windows from ctx.usage() per docs/specs/rate-limit-segments.md.

session_duration

Session duration segment: renders elapsed session time in compact Nh Nm / Nm Ns / Ns form. The total_duration_ms field lives inside the input schema’s cost block, so the segment hides whenever cost is absent.

tokens

Per-turn token segments: tokens_input, tokens_output, tokens_cached, tokens_total. Each reads the corresponding field from ctx.status.context_window.current_usage (the per-turn breakdown from the most recent API call, see TurnUsage). All hide when current_usage is None — either before the first API call in a session, or when the schema didn’t supply the key.

version

Version segment: renders Claude Code’s CLI version from the top-level stdin version field. Hidden when the payload doesn’t carry it. Opt-in: not in the default segment list.

vim

Vim segment: renders Claude Code’s active vim mode (normal, insert, visual, command, replace). Hidden when the payload doesn’t carry vim. Opt-in: not in the default segment list.

workspace

Directory / worktree hybrid segment.

Structs

OverriddenSegment

Wraps a Segment to override its defaults() output while delegating render unchanged. Applying [segments.<id>] overrides without touching the inner segment.

RenderContext

Per-render layout state the engine builds once per call and threads into every Segment::render. Distinct from DataContext, which is the data layer (one instance per process invocation, shared across segments). RenderContext is the layout layer: terminal width today, room for line index / capability / neighbor info as dynamic-segment work lands.

RenderedSegment

Output of a successful segment render.

SegmentDefaults

Layout intent declared by a segment; user config may override each field.

SegmentError

Runtime failure from a segment’s Segment::render. Built-in segments return Ok(...) today; this surface is primarily for plugin-authored segments (rhai script errors, unexpected input, propagated I/O).

WidthBounds

Width bounds in cells with min <= max enforced at construction.

Enums

LineItem

One slot in a line layout: a configured segment or an inline separator between segments. The builder (build_segments / build_lines) interleaves separators between adjacent segments from [layout_options].separator; the renderer walks this list directly. See docs/specs/segment-system.md §Data model.

PowerlineWidth

Cell-count for the Nerd Font powerline chevron (U+E0B0). Most modern fonts at standard sizes render the chevron as a single cell; some larger sizes / older Nerd Font builds render it as two. The type makes any other value unrepresentable so layout-width math can’t drift into invalid territory.

Separator

Separator between adjacent segments. Chosen by the segment to its left; themes and user config can override.

Constants

BUILT_IN_SEGMENT_IDS

Every built-in segment id. Used by PluginRegistry to reject plugins whose const ID shadows a built-in. Add new built-ins here AND to built_in_by_id.

DEFAULT_SEGMENT_IDS

Default segment order when no config supplies one. No rate-limit segments are in the default line: a first-run user without any config shouldn’t trigger a macOS Keychain prompt or a network request just to render the statusline. Users opt in by listing the rate-limit segments explicitly in [line.segments].

Traits

Segment

Functions

built_in_by_id

Construct a built-in segment by its config id. Unknown ids return None so config loaders can warn and skip. extras carries the [segments.<id>] TOML bag; rate-limit segments parse their knobs from it (format, invert, compact, use_days, icon, label, stale_marker, progress_width). Other built-ins currently ignore extras.

Type Aliases

RenderResult

Shorthand for Segment::render’s return type.