Provider-Aware Statusline

See which provider actually served your request.

AI Engineering Lab is a personal research and development space for understanding AI engineering systems, developer tooling, LLM infrastructure, observability, and workflow automation. Its flagship project, the Provider-Aware Statusline, is a statusline for Claude Code behind the OmniRoute LLM routing gateway that shows which provider and model actually served your request. This repository keeps the evidence-first trail of how that project was investigated and built — research, findings, architecture, and ADRs — alongside the code, rather than hidden away. See Origin-Story.md for how the lab started and why this project exists.

Hosted documentation (for humans and AI agents): unscriptedbykramy.github.io/AI-Engineering-Lab — rendered docs, full-text for AI agents (llms.txt), and search.

What this is

A provider-aware statusline for Claude Code running behind an LLM routing gateway. It shows which AI provider and model actually served your last request—not just the label you asked for.

auto/cheap is what you asked for. opencode/big-pickle is what answered.

Every displayed value traces to an observed source (such as the local session transcript and resolved model capabilities), or it degrades gracefully when that information isn't available.

The current implementation targets Claude Code behind OmniRoute, but the underlying approach can be adapted to other AI coding clients and routing gateways with similar architectures.

What makes it different

• Shows what happened, not what was requested — the resolved provider/model, taken from the session transcript, not the requested label from the statusline payload.
• Verified evidence, not assumptions — every displayed value maps to a documented source with a defined fallback. The research, findings, and ADRs in this repository prove how the data flows.
• Zero npm dependencies — a single Node script, no npm install, no lockfile, no build step. The provider display additionally needs the OmniRoute-generated mapping (see Requirements); without it the route degrades to model-only.
• Degrades gracefully — on every failure path it falls back to model-only or the requested label; it never crashes, never guesses, and never leaks tokens or prompts.

FAQ

Which provider/model actually served my request? The statusline shows the resolved route from the session transcript — e.g. opencode/big-pickle — not the requested label. auto/cheap is what you asked for; opencode/big-pickle is what answered.

How does the statusline know which model answered? It reads the last assistant message's model field from the local session transcript (JSONL) and resolves the provider and real context window from a local empirical mapping. It is a reader, not an inferrer — see Architecture.md for the verified data flow.

Does it read my prompts or tokens? Never. It reads only the session transcript and a local mapping file — no tokens, prompts, request bodies, or gateway credentials. It never writes anything and never makes network requests.

Do I need OmniRoute or Docker? Yes if you want the provider/model display — that is the whole point of this tool. OmniRoute generates the model→provider mapping the statusline reads; without it the route degrades to model-only (e.g. claude-3-5-haiku). The statusline itself only reads local files, and the tests (68/68) pass without OmniRoute — but it does not connect to free providers or bypass anything. Docker is needed only for the out-of-band mapping-refresh script.

What is AI Engineering Lab? The evidence-first research and development space this repository documents. See Origin-Story.md for how it started.

Where is the hosted documentation? The rendered docs site: unscriptedbykramy.github.io/AI-Engineering-Lab — with full text for AI agents via llms.txt.

Try it in three steps

1. Clone this repository.
2. Run the tests — npm test (68 contract tests, zero npm dependencies).
3. Install it into Claude Code and wire it into your statusline setting — see For users.

Features

• Resolved route — shows the actual provider/model (opencode/big-pickle) from the last assistant message in the session transcript (the provider prefix needs the OmniRoute-generated mapping; without it the route is model-only).
• Real context window — the fill meter uses the resolved model's actual window from model_capabilities (110K/262K), not a payload guess.
• Staleness marker — [stale] is appended when the last resolved route is older than 5 minutes of idle.
• Git awareness — clean default branches are hidden; feature branches are muted green, main is bright red; worktrees are labeled (🌳 <name>); working-tree states (dirty, staged, conflicted, rebasing, …) get a marker.
• Failure-safe — missing transcript, unknown provider, absent mapping, or an unreadable file each degrade to a defined fallback. No error, no crash, no blank line except on total failure.
• Privacy-preserving — reads only the transcript and a local mapping file. Never reads tokens, prompts, request bodies, or your gateway credentials. Never writes, never makes network requests.

Real output, real states

Every frame below is a genuine screenshot of the tool's actual output (rendered from ANSI with Menlo font on a dark background), not an illustration:

State	Screenshot
Resolved route with provider, real context window, token deltas, dirty feature branch
No assistant message yet — the requested label until the first turn
Route older than the 5-minute staleness threshold
Model not in the empirical mapping — provider omitted (model-only, honest)
Linked worktree — labeled by name instead of its branch

Raw PNGs live in Assets/screenshots/.

For users — install & use

Requirements

• Node.js 18+ and Claude Code — required.
• OmniRoute — required for the provider/model display (the point of this tool). It is the only routing gateway this implementation has been developed and validated with. Point Claude Code at your OmniRoute instance (e.g. via ANTHROPIC_BASE_URL) with auto-style routing so requests resolve through the gateway, then generate the model→provider mapping (below). Without OmniRoute the statusline still runs and its tests pass, but the route degrades to model-only (e.g. claude-3-5-haiku); it does not connect to free providers or bypass anything. Other routing gateways may work if they expose equivalent routing and transcript information, but that has not been implemented or verified.

Install

node Scripts/deploy-statusline.js

This backs up any existing ~/.claude/statusline.js wrapper, installs the implementation to ~/.claude/statusline/, and writes a thin wrapper at ~/.claude/statusline.js so your existing settings.json command keeps working.

Wire it up

In ~/.claude/settings.json, set:

{
  "statusLine": {
    "type": "command",
    "command": "node ~/.claude/statusline.js"
  }
}

Model → provider mapping (requires OmniRoute)

The statusline reads ~/.claude/statusline-model-provider.json at runtime and never writes it. Regenerate it out-of-band when new models appear:

node Scripts/update-model-provider-mapping.js

This script reads OmniRoute's call logs from the Docker data volume the gateway writes to (by default omniroute-data), so it requires Docker and a local OmniRoute installation. It is a maintenance step, not part of the statusline: the statusline itself is a plain Node.js script and never invokes Docker.

Tests & troubleshooting

• npm test — the 68-test contract suite, zero npm dependencies; the tests run without OmniRoute.
• See Statusline/README.md for the full operational guide: layout, environment variables, the context-window fallback chain, and troubleshooting tables.

For engineers — how it works and how it was built

How it works (the short version). Every Claude Code session writes a transcript JSONL. Each assistant message records the resolved model name. The statusline reads the tail of that transcript, takes the last assistant message's model, resolves the provider and real context window from a local empirical mapping, and renders a bounded single line. It is a reader, not an inferrer — see Architecture.md for the verified data flow.

The method. This repository is an evidence-first investigation, not a marketing repo. The trail is:

Research/  →  Findings/  →  Knowledge-Base.md  →  Architecture.md + Decisions.md

Raw external research is preserved verbatim. Local observations are verified before they become findings. Architecture is approved only when every displayed value has an identified source and a defined failure behavior (ADR-0001: investigate first, design second, implement last). The 68 contract tests pin the display contract byte-for-byte.

The problem it solves

See Origin-Story.md for the full story: how the question "Which model actually answered my request?" led to an investigation, why existing tools couldn't answer it, and how it became a reusable tool.

Roadmap

Completed

• V1 — provider-aware route display (provider/model from the transcript).
• V2 — real context window from model_capabilities, provider-hue styling, worktree and branch-state labels.
• 68 contract tests; evidence-first docs + ADRs; dual licensing; CI.

Planned

• Statusline segment improvements (progress bar, UX polish).
• Broader provider/mapping coverage.
• Config-driven theming.

Future

• Generalize to other routing gateways.
• Publish the statusline as an npm package.
• Richer observability (per-request history).
• Methodology guides for other AI-engineering investigations.

Repository map

Path	Purpose
README.md	Project overview and operating principles
Hosted site	Rendered documentation, search, and full text for AI agents (llms.txt) at unscriptedbykramy.github.io/AI-Engineering-Lab
Origin-Story.md	How this project started and why it exists
Roadmap.md	Phases, gates, deliverables, and next actions
Knowledge-Base.md	Consolidated verified knowledge and open questions
Architecture.md	Current architecture, hypotheses, and verified data flows
Decisions.md	Architecture Decision Records and project-level decisions
Project Charter.md	Scope, constraints, success criteria, and non-goals
Research/	Raw external research, preserved verbatim
Findings/	Verified local conclusions and investigation reports
References/	Source links and bibliography
Scripts/	Utility scripts (deploy, mapping refresh, link check)
Statusline/	Statusline implementation, tests, and design documents
Assets/	Real statusline screenshots and supporting evidence
LICENSE / LICENSE.docs / LICENSING.md	Dual licensing (see below)
.github/	CI workflow and issue/PR templates

Project status

v2.0.0 — first public release (2026-08-05). The statusline V1→V2 work is merged to main, 68/68 contract tests pass, and the repository is licensed and documented for external use. See CHANGELOG.md.

Contributing

See CONTRIBUTING.md. In short: evidence over assumption, no secrets, and every change keeps the statusline a read-only, failure-safe reader.

Security

See SECURITY.md. The statusline never reads tokens, prompts, or request content, and never writes anything. Report vulnerabilities privately.

License

This repository uses a dual-license model to clearly separate code from documentation:

• Code / Executables / Config (the Provider-Aware Statusline and its scripts) are licensed under MIT.
• Documentation / Knowledge / Media (all markdown files, research, findings, ADRs, design docs, screenshots) are licensed under CC BY 4.0.

See LICENSING.md for the full guide, including inbound-contribution expectations.

Acknowledgments

• OmniRoute — the routing gateway this investigation started with.
• Claude Code — the environment this tool enhances, and the tool used to build it.
• models.dev Model Database — the source behind the real context windows in the empirical mapping.