ccstatusline

A customizable status line formatter for Claude Code CLI that displays model info, git branch, token usage, and other metrics in your terminal.

Features

• 📊 Real-time metrics - Display model name, git branch, token usage, session duration, and more
• 🎨 Fully customizable - Choose what to display and customize colors
• 📐 Multi-line support - Configure up to 3 status lines
• 🖥️ Interactive TUI - Built-in configuration interface using React/Ink
• 🚀 Cross-platform - Works with both Bun and Node.js
• 📏 Auto-width detection - Automatically adapts to terminal width with flex separators

Quick Start

No installation needed! Use directly with npx:

# Run the configuration TUI
npx ccstatusline@latest

Setup

Configure ccstatusline

Run the interactive configuration tool:

npx ccstatusline@latest

This launches a TUI where you can:

• Add/remove status line items
• Reorder items with arrow keys
• Customize colors for each element
• Preview your status line in real-time

Your settings are saved to ~/.config/ccstatusline/settings.json.

Usage

Once configured, ccstatusline automatically formats your Claude Code status line. The status line appears at the bottom of your terminal during Claude Code sessions.

Available Status Items

• Model Name - Shows the current Claude model (e.g., "Claude 3.5 Sonnet")
• Git Branch - Displays current git branch name
• Git Changes - Shows uncommitted insertions/deletions (e.g., "+42,-10")
• Session Clock - Shows elapsed time since session start (e.g., "2hr 15m")
• Tokens Input - Shows input tokens used
• Tokens Output - Shows output tokens used
• Tokens Cached - Shows cached tokens used
• Tokens Total - Shows total tokens used
• Context Length - Shows current context length in tokens
• Context Percentage - Shows percentage of context limit used
• Terminal Width - Shows detected terminal width (for debugging)
• Separator - Visual divider between items (|)
• Flex Separator - Expands to fill available space

Configuration File

The configuration file at ~/.config/ccstatusline/settings.json looks like:

{
  "lines": [
    [
      {
        "id": "1",
        "type": "model",
        "color": "cyan"
      },
      {
        "id": "2",
        "type": "separator"
      },
      {
        "id": "3",
        "type": "git-branch",
        "color": "magenta"
      },
      {
        "id": "4",
        "type": "separator"
      },
      {
        "id": "5",
        "type": "session-clock",
        "color": "blue"
      }
    ]
  ],
  "colors": {
    "model": "cyan",
    "gitBranch": "magenta",
    "separator": "dim"
  }
}

Color Options

Available colors:

• black, red, green, yellow, blue, magenta, cyan, white, gray
• brightBlack, brightRed, brightGreen, brightYellow, brightBlue, brightMagenta, brightCyan, brightWhite

Development

Prerequisites

• Bun
• Git

Setup

# Clone the repository
git clone https://github.com/yourusername/ccstatusline.git
cd ccstatusline

# Install dependencies
bun install

Development Commands

# Run in TUI mode (configuration)
bun run src/ccstatusline.ts

# Build for distribution
bun run build

Project Structure

ccstatusline/
├── src/
│   ├── ccstatusline.ts     # Main entry point
│   ├── tui.tsx             # React/Ink configuration UI
│   ├── config.ts           # Settings management
│   └── claude-settings.ts  # Claude Code settings integration
├── dist/                   # Built files (generated)
├── package.json
├── tsconfig.json
└── README.md

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT

Author

Matthew Breedlove

Acknowledgments

Built for use with Claude Code CLI by Anthropic.