Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/bmmmm/claudii

Shell prompt layer for Claude Code — session costs, context %, rate limits and model health. Zero daemons, pure bash+jq.
https://github.com/bmmmm/claudii

anthropic claude claude-code cli cost-tracking developer-tools homebrew oh-my-zsh shell statusline terminal zsh zsh-plugin

Last synced: 4 days ago
JSON representation

Shell prompt layer for Claude Code — session costs, context %, rate limits and model health. Zero daemons, pure bash+jq.

Awesome Lists containing this project

README 

          
# claudii



**Claude Code session intelligence in your shell — costs, prompt-cache hit rate, rate limits, model health, and effort-mode awareness. With the standalone [`cc-insomnii`](https://github.com/bmmmm/cc-insomnii) plugin, a bedtime nudge that escalates into a synthwave shame display past 1am.**



Pure bash + jq. No Python, no Node, no daemons. Read-only — claudii never modifies your sessions or makes API calls on your behalf. Compatible with oh-my-zsh, zinit, and manual source.



![CC-Statusline](screenshot-sessionline.png)



## Install



```bash

brew tap bmmmm/tap && brew install claudii

```



Add to `~/.zshrc`:

```bash

source "$(brew --prefix)/opt/claudii/libexec/claudii.plugin.zsh"

```



Enable the in-session status line (writes one key to `~/.claude/settings.json`):

```bash

claudii on

# restart Claude Code

```



Optional: install [`cc-insomnii`](https://github.com/bmmmm/cc-insomnii) for the

animated bedtime-shaming `clock` segment (5+ escalation modes, 460+ shame

messages, char-decay, matrix-rain-drip). claudii auto-detects it and

delegates the clock rendering — no settings.json change needed:

```bash

git clone https://github.com/bmmmm/cc-insomnii ~/cc-insomnii && bash ~/cc-insomnii/install.sh

claudii doctor | grep insomnii   # confirms detection

# add 'clock' to your layout if it isn't already

```



Manual install (without Homebrew)



```bash

git clone https://github.com/bmmmm/claudii ~/claudii

bash ~/claudii/install.sh

```



## What you get



Three display layers, all read-only:



### 1. CC-Statusline — inside Claude Code

Dense metrics on every turn via the native `statusLine` hook:



```

Opus xhigh ▲  ████████░░  ⚡73%

5h:28%  7d:12%  eta:4h  +47/-12

api:23m  12.4k↑ 4.2k↓  23m  feature-branch  ⌂ gateii

Opus ✓  Sonnet ✓  Haiku ✓  │  @orchestrate

⚡ commit-msg Qwen3.5-9B 2s

```



The model segment shows the active **effort mode** — the high-end modes (`xhigh`,

`ultracode`, `max`) are highlighted, `▲` marks active thinking. `ultracode` is Claude

Code's menu mode (= `xhigh` effort plus standing consent to launch multi-agent

workflows); claudii renders it whether Claude Code reports `ultracode` or the

underlying `xhigh`.



Layout, segments, and conditionals (`vpn`, `omlx`, `proxy`, `worktree` only render when relevant) are documented in `man claudii`. Multi-line layouts need Claude Code ≥ 2.1.141 — earlier versions dropped or corrupted statusline rows longer than the terminal width (fixed upstream). The `clock` segment is provided by the standalone [`cc-insomnii`](https://github.com/bmmmm/cc-insomnii) plugin (when installed) — it escalates from a quiet `☾ 22:14` to a per-character rainbow + rotating glyph + rotating shame string past 1h overdue, with `breathing-pulse`, `char-decay`, `matrix-rain-drip`, and `glyph-swarm` modes once you cross +3h. Without cc-insomnii the `clock` segment renders nothing — pure CC-Statusline still works fine for everything else.



### 2. Session Dashboard — above your shell prompt

Appears automatically after `claudii` commands when sessions are active:



```

  opus-4-8     73%  $25.63  5h:28% ↺42m

  sonnet-4-6   42%   $1.20

```



### 3. ClaudeStatus — RPROMPT

Model health in your right prompt, refreshed every 5 minutes. Never blocks your prompt.



![ClaudeStatus](screenshot-claudestatus.png)



`✓` ok · `~` degraded · `↓` down · `?` unreachable · `[…]` loading



## Commands



```bash

claudii                          # overview: sessions, account, agents, services

claudii on / off                 # enable/disable all display layers

claudii status                   # live model health check

claudii sessions / se            # active sessions: context, cost, rate

claudii sessions-inactive / si   # ended sessions + GC hint

claudii gc / g                   # garbage-collect ended sessions

claudii pin / unpin          # protect a session from garbage collection

claudii cost / c                 # per-model cost breakdown

claudii cache                    # prompt-cache hit rate + $ saved, per model & day

claudii trends / t               # weekly/daily cost history

claudii skills-cost              # per-skill / per-plugin cost (--plugins · --json · --days N)

claudii explain                  # explain claudii's layers and architecture

claudii doctor / d               # installation health check

claudii update                   # self-update (Homebrew or git checkout)

claudii changelog                # what changed between versions

claudii config get/set      # read/write config

claudii agents                   # list configured agent aliases

claudii omlx [status|connect|test|disconnect]

                                 # local-LLM (oMLX/gateii) sessionline integration

claudii vpnii [set |clear|show]

                                 # WireGuard tunnel marker for the VPN segment

                                 # (call from wg-quick PostUp/PreDown)

claudii vibemap [grid|strip|status|clear|path]

                                 # opt-in activity heatmap (default off)

```



Most data commands support `--json` and `--tsv` for scripting. Full reference: `man claudii`



## Aliases



Launch aliases register dynamically from config — add/remove without editing shell files.

Each pairs a model with an [effort level](https://platform.claude.com/docs/en/build-with-claude/effort)

(`low` → `medium` → `high` → `xhigh` → `max`); `high` is the default that balances quality

and token spend, `xhigh`/`max` for the heaviest work:



```bash

cl       # Sonnet, high effort — general default

clo      # Opus, high effort — complex tasks, server work

clm      # Opus, xhigh effort — hardest problems, maximum reasoning

clq      # Sonnet, medium effort — search mode

clh      # alias table + live model health

```



Auto-fallback: if a model is down, claudii picks a healthy one automatically.



Agent aliases launch Claude with a specific skill as the system prompt and a model/effort

tier matched to the workload (read-only Haiku for search, Sonnet for scoped features, Opus

for cross-file reasoning and orchestration):



```bash

claudii agents                              # list configured agents + their tier

claudii config set agents.myagent.skill orchestrate

claudii config set agents.myagent.model opus

claudii config set agents.myagent.effort high

```



## Config



`~/.config/claudii/config.json` — created from defaults on first run.



| Key | Default | What it does |

|-----|---------|--------------|

| `statusline.bedtime` | `23:00` | Bedtime threshold for the `clock` segment (HH:MM, local time) |

| `statusline.rate_display` | `used` | Rate-limit mode: `used` or `remaining` (counts down) |

| `statusline.lines` | _see `config/defaults.json`_ | cc-statusline layout — array of arrays of segment names |

| `vibemap.enabled` | `false` | Opt-in: log each render to `~/.cache/claudii/vibemap.tsv`. Local-only, no prompt content. |

| `fallback.enabled` | `true` | Auto-switch alias to a healthy model on outage |

| `session-dashboard.enabled` | `off` | Show session dashboard above the prompt after `claudii` commands |



All keys: `claudii config set ` (zsh completion) or `man claudii`.



## License



[GPL-3.0](LICENSE) · [ko-fi](https://ko-fi.com/bmabma)



---



How it works



**Shell prompt (ClaudeStatus):** A background subshell fetches `status.claude.com` — components API first, then RSS feed — once every 5 minutes, writes a plain-text cache file, then exits. No persistent process, no network calls in `precmd`.



**Inside Claude Code (CC-Statusline):** The native `statusLine` hook calls `claudii-cc-statusline` on each turn and passes session JSON via stdin. Nothing runs between turns.



**Cost & cache data:** Read straight from Claude Code's local session JSONL — `claudii cost`, `cache`, `trends`, and `skills-cost` aggregate it with jq. No telemetry, nothing leaves your machine.