# Context Lens — Beta

Shows the live model context usage above the terminal prompt, plus a compact preview of category estimates. `/context-lens` opens the full breakdown in a pane, including on Desktop.

The video feature appears at [00:14–00:20](https://www.youtube.com/watch?v=yUuFvL1lK4k&t=14s).

## What it does

- Samples `$.session.usage({ breakdown: 'summary' })` on session start and after every main-agent turn. Subagent completions do not trigger a context sample.
- Displays input tokens and percentage against the model window; before the first response it says it is waiting instead of inventing zero usage.
- Shows locally estimated category counts against the separate compaction window. These estimates can differ from the live model input count. Deferred schemas are labelled outside the total.
- Preserves another mod's existing above-prompt content and yields when a Claude Code survey owns the band.
- Lets you refresh and close the pane. It draws the band only on the terminal surface; use `/context-lens` for a pane on other supported surfaces.

## Limits

The display updates after a completed main turn, not for every streaming token. Category counts are local estimates; the mod never requests full token counting. Data stays in the module's session memory. On hot reload it refreshes the live reading and retains no history. It does not change prompts, tools, permission decisions, or compaction behavior.

## Compatibility and verification

Beta 0.2.0, checked on 22 October 2026 with an isolated Claude Code **2.1.307**. The native `claude plugin validate` and `claude plugin test` commands pass. The tests mount the plugin's UI in Claude Code's real mods runtime with stubbed session/model operations; they do not invoke a paid model or execute tasks. Live authenticated terminal/Desktop sessions and visual pointer hover have **not** been manually verified. The mods API changes between versions; use the declarations your installed build generates as its authority. Claude Code first documented mods in 2.1.287; 2.1.307 is the tested version for this download.

Validation reports a missing catalog icon. These source downloads have not been submitted to Anthropic's plugin directory.

## Load the downloaded folder

1. Extract the download to a directory you control and review `hooks/register.js`.
2. Check your installed version with `claude --version`.
3. Start a session with `claude --plugin-dir /absolute/path/to/context-lens`.
4. Run `claude plugin validate /absolute/path/to/context-lens` and `claude plugin test /absolute/path/to/context-lens` to check against your build.

For Desktop, load the folder through the plugin-directory settings supported by your current build. The official video describes global settings; the exact setting varies with the installed release. The terminal command above is the reproducible loading path tested here.

Removing the `--plugin-dir` option on the next session unloads the mod. No external service, npm dependency, extra API key, project file mutation, or system configuration change is required by this plugin. Normal Claude Code access and billing still apply.

## Sources and authorship

Original JustADev implementation, MIT licensed. Inspired by Anthropic's [Mods in Claude Code video](https://www.youtube.com/watch?v=yUuFvL1lK4k), published 5 October 2026. Consult the [official getting started guide](https://claude.dev/blog/getting-started-with-claude-code-mods/) and [public mods API declarations](https://github.com/anthropics/claude-code/blob/main/mods/types/claude-code.d.ts). This plugin is independently published by JustADev and is not an Anthropic product.