Claude Code Custom Status Line

Example Status Line

A fully customized status line for Claude Code featuring:

🎨 Oh-my-posh powered theming with powerline separators
📊 Automatic token usage tracking (Code session + Pro web usage)
🔄 Advanced git status with staging, working changes, and upstream tracking
💾 Context window usage monitoring
⚡ Non-blocking background updates with JSON caching
🕐 Reset time countdowns for Pro usage limits

Installation

📖 Full Installation Guide: See docs/INSTALLATION.md for detailed installation instructions, troubleshooting, and platform-specific notes.

Quick Install (Recommended)

Install directly from GitHub without cloning:

curl -s https://raw.githubusercontent.com/ssenart/oh-my-claude/main/install.sh | bash

Custom installation directory:

curl -s https://raw.githubusercontent.com/ssenart/oh-my-claude/main/install.sh | bash -s -- -d ~/.custom/location

This will:

✅ Check for required dependencies (oh-my-posh, jq, git, npx)
✅ Download and install all scripts to ~/.claude/oh-my-claude/
✅ Backup and update your ~/.claude/settings.json
✅ Make all scripts executable

Pro usage tracking is automatic - no credentials needed!

Security Note: The installer only writes to your home directory and never requests sudo access. You can review the script before running: View install.sh

Alternative: Local Installation

For development or if you prefer to clone the repository:

git clone https://github.com/ssenart/oh-my-claude.git
cd oh-my-claude
bash local-install.sh

After Installation

You're ready to use Claude Code with your custom status line! The installation script already configured everything.

See docs/INSTALLATION.md for detailed installation guide.

Status Line Display

Your status line displays information-rich segments with powerline separators. See the image at the top for a visual example, or check docs/EXAMPLES.md for detailed breakdowns.

Segments (left to right)

#	Segment	Color	Description	Example
1	Path	Orange	Current directory	`oh-my-claude`
2	Git	Yellow*	Branch and status	`main`
3	Context	Teal	Window usage percentage	`󰍛 24.7%`
4	Code	Cyan	Session tokens (optional)	`# 14.3M`
5	Pro	Pink	5h/7d usage percentages (auto)	`󰓅 5h:90% 7d:27%`
6	Reset	Purple	Time until limits reset (auto)	`󰔛 5h:2h1min 7d:Thu09:59`
7	Model	Blue	Current AI model	`󰯉 Sonnet 4.5`

*Git segment color changes dynamically based on repository status (clean, dirty, ahead, behind, diverged)

Project Structure

oh-my-claude/
├── install.sh                    # Web installer (downloads from GitHub)
├── local-install.sh              # Local installer (for development)
├── run-tests.sh                  # Test runner (bats-core)
├── .gitattributes                # Force LF line endings (cross-platform)
├── src/                          # Source files
│   ├── common.sh                 # Shared utility functions
│   ├── statusline.sh             # Main status line script
│   ├── update-usage.sh           # Background usage updater
│   ├── fetch-code-usage.sh       # Code session token fetcher
│   ├── fetch-pro-usage.sh        # Pro usage fetcher
│   └── claude-statusline.omp.json # Oh-my-posh theme
├── tests/                        # Unit tests (bats-core)
│   ├── README.md                 # Testing guide
│   ├── common.bats               # Tests for common.sh
│   ├── statusline.bats           # Tests for statusline.sh
│   ├── fetch-code-usage.bats     # Tests for fetch-code-usage.sh
│   ├── fetch-pro-usage.bats      # Tests for fetch-pro-usage.sh
│   └── update-usage.bats         # Tests for update-usage.sh
├── docs/                         # Documentation
│   ├── PRO-USAGE-SETUP.md        # Pro usage setup guide
│   ├── STATUS_LINE_DOCUMENTATION.md # Technical reference
│   ├── STATUS_LINE_QUICK_REFERENCE.md # Common operations
│   ├── EXAMPLES.md               # Visual examples
│   ├── INDEX.md                  # Documentation index
│   └── DEVELOPER_GUIDE.md        # Developer guide & architecture
├── README.md                     # This file
├── CHANGELOG.md                  # Version history
└── VERSION                       # Current version number

Installed files (in ~/.claude/oh-my-claude/):

All scripts from src/ (including common.sh)
.usage_cache - Auto-generated cache (JSON format)

Common Tasks

Check Version

bash ~/.claude/oh-my-claude/statusline.sh --version
bash ~/.claude/oh-my-claude/update-usage.sh --version
bash ~/.claude/oh-my-claude/fetch-code-usage.sh --version
bash ~/.claude/oh-my-claude/fetch-pro-usage.sh --version

Update Usage Data

bash ~/.claude/oh-my-claude/update-usage.sh

View Current Usage Cache

cat ~/.claude/oh-my-claude/.usage_cache | jq .

Test Code Usage Fetcher

bash ~/.claude/oh-my-claude/fetch-code-usage.sh --debug

Test Pro Usage Fetcher

bash ~/.claude/oh-my-claude/fetch-pro-usage.sh --debug

Change How Often Usage Updates

Edit ~/.claude/oh-my-claude/statusline.sh and change:

cache_timeout=60  # Seconds (default: 60)

Test the Status Line

echo '{"model":{"display_name":"Test"},"workspace":{"current_dir":"'$PWD'"},"output_style":{"name":"markdown"},"context_window":{"current_usage":{"input_tokens":1000},"context_window_size":200000}}' | bash ~/.claude/oh-my-claude/statusline.sh

Customization

Colors: Edit ~/.claude/oh-my-claude/claude-statusline.omp.json → change background values
Icons: Edit ~/.claude/oh-my-claude/claude-statusline.omp.json → change template values
Segment order: Rearrange segments array in claude-statusline.omp.json
Add segments: See docs/STATUS_LINE_DOCUMENTATION.md for examples

Status Indicators

Symbol	Meaning
``	Path/directory indicator
``	Git upstream status indicator
``	Staged files in git
``	Modified files in git
`↑`	Commits ahead of remote
`↓`	Commits behind remote
`󰍛`	Context usage indicator (microchip)
`#`	Code token count indicator
`󰓅`	Pro usage gauge indicator
`󰔛`	Reset timer indicator
`󰯉`	Model indicator

How It Works

Claude Code calls statusline.sh on every refresh
statusline.sh:
- Extracts data (model, directory, context, git status)
- Reads usage cache (JSON format, instant, no blocking)
- If cache is old (>60s), triggers update-usage.sh in background
- Exports environment variables for oh-my-posh
- Passes data to oh-my-posh
oh-my-posh renders the colored powerline segments
update-usage.sh (background, every 60s):
- Calls fetch-code-usage.sh for session token count
- Calls fetch-pro-usage.sh for Pro usage percentages and reset times
- Writes JSON cache with timestamps

Performance

Status line render: ~50ms (fast!)
Usage update: ~2-5s (runs in background, doesn't block)
Cache: Updates every 60 seconds automatically

Optimization

To make usage updates faster, install ccusage globally:

npm install -g ccusage

Then edit update-usage.sh and replace npx ccusage with ccusage.

Dependencies

oh-my-posh: Already installed at /c/Program Files (x86)/oh-my-posh/bin/oh-my-posh
ccusage: Runs via npx (no global install needed)
jq: For JSON parsing (standard on Git Bash)
git: For git status detection

Troubleshooting

Usage not updating?

# Test ccusage manually
npx ccusage blocks --active --json

# Check cache
cat ~/.claude/.usage_cache

# Force update
bash ~/.claude/update-usage.sh

Git status not showing?

Only visible when inside a git repository
Navigate to a git repo and it will appear

Status line not appearing?

# Check settings
cat ~/.claude/settings.json

# Should contain:
# "statusLine": {
#   "type": "command",
#   "command": "bash C:/Users/steph/.claude/statusline.sh",
#   "padding": 0
# }

Documentation

Full docs: docs/STATUS_LINE_DOCUMENTATION.md - Complete technical reference
Quick ref: docs/STATUS_LINE_QUICK_REFERENCE.md - Common operations
Examples: docs/EXAMPLES.md - Visual examples of all states
Index: docs/INDEX.md - Documentation navigation guide
This file: README.md - Overview and getting started

Version Management

Checking Version

All scripts support the --version flag:

bash ~/.claude/oh-my-claude/statusline.sh --version

For Developers: Bumping Version

To update the project version, use the included helper script:

bash bump-version.sh