Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@ and the project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Repo-wide session counts on line 1 (`STATUSLINE_PEERS`, on by default). When another Claude Code session works in the same repository (linked worktrees included), the right edge of line 1 counts every session, this one included, by state: `⚙` busy, `◷` background shells running, `?` idle and waiting on your answer (reverse video), `○` idle. Zero counts are omitted, the segment is hidden for a lone session, and the count the current session belongs to is bracketed (`[⚙N]`, `[◷N]` or `[○N]`); the current session never counts as `?`. States come from Claude Code's internal session registry; `?` is a hint from the end of each idle session's transcript. Codex peer threads are not counted. The segment shares line 1's spare columns with the update indicator and is dropped, never truncated, when it does not fit.

## [v3.5.1] - 2026-09-30

### Changed
Expand Down
2 changes: 2 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -201,6 +201,8 @@ Line 1 leads with two identifiers that come straight from Claude Code, sourced i
- **`@handle`** (`SESSION_HANDLE`): the addressable name peers message (`SendMessage({to})`), e.g. `@uzi-60`. Read from Claude Code's per-session registry `~/.claude/sessions/<pid>.json`, selecting the file whose `.sessionId` matches the stdin `.session_id` and taking `.name`. This covers both the auto-derived handle and a `/rename` value. **This registry is an UNDOCUMENTED internal file** (verified against Claude Code 2.1.233: `.sessionId`, `.name`, `.nameSource`, `.status`, `.messagingSocketPath`); its shape may change across versions, so the read is fully guarded and the handle just doesn't show on any miss. Toggle: `STATUSLINE_SESSION_NAME` (default 1). Test seam: `CC_STATUSLINE_SESSIONS_DIR`.
- **Title** (`SESSION_TITLE` -> `TOPIC`): the descriptive label, from the **documented** stdin `.session_name` field (Claude Code's `/rename` value, else its auto-generated session title, which it also stores in the transcript as `.aiTitle`). Absent until a title exists, so a brand-new session shows none. Toggle: `STATUSLINE_TOPIC` (default 1).

**Repo-wide session counts** (`PEER_SEG`, toggle `STATUSLINE_PEERS`) read the same registry for every live session (`.pid` alive, `.status` busy/shell/idle, `.cwd` inside a `git worktree list` path), excluding `.entrypoint == "codex"` shims. The `?` state tails each idle peer's transcript, found by glob `~/.claude/projects/*/<sessionId>.jsonl`. Test seams: `CC_STATUSLINE_SESSIONS_DIR`, `CC_STATUSLINE_PROJECTS_DIR`. Verified: a running background subagent keeps a session `busy`; `shell` means background shells are still running after the turn (observed, undocumented). SGR 5 blink does not render in the statusline (tried and removed).

Do NOT conflate the two: `.session_name` is the *title*, never the addressable handle. The default `my-app-3f`-style display name does NOT populate `.session_name` (it stays absent), which is why the handle has to come from the registry. Both values are user/model-controlled, so both get the standard control-byte strip and a 40-codepoint cap, and both ride the line-1 truncation ladder (title on the `TOPIC` rung, handle on the `NAME` rung).

**History:** the title was previously synthesized by an opt-in `UserPromptSubmit` hook (`hooks/session-topic-capture.sh`) that called Claude Haiku and wrote `~/.claude/session-topics/<id>.txt`. That hook was removed once Claude Code exposed `.session_name` natively (no credential, transcript excerpt, or quota needed). If you see references to `session-topic-capture.sh`, `_strip_ctl`, or `session-topics/` in old commits/docs, they predate that removal.
Expand Down
29 changes: 29 additions & 0 deletions KNOWN_ISSUES.md
Original file line number Diff line number Diff line change
Expand Up @@ -157,3 +157,32 @@ active Claude/OpenAI provider) so they are clickable;
glyphs, which are never truncated. `measure_cols` (and the test harness's
`vis_cols`/`_strip_ansi`) strip the OSC 8 wrapper, so it is zero-width for
layout, matching what a terminal actually renders.

## Repo-wide session counts read an internal registry

The line-1 session counts (`STATUSLINE_PEERS`) depend on Claude Code
internals and on redraw timing:

- **The registry is undocumented.** `~/.claude/sessions/<pid>.json` and its
`.status` values (`busy`, `shell`, `idle`) are internal to Claude Code and
may change in any release. The read is guarded: an unknown status is ignored
and a missing registry hides the segment. The meaning of `shell` (turn ended,
background shells still running) is inferred from observation, not
documented.
- **`?` is a guess.** It reads the end of an idle session's transcript and
flags a pending question prompt or a final line ending in `?`. A rhetorical
question shows as `?`; a request phrased without a question mark shows as
`○`.
- **A waiting session sees itself as `○`.** The current session is never
counted as `?` (you are already looking at it), so its own statusline and
the others' show the same total but a different split for as long as it
waits on you: with idle sessions A and B where only A asked something, A
shows `[○2]` and B shows `?1 [○1]`. This is intentional.
- **Counts can disagree briefly.** Each statusline counts when it redraws, so
two sessions can differ by one for up to the `refreshInterval` while a
session changes state. Without `refreshInterval`, an idle session never
redraws and its counts go stale.
- **Paths are compared literally.** A session counts when its registry `.cwd`
sits inside one of the repo's `git worktree list` paths. A cwd reached
through a symlink, or a separate repository nested inside a worktree, can be
miscounted.
17 changes: 17 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ A two-line, ANSI-colored statusline for [Claude Code](https://claude.com/claude-
- **GitHub service status**: line-1 icon (same glyphs/colors as the provider one), shown on repos with a `github.com` remote; on by default, disable with `STATUSLINE_GITHUB_STATUS=0`
- **Clickable status icons**: both service-status icons are OSC 8 hyperlinks (GitHub icon to `githubstatus.com`, provider icon to `status.claude.com` or `status.openai.com`), so Cmd+click (macOS) / Ctrl+click opens the status page in a supporting terminal; on by default, disable with `STATUSLINE_HYPERLINKS=0`
- **Update indicator**: a gold `⇡ X.Y.Z` at the right edge of line 1 when a newer cc-statusline release exists (checked hourly against GitHub, hyperlinked to the release page); hidden entirely when you are current, disable with `STATUSLINE_UPDATE_CHECK=0`
- **Sessions in this repo**: right-aligned on line 1 when another Claude Code session works in the same repository, a repo-wide count of every session by state (`⚙` busy, `◷` background shells running, `?` waiting on your answer, `○` idle), with the count your own session belongs to bracketed; disable with `STATUSLINE_PEERS=0`
- **Session name (`@handle`)**: the addressable name other Claude sessions use to message this one (Claude Code's per-session registry), shown first on line 1; on by default, hide with `STATUSLINE_SESSION_NAME=0`
- **Session title**: Claude Code's native session name (its `/rename` value or auto-generated title, from `.session_name`) as a descriptive label after the handle; hide with `STATUSLINE_TOPIC=0`
- **Tab title**: sets the terminal tab title from the session title or directory
Expand Down Expand Up @@ -160,6 +161,7 @@ The key is the project root (resolved via `git rev-parse --show-toplevel`); the
| `STATUSLINE_CACHE_TIMER` | `1` | Set to `0` to hide the prompt-cache cooldown timer on line 2 (fire + minutes left while warm, snowflake + tokens to re-cache once cold), independent of `STATUSLINE_CACHE`. When line 2 is short on room it keeps the timer and drops the hit rate first. Claude Code redraws when the cache expires, but the minutes only count down while idle with `refreshInterval` set. Hidden on GPT panes. |
| `STATUSLINE_CTX` | `1` | Set to `0` to hide the context-fill segment (`ctx NN%`) on the phone/slim layout's line 2. Shown before the rate limits with the same color thresholds; the first line-2 segment to shed as the viewport tightens. The wide layout's context readout is unaffected. |
| `STATUSLINE_SESSION_NAME` | `1` | Set to `0` to hide the `@handle` (the addressable session name peers message, read from Claude Code's per-session registry) at the start of line 1. |
| `STATUSLINE_PEERS` | `1` | Set to `0` to hide the repo-wide session counts right-aligned on line 1 (see [Sessions in this repo](#sessions-in-this-repo)). |
| `STATUSLINE_TOPIC` | `1` | Set to `0` to hide the descriptive session title on line 1 (Claude Code's `/rename` value or auto-generated title, from the `.session_name` payload field). |
| `STATUSLINE_GITHUB_STATUS` | `1` | Set to `0` to hide the GitHub service-status icon on line 1 after the branch (same glyphs/colors as the Claude icon). Shown only when the current repo has a `github.com` remote; polls `githubstatus.com` every 60s in the background. |
| `STATUSLINE_HYPERLINKS` | `1` | Set to `0` to disable the OSC 8 hyperlinks on the service-status icons (GitHub plus the active Claude/OpenAI provider). Needs a terminal that supports OSC 8 (Ghostty, iTerm2, Kitty, WezTerm); elsewhere the escape is swallowed and the icon shows as plain text. |
Expand Down Expand Up @@ -253,6 +255,21 @@ Line 1 leads with two identifiers Claude Code provides natively, so neither need

Earlier versions synthesized the title with an opt-in `UserPromptSubmit` hook that called Claude Haiku; that hook has been removed in favor of the native field, which needs no credential, transcript excerpt, or quota. If you registered that hook in `settings.json` before upgrading, remove its `UserPromptSubmit` entry: otherwise Claude Code prints `session-topic-capture.sh: No such file or directory` on every prompt (harmless but noisy). The stale `~/.claude/session-topics/` cache it wrote is safe to delete.

### Sessions in this repo

When more than one Claude Code session works in the same repository, line 1 shows a repo-wide count of all of them, your own included, at its right edge, for example `[⚙2] ◷1 ?1 ○2`:

| Glyph | Meaning |
|---|---|
| `⚙N` | busy: a turn is running (a running background subagent keeps a session busy too) |
| `◷N` | the turn ended but background shells are still running, e.g. a watcher waiting on a delegated run |
| `?N` | idle, and its last reply asked you something (an unanswered question prompt, or its final line ends with `?`); drawn in reverse video so it stands out |
| `○N` | idle and asked nothing: probably finished, a candidate for a final check |

Zero counts are left out, and the whole segment is hidden when a session is alone in its repo. The count your own session belongs to is bracketed (`[⚙N]`, `[◷N]` or `[○N]`), so each session shows where it stands; it is never counted as `?`, since you are already looking at it. "Same repo" follows `git worktree list`, so sessions in linked worktrees at other paths count too. Codex threads attached as session peers are not counted; they are Codex runs, not Claude Code sessions.

The states come from Claude Code's per-session registry (`~/.claude/sessions/*.json`, the same internal file the `@handle` uses), and `?` is a hint read from the end of each idle session's transcript, not a guarantee. Every session in the repo shows the same total, but not always the same split: a session waiting on you counts itself as `○` while the others count it as `?`, so with two idle sessions where only A asked something, A shows `[○2]` and B shows `?1 [○1]`. Each statusline also counts at its own redraw, so two sessions can briefly disagree by one; set `refreshInterval` on your `statusLine` so idle sessions redraw (60 seconds is plenty). The segment sits in line 1's spare columns next to the update indicator and is dropped, never truncated, when it does not fit. Disable with `STATUSLINE_PEERS=0`.

### Per-account usage fetcher

`claude-usage-fetch.sh` runs in the background (spawned by the statusline, throttled to once a minute across all your sessions per account) and asks `api.anthropic.com/api/oauth/usage` for the account's true 5h/7d usage, authenticated as the session itself: the session's `CLAUDE_CODE_OAUTH_TOKEN` when it was launched with one, your stored login otherwise. This exists because Claude Code feeds every session the same cached rate-limit numbers regardless of which account the session bills (shared `~/.claude.json` state), so on multi-account machines the bars were whichever account fetched last. The credential is never logged, never put in argv/env, and is only sent to `api.anthropic.com` over HTTPS. Set `STATUSLINE_RL_FETCH=0` to disable (the statusline then falls back to whatever Claude Code reports).
Expand Down
Loading
Loading