claude-status

A fast, lightweight status line for Claude Code CLI written in Go.

work | [Sonnet 4] | 📁 my-project | 🌿 main ±3 +42,-10 ✨2📝1 | ✅ | 📊 56.5%
📋 Tasks: 2 ready, 1 blocked. Next Up: Implement feature X

Features

• Fast - Single binary, ~10MB, sub-millisecond startup
• Smart Caching - Git info cached based on file modification times; no redundant git calls
• GitHub CI Status - Shows build status (✅ ❌ 🔄) for your current branch
• Git Diff Stats - Line additions/deletions and file change counts
• Task Tracking - Shows ready/blocked counts from supported task trackers
• Multi-Profile - Use --prefix to identify different Claude sessions
• Customizable - Full Go template support with ANSI colors
• Zero Config - Works out of the box with sensible defaults
• XDG Compliant - Config, cache, and data stored in standard locations

Installation

From Source

go install github.com/kostyay/claude-status/cmd/claude-status@latest

Manual Build

git clone https://github.com/kostyay/claude-status.git
cd claude-status
make build
# Binary is at ./claude-status

Quick Start

The easiest way to configure Claude Code is with the built-in install command:

./claude-status -install

This will:

1. Show a diff of the changes to ~/.claude/settings.json
2. Ask for confirmation before applying
3. Preserve any existing settings

Alternatively, manually add to your Claude Code settings (~/.claude/settings.json):

{
  "statusLine": {
    "type": "command",
    "command": "/path/to/claude-status",
    "padding": 0
  }
}

That's it! The status line will appear in your Claude Code sessions.

Multi-Profile Support

Use --prefix to identify different Claude Code sessions (e.g., work vs personal):

{
  "statusLine": {
    "type": "command",
    "command": "/path/to/claude-status --prefix work --prefix-color blue",
    "padding": 0
  }
}

Available colors: cyan (default), blue, green, yellow, red, magenta, gray

Custom Config Directory

If you use a custom Claude Code config directory, set CLAUDE_CONFIG_DIR:

CLAUDE_CONFIG_DIR=/custom/path ./claude-status -install

What It Shows

Component	Description	Example
Prefix	Optional profile identifier	work
Model	Current Claude model	[Sonnet 4]
Directory	Current working directory	📁 my-project
Git Branch	Current branch name	🌿 main
Git Status	Uncommitted changes count	±3
Git Diff	Line additions/deletions	+42,-10
Git Files	New/modified/deleted/unstaged files	✨2📝1🗑1⚡3
GitHub CI	Latest workflow run status	✅ ❌ 🔄
Pull Request	Open PR for the branch (clickable in supported terminals)	✅ #42
Context %	Usable context usage before auto-compact (color-coded)	📊 56.5%
Version	Claude Code version	v1.0.0
Tasks	Task tracking stats (if a supported task tracker is configured)	📋 Tasks: 2 ready, 1 blocked

Token Metrics (Available in Templates)

All values are raw numbers. Use fmtTokens and fmtPct template functions to format them.

Metric	Description	Example (with formatting)
TokensInput	Input tokens used	{{fmtTokens .TokensInput}} → 10.5k
TokensOutput	Output tokens generated	{{fmtTokens .TokensOutput}} → 5.2k
TokensCached	Cached tokens (read + creation)	{{fmtTokens .TokensCached}} → 35k
TokensTotal	Sum of all tokens	{{fmtTokens .TokensTotal}} → 50.7k
ContextLength	Current context window size	{{fmtTokens .ContextLength}} → 45.2k
ContextPctUse	Percentage of usable context (80% before auto-compact) - default	{{fmtPct .ContextPctUse}} → 56.5%
ContextPct	Percentage of max context used	{{fmtPct .ContextPct}} → 45.2%

GitHub CI Status Icons

Icon	Meaning
✅	Build succeeded
❌	Build failed
🔄	Build in progress
⚠️	Status unknown

PR Review State Icons

When Claude Code reports an open pull request for the current branch, claude-status renders a clickable <emoji> #<number> link (OSC 8, works in iTerm2, Kitty, WezTerm, and most modern terminals).

Icon	Review state
✅	Approved
⏳	Pending review
❌	Changes requested
📝	Draft
🔀	Unknown / no state

Task Tracking

If you use a supported task tracker (kt, tk, or Claude Code's built-in tasks), claude-status automatically detects it and shows task stats on a second line:

📋 Tasks: 2 ready, 1 blocked. Next Up: Implement feature X

• Ready - Tasks with no blockers that can be started
• Blocked - Tasks waiting on dependencies
• Next Up - Title of the first ready task

Configuration

Create ~/.config/claude-status/config.json:

{
  "template": "{{cyan}}[{{.Model}}]{{reset}} | {{blue}}📁 {{.Dir}}{{reset}}{{if .GitBranch}} | {{green}}🌿 {{.GitBranch}}{{if .GitStatus}} {{.GitStatus}}{{end}}{{reset}}{{end}}{{if .GitHubStatus}} | {{.GitHubStatus}}{{end}}",
  "github_workflow": "ci",
  "github_ttl": 60,
  "logging_enabled": false
}

Configuration Options

Option	Type	Default	Description
template	string	(see below)	Go template for status line
github_workflow	string	"build_and_test"	GitHub Actions workflow name to monitor
github_ttl	int	60	Seconds to cache GitHub status
tasks_ttl	int	5	Seconds to cache task stats
logging_enabled	bool	false	Enable status line logging
log_path	string	XDG data dir	Custom log file path

Default Template

The default template shows a complete status line with prefix support, git diff stats, clickable PR link, and a second line for task tracking (if a task tracker is configured):

{{if .Prefix}}{{.PrefixColor}}{{.Prefix}}{{reset}} | {{end}}{{cyan}}[{{.Model}}]{{reset}} | {{blue}}📁 {{.Dir}}{{reset}}{{if .GitBranch}} | {{green}}🌿 {{.GitBranch}}{{if .GitStatus}} {{.GitStatus}}{{end}}{{reset}}{{if or .GitAdditions .GitDeletions}} {{green}}{{fmtSigned .GitAdditions}}{{reset}},{{red}}-{{.GitDeletions}}{{reset}}{{end}}{{if or .GitNewFiles .GitModifiedFiles .GitDeletedFiles .GitUnstagedFiles}}{{if .GitNewFiles}} ✨{{.GitNewFiles}}{{end}}{{if .GitModifiedFiles}} 📝{{.GitModifiedFiles}}{{end}}{{if .GitDeletedFiles}} 🗑{{.GitDeletedFiles}}{{end}}{{if .GitUnstagedFiles}} ⚡{{.GitUnstagedFiles}}{{end}}{{end}}{{end}}{{if .GitHubStatus}} | {{.GitHubStatus}}{{end}}{{if .PRNumber}} | {{magenta}}{{link .PRURL (printf "%s #%d" (prEmoji .PRReviewState) .PRNumber)}}{{reset}}{{end}}{{if .ContextPctUse}} | {{ctxColor .ContextPctUse}}📊 {{fmtPct .ContextPctUse}}{{reset}}{{end}}{{if .Version}} | {{gray}}v{{.Version}}{{reset}}{{end}}{{if .TasksReady}}
{{yellow}}📋 {{.TaskProvider}}: {{.TasksReady}} ready{{reset}}{{if .TasksBlocked}}, {{red}}{{.TasksBlocked}} blocked{{reset}}{{end}}{{if .TasksNextTask}}. Next Up: {{.TasksNextTask}}{{end}}{{end}}

Features:

• Prefix - Optional profile identifier (via --prefix flag)
• Context percentage - Color-coded (green/yellow/red) based on usage
• Git diff stats - Shows additions, deletions, and file changes
• Pull request - Clickable PR number with review-state emoji
• Task tracking - Second line with task stats (if a tracker is available)

Template Reference

Available Fields

All values are raw numbers. Use template functions (fmtTokens, fmtPct, fmtSigned) for formatting.

Field	Type	Description
.Prefix	string	Profile prefix (from --prefix flag)
.PrefixColor	string	ANSI color code for prefix (from --prefix-color)
.Model	string	Model display name (e.g., "Claude", "Sonnet 4")
.Dir	string	Current directory basename
.GitBranch	string	Current git branch (empty if not in repo)
.GitStatus	string	Change indicator like "±3" (empty if clean)
.GitAdditions	int	Line additions count
.GitDeletions	int	Line deletions count
.GitNewFiles	int	New files count
.GitModifiedFiles	int	Modified files count
.GitDeletedFiles	int	Deleted files count
.GitUnstagedFiles	int	Unstaged files count
.GitHubStatus	string	CI status emoji (empty if unavailable)
.Version	string	Claude Code version
.TokensInput	int64	Input tokens
.TokensOutput	int64	Output tokens
.TokensCached	int64	Cached tokens
.TokensTotal	int64	Total tokens
.ContextLength	int64	Context length
.ContextPct	float64	Context percentage of max tokens (0-100)
.ContextPctUse	float64	Usable context percentage (0-100) - used in default template
.ContextWindowSize	int64	Max context window in tokens (200k or 1M)
.CostUSD	float64	Session cost in USD (from Claude Code stdin)
.DurationMS	int64	Total wall-clock session duration (ms)
.APIDurationMS	int64	Total API response time (ms)
.CostLinesAdded	int	Lines added across session
.CostLinesRemoved	int	Lines removed across session
.TaskProvider	string	Provider name ("claude", "kt", or "tk")
.TaskListID	string	Claude Code task list ID (when CLAUDE_CODE_TASK_LIST_ID is set)
.TasksTotal	int	Total issues count
.TasksOpen	int	Open issues count
.TasksReady	int	Ready issues count
.TasksInProgress	int	In-progress count
.TasksBlocked	int	Blocked count
.TasksNextTask	string	Title of next ready task (empty if none)
.HasTasks	bool	Whether a task tracker is available

Workspace & session metadata (from Claude Code stdin)

Field	Type	Description
.ProjectDir	string	Directory where Claude Code was launched (may differ from .Dir)
.AddedDirs	[]string	Extra dirs added via /add-dir
.GitWorktree	string	Git worktree name when inside a linked worktree
.RepoHost	string	Origin remote host (e.g., "github.com")
.RepoOwner	string	Origin remote owner
.RepoName	string	Origin remote repo name
.SessionName	string	Custom session name from --name or /rename
.OutputStyle	string	Active output style name
.Exceeds200kTokens	bool	Whether the last response exceeds 200k tokens
.EffortLevel	string	Reasoning effort (low/medium/high/xhigh/max)
.ThinkingEnabled	bool	Whether extended thinking is enabled
.VimMode	string	Vim mode (NORMAL/INSERT/VISUAL/VISUAL LINE)
.AgentName	string	Agent name when running with --agent

Rate limits (Pro/Max accounts)

Field	Type	Description
.RateLimitFiveHourPct	float64	5-hour window used percentage
.RateLimitFiveHourResetsAt	int64	5-hour window reset (unix epoch)
.RateLimitSevenDayPct	float64	7-day window used percentage
.RateLimitSevenDayResetsAt	int64	7-day window reset (unix epoch)

Pull request (when an open PR exists for the branch)

Field	Type	Description
.PRNumber	int	PR number (0 when absent)
.PRURL	string	PR URL
.PRReviewState	string	approved/pending/changes_requested/draft

Worktree session (--worktree)

Field	Type	Description
.WorktreeName	string	Active worktree name
.WorktreePath	string	Worktree directory path
.WorktreeBranch	string	Worktree branch
.WorktreeOriginalCwd	string	Directory before entering the worktree
.WorktreeOriginalBranch	string	Branch checked out before the worktree

Template Functions

Function	Description	Example
{{fmtTokens .TokensInput}}	Format token count (e.g., 10500 → "10.5k")	{{fmtTokens .TokensTotal}}
{{fmtPct .ContextPctUse}}	Format percentage (e.g., 45.2 → "45.2%")	{{fmtPct .ContextPct}}
{{fmtSigned .GitAdditions}}	Format with +/- prefix (e.g., 42 → "+42")	{{fmtSigned .GitAdditions}}
{{fmtCost .CostUSD}}	Format USD amount (e.g., 0.01234 → "$0.01")	{{fmtCost .CostUSD}}
{{fmtDuration .DurationMS}}	Format milliseconds (e.g., 125000 → "2m 5s")	{{fmtDuration .DurationMS}}
{{link .PRURL "text"}}	Wrap text in an OSC 8 clickable hyperlink	{{link .PRURL .PRNumber}}
{{prEmoji .PRReviewState}}	Map PR review state to an emoji (✅/⏳/❌/📝/🔀)	{{prEmoji .PRReviewState}}

Color Functions

Function	Description
{{cyan}}	Cyan color
{{blue}}	Blue color
{{green}}	Green color
{{yellow}}	Yellow color
{{red}}	Red color
{{magenta}}	Magenta color
{{gray}}	Gray color
{{bold}}	Bold text
{{reset}}	Reset formatting
{{ctxColor .ContextPctUse}}	Dynamic color based on usable context: green (<50%), yellow (50-80%), red (>80%)

Example Templates

Minimal:

{{.Model}} {{.Dir}}{{if .GitBranch}} ({{.GitBranch}}){{end}}

Sonnet 4 my-project (main)

With colors, no emojis:

{{cyan}}{{.Model}}{{reset}} {{blue}}{{.Dir}}{{reset}}{{if .GitBranch}} {{green}}{{.GitBranch}}{{reset}}{{if .GitStatus}} {{yellow}}{{.GitStatus}}{{reset}}{{end}}{{end}}

Sonnet 4 my-project main ±3

Branch-focused:

{{if .GitBranch}}{{green}}{{.GitBranch}}{{reset}}{{if .GitStatus}} {{red}}{{.GitStatus}}{{reset}}{{end}} {{.GitHubStatus}}{{else}}{{gray}}(no git){{reset}}{{end}}

feature-branch ±5 ✅

With full token metrics:

{{cyan}}[{{.Model}}]{{reset}} | {{blue}}📁 {{.Dir}}{{reset}}{{if .GitBranch}} | {{green}}🌿 {{.GitBranch}}{{if .GitStatus}} {{.GitStatus}}{{end}}{{reset}}{{end}}{{if .TokensTotal}} | {{gray}}📈 In:{{fmtTokens .TokensInput}} Out:{{fmtTokens .TokensOutput}} Cache:{{fmtTokens .TokensCached}}{{reset}}{{end}}{{if .ContextPctUse}} | {{ctxColor .ContextPctUse}}📊 {{fmtPct .ContextPctUse}}{{reset}}{{end}}

[Sonnet 4] | 📁 my-project | 🌿 main ±3 | 📈 In:10.5k Out:5.2k Cache:35k | 📊 56.5%

Context-focused (shows usable context percentage):

{{cyan}}[{{.Model}}]{{reset}} | {{.Dir}}{{if .ContextPctUse}} | {{ctxColor .ContextPctUse}}Ctx: {{fmtTokens .ContextLength}} ({{fmtPct .ContextPctUse}}){{reset}}{{end}}

[Sonnet 4] | my-project | Ctx: 45.2k (56.5%)

With git diff stats:

{{cyan}}[{{.Model}}]{{reset}} | {{blue}}📁 {{.Dir}}{{reset}}{{if .GitBranch}} | {{green}}🌿 {{.GitBranch}}{{reset}}{{if or .GitAdditions .GitDeletions}} {{green}}{{fmtSigned .GitAdditions}}{{reset}},{{red}}-{{.GitDeletions}}{{reset}}{{end}}{{end}}

[Sonnet 4] | 📁 my-project | 🌿 main +42,-10

With clickable PR link:

{{cyan}}[{{.Model}}]{{reset}} | {{blue}}📁 {{.Dir}}{{reset}}{{if .PRNumber}} | {{magenta}}{{link .PRURL (printf "%s #%d" (prEmoji .PRReviewState) .PRNumber)}}{{reset}}{{end}}

[Sonnet 4] | 📁 my-project | ✅ #42

Task-focused:

{{cyan}}[{{.Model}}]{{reset}} | {{blue}}📁 {{.Dir}}{{reset}}{{if .TasksReady}} | {{yellow}}📋 {{.TasksReady}} ready{{reset}}{{if .TasksBlocked}}, {{red}}{{.TasksBlocked}} blocked{{reset}}{{end}}{{end}}

[Sonnet 4] | 📁 my-project | 📋 2 ready, 1 blocked

GitHub Integration

claude-status shows CI/CD build status for GitHub repositories. It requires the GitHub CLI (gh) to be installed and authenticated.

Setup

1. Install GitHub CLI: https://cli.github.com/
2. Authenticate: gh auth login
3. Set workflow name in config (defaults to build_and_test)

How It Works

• Detects GitHub repos from git remote URL
• Fetches latest workflow run status via GitHub API
• Caches results based on TTL and git ref changes
• Uses gh auth token for authentication (no token config needed)

Supported Workflow Matching

The github_workflow config matches by:

• Workflow name (e.g., "CI")
• Workflow filename without extension (e.g., "ci" matches ci.yml)

Caching

claude-status uses smart caching to minimize git and API calls:

Data	Invalidation Strategy
Git branch	.git/HEAD file modification time
Git status	.git/index file modification time
GitHub status	TTL-based (default 60s) + ref file mtime

Cache location: ~/.cache/claude-status/cache.json

File Locations

Following XDG Base Directory Specification:

Purpose	Path
Config	~/.config/claude-status/config.json
Cache	~/.cache/claude-status/cache.json
Logs	~/.local/share/claude-status/status_line.json

Development

Prerequisites

• Go 1.25+
• golangci-lint (for linting)

Commands

make lint    # Run linter
make test    # Run tests with coverage
make build   # Build binary
make clean   # Remove build artifacts
make all     # lint + test + build

Running Tests

go test -v ./...

Project Structure

├── cmd/claude-status/    # Main entry point
├── internal/
│   ├── cache/            # File-based caching
│   ├── config/           # Configuration loading
│   ├── git/              # Git operations
│   ├── github/           # GitHub API client
│   ├── install/          # -install command logic
│   ├── status/           # Status data builder
│   ├── template/         # Template rendering
│   └── tokens/           # Token metrics parsing
├── testdata/             # Test fixtures
└── integration_test.go   # Integration tests

Troubleshooting

Status line not appearing

1. Check Claude Code settings has correct path
2. Verify binary is executable: chmod +x claude-status
3. Test manually: echo '{"model":{"display_name":"Test"},"workspace":{"current_dir":"/tmp"}}' | claude-status

GitHub status not showing

1. Ensure gh CLI is installed and authenticated
2. Check workflow name matches your .github/workflows/*.yml
3. Verify you're in a GitHub repository

Errors logged to stderr

claude-status logs errors to stderr but still outputs a fallback status line. Check stderr for debugging:

echo '{}' | claude-status 2>&1

Comparison with ccstatusline

Feature	claude-status	ccstatusline
Language	Go	TypeScript/Node.js
Binary size	~10MB	Requires Node.js runtime
Startup time	<1ms	~100ms
Configuration	JSON file	Interactive TUI
Widgets	Template-based	Widget-based
Token metrics	✅ Full support	✅ Full support
Context tracking	✅ Model-aware (1M/200k)	✅ Model-aware
Git diff stats	✅ Additions/deletions/files	❌
Task tracking	✅ kt/tk/Claude tasks	❌
Multi-profile	✅ --prefix flag	❌
Powerline fonts	Via template	Built-in support

claude-status prioritizes speed and simplicity. If you need more widgets and interactive configuration, check out ccstatusline.

License

MIT License - see LICENSE for details.

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Run make all to ensure tests pass
4. Submit a pull request

Credits

Inspired by ccstatusline by sirmalloc.