Shell context chrome

Shell context chrome is the interaction layer for persistent shell context @ OpenShellOrg: the prompt is not only user@host:path › but a row of editable context tokens the shell owns and CLIs negotiate with.

In plain language: stop hiding "which Google am I?" inside `gcloud’s parallel config stack — show it in the prompt, let Left-arrow reach it, pick from a dropdown like desktop UI.

Core claim

Terminals treat the prompt as static decoration. We treat it as a compact context bar — same design move as Context-bound settings (settings follow activity) but for the shell session:

  1. Host context (user, host, path) — traditional, stable, blue-toned boxes

  2. App context (gcloud, py, aws, …) — tool-declared, grey-toned boxes (default theme)

  3. Input — command entry after the tokens

When a CLI lacks required context, it exits with a structured request; the shell injects tokens — it does not spawn a REPL that wipes the prior mental model.

Why it exists

Disorientation from parallel stacks. Composio routes by connected account per toolkit; gcloud uses named configurations — easy to act as the wrong principal.

REPL as default is wrong. Subshells and interactive forks replace the prompt entirely. That mode should be special, not the escape hatch when context is missing.

Dead left-arrow. At the start of the command line, Left-arrow does nothing useful. It should begin token focus — path, then user, then app contexts — so keyboard users can reach context without mouse or memorized env var names.

Prompt as status, not control. Users read user@host:path but cannot change app identity from the same surface they stare at between commands.

Prompt layout (line modes)

Both modes are first-class experimental surfaces. Prefer 2-line as the Open Shell default; keep 1-line for muscle memory and spatial compare. The line-mode switcher lives in the TUI top context bar (always-on chrome) — not a settings page.

See OpenShellOrg xref via prompt spatial layout.

2-line (preferred)

    [gcloud: ftn] [py: .venv]  rjamd@desk:~/code
[▶] gcloud compute instances list

  • Line 1: all contexts together (path, user@host, app tokens) — do not isolate path alone

  • Line 2: gutter (with ▶) + command editor only

  • Context row indented to gutter width for column align

1-line (compare)

[?] [gcloud: ftn] [py: .venv] rjamd@desk:~/code ▶ gcloud compute instances list

Concession: still types after chrome on the same line.

Zone Interaction

Gutter ? (overlay, leftmost on input row)

Appears when prohelp recognizes input — no --help typing

App tokens

Dropdown / typeahead / click-expand; grey boxes (default theme)

Host tokens

Path picker or cd completion; user@host display; blue boxes (default theme)

▶ input

Normal command entry; left-arrow from column 0 enters token focus (rightmost token first)

Host anchor stays on the context surface with apps (2-line) or left of ▶ (1-line). Do not resurrect permanent 3-row path-isolated layouts as defaults — wrap the context surface instead.

Top-bar placement (mode-engaged)

Prefer native host chrome; overlay fallback when negotiation fails. See shell-layer-chrome and OpenShellOrg host-chrome-negotiation.

Top-bar controls

Always-on TUI top context bar (not a settings page):

Control Values

Line mode

1-line | 2-line (preferred default: 2-line)

Arrow mode

ephemeral | persist — gutter ▶ lifetime

Arrow mode (HCI)

  • ephemeral (reticle): ▶ while editing; disappears after submit. Feels like a live cursor affordance. Never in copy.

  • persist: ▶ remains on committed history rows for scanability (“where did I type”). Present in copy.

Do not hard-code one behavior — users disagree; expose the control.

Copy tension: overlay-only ▶ (never in stdout) makes paste cleaner for scripts but removes scan markers from copied scrollback. v1 folds copy into arrow mode (no third control). Advanced later: visible-but-stripped-from-copy persist.

Token focus (keyboard)

At input column 0, ← (Left):

  1. Focus path token — inline edit / directory picker

  2. Focus host / user (combined or split per theme)

  3. Focus each app token right-to-left

  4. Wrap or stop at leftmost app token

→ from a focused token returns toward input. Enter on a focused token commits value and returns focus to input. Tab may cycle tokens forward (theme-configurable).

Selected token uses elevated contrast border; unfocused tokens stay readable but subdued.

Widget affordances

Reuse the interaction vocabulary from desktop patterns (implement via openshellorg interaction mods and/or dlang-supplemental where terminal protocol allows):

Kind Terminal behavior

enum

Dropdown (▾); arrow keys select; typeahead filter when list > ~8

string

Inline text; autocomplete from CLI-provided suggest list

path

File-path completion; optional GUI folder picker via terminal-gui-prompts when host has desktop

secret

Masked display; never log raw value in structured emit

When inline terminal widgets are insufficient, the shell-host (Windows Terminal fork) can promote the focused token to a native dropdown — same promotion rules as terminal-gui-prompts.

Color theming

Nushell’s default palette can feel jarring; context chrome needs local theme packs, not only the terminal app’s global ANSI theme.

Default scheme (v0):

  • Host tokens — blue background tint, blue foreground, subtle 1px box

  • App tokens — grey background tint, grey foreground, subtle 1px box

  • Focus ring — shared accent (not blue — avoids "everything is special")

Why not all blue for app context? App tokens multiply; an all-blue prefix reads as noise and collapses hierarchy with host tokens.

Tradeoff: Local truecolor / styled spans may diverge from terminal-wide "auto theme" sync. Mitigation: theme packs as SDL/JSON5 files; fallback to ANSI-only when $TERM capabilities lack truecolor; document which hosts support inline dropdown glyphs.

Experimentation lives in the web demo (shell-context-demo) before hardcoding in the Nushell fork.

Architecture (HCI layers)

Follow Prototype strategy:

Layer Owns

Core

Context key schema, validation, serialize session bind, CLI request parse

Controller

Token focus order, edit/commit/cancel, keyboard paths, theme resolution

Renderers

DOM demo first; ANSI box drawer for Nu fork; optional canvas for dense token rows

Thin wrappers

Astro island for web demo; Nu plugin glue in OpenShellOrg fork

Mockup / demo

Demo scenarios:

  1. Missing gcloud configuration — CLI message + tokens appear

  2. Left-arrow token focus cycle (animated hint on first visit)

  3. Theme switcher (blue/grey default vs high-contrast vs mono)

  4. Compare anti-pattern: subshell REPL that hides prior context

Relation to context-bound settings

| Shell context chrome | Context-bound settings |

Session-scoped CLI identity

Activity-scoped admin controls

Prompt tokens

Side inspector pane

CLIs declare requiresContext

Settings declare appliesWhen

OpenShellOrg protocol + Nu fork

HCI Nerdz web/GUI prototypes

Same pattern: dependent context visible beside the work — not buried in a storage room across town.

Non-goals

  • Storing OAuth tokens in prompt widgets (secrets use masked kind + OS keychain)

  • Replacing Composio connection UI

  • Pixel-perfect export of prompt chrome to every terminal emulator on day one

Literature