shannon-statusline

Live ANSI HUD for Claude Code with project, model, context, throughput, tool, agent, and configuration state.

Install

npm install -g shannon-statusline

Add to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "shannon-statusline",
    "refreshInterval": 1
  }
}

refreshInterval is measured in seconds. 1 refreshes the statusline at least once per second in addition to Claude Code events.

HUD

Cyberpunk mode renders below each Claude Code response:

⌘ ~/D/project  │  ⎇ main* ↑2 !3 +1  │  ✦ 12m  │  ⊟ auto
λ Opus · claude-opus-4-6  │  ⊡ ████████░░░░ 65% (200k)  │  ↑ 36k  ↓ 300  ⊗ 8.5k
» TTFT 1.24s  │  Decode ~62.4 tok/s · ~312 tok
※ ×3 CLAUDE.md  │  ⊕ ×4 MCPs  │  ↩ ×12 hooks  │  ★ ×5 Skills
──────────────────────────────────────────────────────
✔ Read ×12  │  ✔ Edit ×7  │  ✔ Bash ×4
↻ Bash: ~/D/project/src (3s)

When model.display_name and model.id differ, both are shown. The ID reflects the active model variant.

Configuration

Optional file: ~/.shannon/shannon-statusline/config.json

{
  "rain": true,
  "throughput": true
}

Option	Type	Default	Effect
rain	boolean	true	Show the matrix column in cyberpunk mode.
throughput	boolean	true	Show response metrics on line 3.

Invalid or missing values use the defaults. Powerline mode is single-line and uses · separators:

{
  "statusLine": {
    "type": "command",
    "command": "shannon-statusline --style powerline",
    "refreshInterval": 1
  }
}

throughput: false also hides the throughput segment in powerline mode.

Metrics

• TTFT: transcript-observed time from the preceding user/tool event to the first assistant event.
• Decode: transcript-observed output rate; ~ marks an estimate.

Bridge

When a local consumer is listening, each invocation writes session data as NDJSON to /tmp/shannon-<uid>.sock.

Development

bun install
bun test
bun run build
bun run test:stdin

See CONTRIBUTING.md and RELEASING.md.

Runtime requirement: Node.js >= 22.

License

MIT