ccsl

Claude Code Statusline

A rich, information-dense statusline for Claude Code.

ccsl replaces Claude Code's default statusline with a dense, color-coded ANSI badge display. It shows your model and plan, session duration, cost, context window usage, git status, file changes, PR links, active tools, sub-agents, task progress, and more — all rendered as compact badges with gradient backgrounds that shift color based on values.

What's New

v0.2.7 — Documentation and release housekeeping.

v0.2.5 — 7-day usage badge with gradient coloring, usage API rate limit resilience with stale ~ fallback, last-known-good cache across API failures.

v0.2.4 — Compaction badge (📦), emoji terminal fallbacks.

See all changes in Releases.

Contents

• Layouts · Badge Reference · Quick Start · Configuration · Width Modes
• How It Works · Privacy · See Also · Contributing

Layouts

Three layout modes — dense (fixed header rows, default), semantic (one category per row), and adaptive (auto-wrapping stream). Badges have colored backgrounds that shift based on values — cost from green to red, duration from green to purple, context bars from green to yellow to red.

Badge Reference

Every badge the statusline can show, with all possible states:

| Badge | Description | States | |---|---|---| | Model / Plan | Current Claude model and subscription plan | Opus, Sonnet \| Pro, Opus \| Max | | Duration | Session wall-clock time. Background shifts green → gold → purple | 30s, 12m, 1h 30m, 3h | | Cost | Cumulative API cost. Background shifts green → gold → orange → red | $0.42, $4.82, $50, $123 | | Context window | Visual progress bar of token usage with color-coded fill | Green (<70%), yellow (70–84%), red (≥85%) | | Cache breakdown | Token split: cache read / cache write / uncached | 🔥 12kr·5kw·800u | | Usage (5h) | 5-hour API utilization bar with reset timer. ~ prefix means stale (API temporarily unavailable) | ⚡ 12% (4h 23m / 5h) — bar fills green/yellow/red. Stale: ⚡ ~42% | | Usage (7d) | 7-day rolling utilization | 7d 26%, stale: 7d ~26% | | Repo name | Git repository name | ccsl, my-project | | Branch / Worktree | Current branch (🌿) or worktree (🌳). Main/master shown in purple | 🌿 main, 🌿 feature/auth, 🌳 fix-login | | File stats | Dirty file counts: modified (!), added (+), deleted (✘), untracked (?) | !3, !1+2?4, !5+3✘1?2 | | Ahead / Behind | Commits ahead/behind remote tracking branch | ↑3, ↓2, ↑5↓1 | | Lines changed | Total lines added (green) and removed (red) in session | 📊 +284-67 | | Config summary | Counts of CLAUDE.md files, MCP servers, and hooks | 📋 2 CLAUDE.md \| 5 MCPs \| 3 hooks | | Ticket marker | Jira-style ticket ID extracted from PR title | 🎫 PROJ-123 | | PR link | Clickable PR with status: Draft, Open, Mergeable (✅), Merged, Closed | 🔗 PR#42 (D), (O), (✅), (M), (C) | | Recall status | Whether /recall was run this session | 🧩 ✓ (recalled), 🧩 ✗ (not recalled) | | Learn status | Compact relative time since last /learn, plus unprocessed observation count or ✓ | 📚 15m ✓ (recent, all processed), 📚 3d 1418 (3 days ago, 1418 pending), 📚 ⚠ 500 (pending) | | Instinct status | Active instinct count with promotion/correction indicators | 🧬 21 (normal), 🧬 21 ▲3 (3 promotable), 🧬 21 ! (corrections detected) | | Remote Control | Claude Code Remote Control status | 📱 RC, 📱 local | | Transcript link | Clickable file:// hyperlink to session transcript | 📝 session-abc.jsonl | | Running tool | Currently executing tool with target | ◐ Bash: npm test, ◐ Read: src/types.ts | | Completed tools | Tool use counts, color-coded by category | Read×12, Grep×6, Bash×8, WebSearch×1 | | MCP tools | MCP tool counts grouped by server | 🔌playwright×6, 🔌context7×3 | | Running agent | Active Task subagent with elapsed time | ◐ feature Review auth… (2m 30s) | | Completed agents | Recent finished agents (max 2) with duration | ✓ feature Review auth… 2m | | Tasks | Current task from TodoWrite with progress | ▸ Add rate limiting (3/6), ✓ All done (6/6) |

Note: Badges marked with features.* in the reference image require the corresponding feature toggle in config.

Quick Start

1. Install

npm install -g ccsl

2. Configure Claude Code

Add to your ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "ccsl"
  }
}

That's it. Claude Code will pipe status data to ccsl on every update.

Configuration

Interactive Setup

The easiest way to configure ccsl is the interactive wizard:

ccsl setup

This walks you through preset selection, row composition, flex settings, and feature toggles — with a live preview of your statusline before saving.

Config File

Configuration is stored in ~/.claude/statusline-config.json. The rows array defines which badge groups appear on each row:

{
  "rows": [
    ["identity", "learning", "remoteControl"],
    ["context", "usage", "config"],
    ["git", "pr"],
    "---",
    ["transcript", "tools"],
    ["agents"],
    ["todos"]
  ],
  "flexMode": "full-until-compact",
  "compactThreshold": 85,
  "flexPadding": 50,
  "features": {
    "usage": false,
    "learning": false,
    "remoteControl": false
  }
}

Each row is an array of badge group IDs. Use "---" for a separator line. Rows with no output (e.g., no agents running) are automatically hidden.

Badge Groups

| ID | Badges | |---|---| | identity | Model/plan, duration, cost | | context | Context bar, token breakdown | | usage | API rate limit bar | | git | Repo, branch, file stats, ahead/behind, lines | | config | CLAUDE.md count, MCPs, hooks | | pr | Ticket marker, PR link | | learning | Recall, learn, instinct | | remoteControl | Remote control status | | transcript | Session transcript link | | tools | Running/completed tools, MCP tools | | agents | Running/completed agents | | todos | Todo progress |

Presets

Three preset starting points (available via ccsl setup):

• Dense (default) — Compact multi-row layout. Groups related badges together on shared rows.
• Semantic — One category per row. More vertical, easier to scan.
• Adaptive — All badges on a single auto-wrapping line.

Layout & Display

| Option | Description | Default | |---|---|---| | rows | Row composition array (see above) | Dense preset | | flexMode | Terminal width strategy (see Width Modes) | full-until-compact | | compactThreshold | Context % that triggers compact width in full-until-compact mode (1–99) | 85 | | flexPadding | Chars reserved for right-side notifications (all modes) | 50 |

Backwards compatibility: Old configs using "layout": "dense" / "semantic" / "adaptive" still work — they're mapped to equivalent row presets.

Feature Toggles

| Option | Description | Default | |---|---|---| | features.usage | Show Anthropic API usage rate limit bar (see privacy note) | false | | features.learning | Show recall/learn/instinct status badges (for custom learning loop integration) | false | | features.remoteControl | Show Claude Code Remote Control status badge | false |

Width Modes

Claude Code shares the statusline row with system notifications (e.g., "Update available!", "Context left until auto-compact...") that appear on the right side and can truncate your output. The flexMode setting controls how ccsl adapts, while flexPadding (default: 50) reserves space for these notifications:

| Mode | Behavior | |---|---| | full | Uses terminalWidth - flexPadding. Good default for most setups. | | full-minus-40 | Always reserves exactly 40 chars. Legacy mode for narrower notification reserve. | | full-until-compact | Uses flexPadding normally, increases reserve to max(flexPadding, 40) when context exceeds compactThreshold. |

ccsl also replaces spaces with non-breaking spaces and prefixes each line with an ANSI reset code to prevent Claude Code from trimming or dimming the output.

How It Works

flowchart TD
    A[Claude Code<br/>Status hook] --> B[stdin JSON]
    B --> C[ccsl]
    C --> D[Git info]
    C --> E[Transcript]
    C --> F[Config counts]
    C --> G[Usage API*]
    D --> H[Render badges]
    E --> H
    F --> H
    G --> H
    H --> I[stdout ANSI]

    style A fill:#2d4a2d
    style C fill:#38608c
    style I fill:#2d4a2d
    style G fill:#5f3a1c

ccsl is a StatusLine command — Claude Code pipes a JSON object to stdin on every status update. ccsl gathers additional context (git state, transcript history, config files, optionally the usage API), renders everything as ANSI-colored badges, and writes the result to stdout.

* Usage API is optional and requires features.usage: true in config.

Privacy

When features.usage is disabled (the default), ccsl reads only local files (git state, transcript, config). No network requests are made and no credentials are accessed.

When features.usage is enabled, ccsl reads your Claude OAuth token from ~/.claude/.credentials.json (or macOS Keychain) to query the Anthropic usage API. The token is used solely for this request and is never stored, logged, or transmitted elsewhere. Responses are cached locally for 3 minutes to minimize API calls. If the API is temporarily unavailable (e.g., rate-limited), the last successful value is shown with a ~ stale marker and retries are backed off to every 5 minutes.

See Also

• Remote Control — Claude Code's built-in feature for continuing local sessions from your phone, tablet, or browser. When enabled, ccsl shows the RC status as a badge (enable with features.remoteControl: true).

Acknowledgments

Based on work by Aaro Korhonen.

Contributing

Contributions are welcome! This is a small project — open an issue or submit a PR.

git clone https://github.com/laveez/ccsl.git
cd ccsl
npm install
npm run dev    # Watch mode — rebuilds on change

License

MIT