ccstatusline: Instructions file for Codex

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

ccstatusline is a customizable status line formatter for Claude Code CLI that displays model info, git branch, token usage, and other metrics. It functions as both:

1. A piped command processor for Claude Code status lines
2. An interactive TUI configuration tool when run without input

Development Commands

# Install dependencies
bun install

# Run in interactive TUI mode
bun run start

# Test with piped input (use [1m] suffix for 1M context models)
echo '{"model":{"id":"claude-sonnet-4-5-20250929[1m]"},"transcript_path":"test.jsonl"}' | bun run src/ccstatusline.ts

# Or use example payload
bun run example

# Build for npm distribution
bun run build   # Creates dist/ccstatusline.js with Node.js 14+ compatibility

# Run tests
bun test

# Run tests in watch mode
bun test --watch

# Lint and type check
bun run lint      # Runs TypeScript type checking and ESLint without modifying files

# Apply ESLint auto-fixes intentionally
bun run lint:fix

Architecture

The project has dual runtime compatibility - works with both Bun and Node.js:

Core Structure

• src/ccstatusline.ts: Main entry point that detects piped vs interactive mode
  • Piped mode: Parses JSON from stdin and renders formatted status line
  • Interactive mode: Launches React/Ink TUI for configuration

TUI Components (src/tui/)

• index.tsx: Main TUI entry point that handles React/Ink initialization
• App.tsx: Root component managing navigation and state
• components/: Modular UI components for different configuration screens
  • MainMenu, LineSelector, ItemsEditor, ColorMenu, GlobalOverridesMenu
  • PowerlineSetup, TerminalOptionsMenu, StatusLinePreview

Utilities (src/utils/)

• config.ts: Settings management
  • Loads from ~/.config/ccstatusline/settings.json
  • Handles migration from old settings format
  • Default configuration if no settings exist
• renderer.ts: Core rendering logic for status lines
  • Handles terminal width detection and truncation
  • Applies colors, padding, and separators
  • Manages flex separator expansion
• powerline.ts: Powerline font detection and installation
• claude-settings.ts: Integration with Claude Code settings.json
  • Respects CLAUDE_CONFIG_DIR environment variable with fallback to ~/.claude
  • Provides installation command constants (NPM, BUNX, self-managed)
  • Detects installation status and manages settings.json updates
  • Validates config directory paths with proper error handling
• colors.ts: Color definitions and ANSI code mapping
• model-context.ts: Model-to-context-window mapping
  • Maps model IDs to their context window sizes based on [1m] suffix
  • Sonnet 4.5 WITH [1m] suffix: 1M tokens (800k usable at 80%) - requires long context beta access
  • Sonnet 4.5 WITHOUT [1m] suffix: 200k tokens (160k usable at 80%)
  • Legacy models: 200k tokens (160k usable at 80%)