Skip to content

docs(cc-statusline): update docs for clickable links and new fields #232

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AnnatarHe merged 1 commit into from
Feb 13, 2026
Merged

docs(cc-statusline): update docs for clickable links and new fields #232

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
9 changes: 6 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,14 +88,17 @@ Add to your Claude Code settings (`~/.claude/settings.json`):
The status line will display:

```
🤖 Opus | 💰 $0.12 | 📊 $3.45 | 📈 45%
🌿 main* | 🤖 Opus | 💰 $0.12 | 📊 $3.45 | 🚦 5h:23% 7d:12% | ⏱️ 5m30s | 📈 45%
```

| Section | Description |
|---------|-------------|
| 🌿 Git Branch | Current branch name (`*` if dirty) |
| 🤖 Model | Current model name |
| 💰 Session | Current session cost |
| 📊 Today | Today's total cost (requires daemon + OTEL) |
| 💰 Session | Current session cost (clickable link to session detail) |
| 📊 Daily | Today's total cost (clickable link to coding agent page) |
| 🚦 Quota | Anthropic API quota utilization (macOS only, clickable link to usage settings) |
| ⏱️ Time | AI agent session duration (clickable link to user profile) |
| 📈 Context | Context window usage % |

For full details, see [Claude Code Statusline Guide](docs/CC_STATUSLINE.md).
Expand Down
70 changes: 52 additions & 18 deletions docs/CC_STATUSLINE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ The `shelltime cc statusline` command provides a custom status line for Claude C
- Today's total cost (from ShellTime API)
- AI agent time (session duration)
- Context window usage percentage
- Anthropic API quota utilization (5-hour and 7-day windows)
- Anthropic API quota utilization (5-hour and 7-day windows, macOS only)

## Quick Start

Expand Down Expand Up @@ -41,15 +41,28 @@ The status line will appear at the bottom of Claude Code:

## Output Format

| Section | Emoji | Description | Color |
|---------|-------|-------------|-------|
| Git | 🌿 | Current branch name (`*` if dirty) | Green |
| Model | 🤖 | Current model display name | Default |
| Session | 💰 | Current session cost in USD | Cyan |
| Today | 📊 | Today's total cost from API | Yellow |
| Quota | 🚦 | Anthropic API quota utilization | Green/Yellow/Red |
| Time | ⏱️ | AI agent session duration | Magenta |
| Context | 📈 | Context window usage % | Green/Yellow/Red |
| Section | Emoji | Description | Color | Clickable Link |
|---------|-------|-------------|-------|----------------|
| Git | 🌿 | Current branch name (`*` if dirty) | Green (Gray if unavailable) | — |
| Model | 🤖 | Current model display name | Default | — |
| Session | 💰 | Current session cost in USD | Cyan | Session detail page |
| Daily | 📊 | Today's total cost from API | Yellow when > 0, Gray when 0 | Coding agent page |
| Quota | 🚦 | Anthropic API quota utilization | Green/Yellow/Red (Gray if unavailable) | Claude usage settings (always linked) |
| Time | ⏱️ | AI agent session duration | Magenta when > 0, Gray when 0 | User profile page |
| Context | 📈 | Context window usage % | Green/Yellow/Red | — |

### Clickable Links

All cost and usage sections support terminal hyperlinks using the [OSC 8 protocol](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda). Click on the section text in a supported terminal to open the corresponding page:

| Section | Link Target |
|---------|-------------|
| 💰 Session Cost | `{webEndpoint}/users/{login}/coding-agent/session/{sessionID}` |
| 📊 Daily Cost | `{webEndpoint}/users/{login}/coding-agent/claude-code` |
| 🚦 Quota | `https://claude.ai/settings/usage` (always linked, even when showing `-`) |
| ⏱️ Time | `{webEndpoint}/users/{login}` (user profile) |

Session and Daily links require a configured ShellTime account (`userLogin` and `webEndpoint` from daemon). The Quota link is always active regardless of data availability.

### Git Status Indicator

Expand All @@ -69,6 +82,10 @@ The quota section displays your Anthropic API rate limit utilization across two

The percentage is clickable and links to your [Claude usage settings](https://claude.ai/settings/usage) page.

### Platform Note

On **Linux**, the quota section (`🚦`) is omitted entirely from the output — the statusline skips from Daily Cost to Time. On **macOS**, it is always shown (either with data or as `🚦 -`).
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The documentation states the quota section is omitted on Linux. However, the implementation checks for darwin (macOS) and omits the section for all other operating systems, including Windows. Generalizing this statement would make it more accurate for all users.

Suggested change
On **Linux**, the quota section (`🚦`) is omitted entirely from the output — the statusline skips from Daily Cost to Time. On **macOS**, it is always shown (either with data or as `🚦 -`).
On **platforms other than macOS**, the quota section (`🚦`) is omitted entirely from the output — the statusline skips from Daily Cost to Time. On **macOS**, it is always shown (either with data or as `🚦 -`).


### Quota Color Coding

Color is based on the **maximum** utilization across both windows:
Expand Down Expand Up @@ -96,16 +113,22 @@ Color is based on the **maximum** utilization across both windows:
- Model name from `model.display_name`
- Session cost from `cost.total_cost_usd`
- Context usage from `context_window`
- Working directory from `working_directory`
3. **Git info** is fetched from the daemon (which caches it for performance)
4. **Daily cost** is fetched from ShellTime GraphQL API (cached for 5 minutes)
5. **Quota utilization** is fetched from Anthropic OAuth API by the daemon (cached for 10 minutes)
6. **Output** is a single formatted line with ANSI colors
- Working directory from `cwd`
- Session ID from `session_id` (used for session cost link)
- Workspace info from `workspace` (used for session-project mapping)
3. **Session-project mapping** is sent to the daemon as a fire-and-forget message (~1ms), associating the session ID with its project directory
4. **Git info** is fetched from the daemon (which caches it for performance)
5. **Daily cost** is fetched from ShellTime GraphQL API (cached for 5 minutes)
6. **Quota utilization** is fetched from Anthropic OAuth API by the daemon (cached for 10 minutes)
7. **Clickable links** are added to Session, Daily, Quota, and Time sections using OSC 8 terminal hyperlinks
8. **Output** is a single formatted line with ANSI colors

### JSON Input (from Claude Code)

```json
{
"hook_event_name": "StatusLine",
"session_id": "abc123-def456",
"model": {
"id": "claude-opus-4-1",
"display_name": "Opus"
Expand All @@ -125,7 +148,12 @@ Color is based on the **maximum** utilization across both windows:
"cache_read_input_tokens": 2000
}
},
"working_directory": "/home/user/projects/my-app"
"cwd": "/home/user/projects/my-app",
"version": "1.0.0",
"workspace": {
"current_dir": "/home/user/projects/my-app",
"project_dir": "/home/user/projects/my-app"
}
}
```

Expand Down Expand Up @@ -171,7 +199,7 @@ If no token is configured, the daily cost will show as `-`.

Requires **macOS** and the ShellTime daemon running. The daemon reads Claude Code's OAuth token from the macOS Keychain (service name: `Claude Code-credentials`) and queries the Anthropic usage API.

- **macOS only** - Keychain access is required to retrieve the OAuth token
- **macOS only** - Keychain access is required to retrieve the OAuth token; on Linux the quota section is omitted entirely
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

For accuracy and to avoid confusion for users on other operating systems like Windows, this should mention that the quota section is omitted on all non-macOS platforms, not just Linux.

Suggested change
- **macOS only** - Keychain access is required to retrieve the OAuth token; on Linux the quota section is omitted entirely
- **macOS only** - Keychain access is required to retrieve the OAuth token; on other platforms the quota section is omitted entirely

- **Daemon required** - quota data is fetched and cached by the daemon's background timer
- **No manual setup** - if you're logged into Claude Code on macOS, it works automatically

Expand All @@ -182,6 +210,8 @@ If quota data is unavailable, the section will show as `🚦 -`.
## Performance

- **Hard timeout:** 100ms for entire operation
- **Daemon request timeout:** 50ms for the daemon socket request (fast path)
- **Session mapping:** ~1ms fire-and-forget to daemon
- **API caching:** 5-minute TTL for daily cost, 10-minute TTL for quota utilization
- **Git info caching:** Daemon fetches git info in background timer loop, not on-demand
- **Quota caching:** Daemon fetches quota data asynchronously with rate-limit protection
Expand Down Expand Up @@ -212,7 +242,7 @@ If quota data is unavailable, the section will show as `🚦 -`.

### Quota shows `-`

1. Ensure you're on **macOS** - quota display is only available on macOS
1. Ensure you're on **macOS** - quota display is only available on macOS (omitted entirely on Linux)
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

To make this troubleshooting step accurate for users on any non-macOS system (like Windows), it's better to generalize this from being specific to 'Linux'.

Suggested change
1. Ensure you're on **macOS** - quota display is only available on macOS (omitted entirely on Linux)
1. Ensure you're on **macOS** - quota display is only available on macOS (it is omitted on other platforms)

2. Verify you're logged into Claude Code (the OAuth token is stored in macOS Keychain)
3. Ensure the daemon is running: `shelltime daemon status`
4. Quota data is cached for 10 minutes - it may take a moment after daemon start
Expand All @@ -221,6 +251,10 @@ If quota data is unavailable, the section will show as `🚦 -`.

Your terminal may not support ANSI colors. Check terminal settings or try a different terminal emulator.

### Links not clickable

Your terminal must support the [OSC 8 hyperlink protocol](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda). Most modern terminals (iTerm2, WezTerm, Windows Terminal, GNOME Terminal 3.26+) support it. Older terminals or multiplexers (tmux, screen) may not.

---

## Related
Expand Down