pulseline

cc-pulseline

A multi-line statusline for Claude Code that shows context usage, cost tracking, active tools, running agents, and todo progress — updated live as you work.

What You'll See

Core Metrics — identity (L1) and budget (L3) always visible; config counts (L2) opt-in via [segments.config] enabled

Context Alert — CTX ≥70% turns red

Cost Alert — Burn rate >$50/h turns magenta

Tool Tracking — Running tools with targets + completed counts (noise-filtered, multi-line wrapping)

Agent Tracking — Running + completed agents on L5+

Todo Tracking — Task progress

Features

• Multi-line metrics dashboard — Identity, config counts, budget, quota, and live activity (layouts from flat to label-value ledger — see docs/layouts.md for the catalog)
• Incremental transcript parsing — Seek-based JSONL parsing with per-session offsets
• Deep observability — Active tools with targets, agent status, todo tracking
• Session-aware — Concurrent Claude Code sessions tracked independently
• Adaptive rendering — Width degradation for narrow terminals
• Built-in themes — ThemePalette system with custom themes, per-color TOML overrides, and --preview (see src/themes/ for the full set)
• Minimal dependencies — 3 runtime crates (serde, serde_json, toml)
• Configurable — TOML config with per-project overrides and segment toggles

Quickstart

1. Install

# npm (recommended — works on macOS, Linux, Windows)
npm install -g @cc-pulseline/cc-pulseline

# From source
cargo install cc-pulseline

# Or clone and build
git clone https://github.com/GregoryHo/cc-pulseline.git
cd cc-pulseline && ./scripts/install.sh

2. Configure Claude Code

Add to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/pulseline/cc-pulseline"
  }
}

3. Done

Start a Claude Code session — the statusline appears automatically.

Installation Methods

Method	Command	Best For
npm	npm i -g @cc-pulseline/cc-pulseline	Claude Code users
cargo-binstall	cargo binstall cc-pulseline	Rust devs (prebuilt)
cargo install	cargo install cc-pulseline	Rust devs (from source)
install.sh	./scripts/install.sh	Local clone

Configuration

cc-pulseline uses TOML configuration with two scopes:

• User: ~/.claude/pulseline/config.toml
• Project: {project}/.claude/pulseline.toml (overrides user)

cc-pulseline --init              # Create user config
cc-pulseline --init --project    # Create project config
cc-pulseline --check             # Validate configs
cc-pulseline --print             # Show effective merged config

Example Config

[display]
theme = "tokyo-night"   # tokyo-night | echo-sub-zero | titanium-precision | ...
# variant = "dark"      # dark | light (overrides theme default)
icons = true            # nerd font icons vs ascii

[segments.identity]     # Line 1 — model, style, version, project, git
show_model = true
show_style = true
show_version = true
show_project = true
show_git = true

[segments.config]       # Line 2 — CLAUDE.md, rules, memories, hooks, MCPs, skills, plugins, duration
enabled = true          # L2 row is opt-in (off by default)
show_claude_md = true
show_rules = true
show_memory = true
show_hooks = true
show_mcp = true
show_skills = true
show_plugins = true
show_duration = true

[segments.budget]       # Line 3 — context, tokens, cost
show_context = true
show_tokens = true
show_cost = true

[segments.tools]
enabled = true
max_lines = 2           # max running tools shown
max_completed = 4       # max completed tool counts
max_completed_lines = 1 # max rows of completed tools (overflow folds into a ` +N` tail)

[segments.agents]
enabled = true
max_lines = 2

[segments.todo]
enabled = true
max_lines = 2

Layouts & Visual Composition