ccstatusline/CLAUDE.md

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 locally (TUI mode)
bun run src/ccstatusline.ts

# Test with piped input
echo '{"model":{"display_name":"Claude 3.5 Sonnet"},"transcript_path":"test.jsonl"}' | bun run src/ccstatusline.ts

# Build for npm distribution
bun run build   # Creates dist/ccstatusline.js

# Test npm package locally
npm link
echo '{"model":{"display_name":"Claude 3.5 Sonnet"},"transcript_path":"test.jsonl"}' | ccstatusline

Architecture

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

• 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

• src/tui.tsx: React-based terminal UI using Ink for configuration interface

  • Item management (add/remove/reorder status items)
  • Color customization for different elements

• src/config.ts: Settings management

  • Loads from ~/.config/ccstatusline/settings.json
  • Handles migration from old settings format
  • Default configuration if no settings exist

• npm publishing: Uses --packages=external to keep dependencies external for cross-platform compatibility

Key Implementation Details

• Cross-platform stdin reading: Code detects Bun vs Node.js environment and uses appropriate stdin API
• Token metrics: Parses Claude Code transcript files (JSONL format) to calculate token usage
• Git integration: Uses child_process.execSync to get current branch
• 80-char limit: Status line always formats to exactly 80 characters for Claude Code compatibility
• Flex separators: Special separator type that expands to fill available space

Bun Usage Preferences

Default to using Bun instead of Node.js.

• Use bun <file> instead of node <file> or ts-node <file>
• Use bun test instead of jest or vitest
• Use bun build <file.html|file.ts|file.css> instead of webpack or esbuild
• Use bun install instead of npm install or yarn install or pnpm install
• Use bun run <script> instead of npm run <script> or yarn run <script> or pnpm run <script>
• Bun automatically loads .env, so don't use dotenv.

APIs

• Bun.serve() supports WebSockets, HTTPS, and routes. Don't use express.
• bun:sqlite for SQLite. Don't use better-sqlite3.
• Bun.redis for Redis. Don't use ioredis.
• Bun.sql for Postgres. Don't use pg or postgres.js.
• WebSocket is built-in. Don't use ws.
• Prefer Bun.file over node:fs's readFile/writeFile
• Bun.$ls instead of execa.

Testing

Use bun test to run tests.

import { test, expect } from "bun:test";

test("hello world", () => {
  expect(1).toBe(1);
});