ccstatuswidgets CLAUDE.md

ccstatuswidgets

What This Is

A Go binary (ccw) that provides a customizable, multi-line status line for Claude Code CLI. Reads JSON from stdin, runs widgets concurrently, renders colored ANSI output to stdout.

Repo: github.com/warunacds/ccstatuswidgets Module: github.com/warunacds/ccstatuswidgets Binary: ccw Go version: 1.21+ Dependencies: stdlib only (no external deps) License: MIT

Build & Test

go test ./...              # all tests
go test ./... -race        # with race detector
go vet ./...               # lint
go build -o ccw ./cmd/ccw  # build binary

Architecture

stdin JSON (from Claude Code)
    │
    ▼
┌─────────────────┐
│  cmd/ccw/main.go │ ─── CLI routing (init, doctor, configure, pomo, etc.)
└────────┬────────┘
         │ pipeline mode (no args)
         ▼
┌─────────────────┐     ┌──────────────────┐
│  config.Load()  │ ──▸ │  widget.Registry │ ◂── widgets.RegisterAll() + plugin.DiscoverPlugins()
└────────┬────────┘     └────────┬─────────┘
         │                       │
         ▼                       ▼
┌─────────────────────────────────────┐
│           engine.Run()              │
│  Launches all widgets concurrently  │
│  500ms timeout per widget           │
│  Cache fallback on timeout/error    │
└────────────────┬────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────┐
│         renderer.Render()           │
│  Per-widget styling (fg/bg/bold)    │
│  Custom separators / Powerline      │
│  ANSI color output                  │
└────────────────┬────────────────────┘
                 │
                 ▼
            stdout (colored text)

Package Map

Package	Responsibility	Key Types/Functions
cmd/ccw	Entry point, CLI routing	main(), runPipeline()
internal/protocol	Data types	StatusLineInput, WidgetOutput, ModelInfo, ContextInfo, RateLimits, CostInfo
internal/widget	Widget interface + registry	Widget interface (Name(), Render()), Registry (Register, Get, Names)
internal/widgets	23 built-in widget implementations	One file per widget, RegisterAll() in register.go
internal/engine	Concurrent executor	Engine.Run() — goroutines per widget, timeout, cache fallback
internal/renderer	ANSI output	Render(), WidgetStyle, FgCode/BgCode, Powerline mode
internal/cache	File-based TTL cache	Cache.Get(), Cache.Set() — atomic writes in ~/.ccstatuswidgets/cache/
internal/config	JSON config	Config struct, Load(), Save(), Default(), ConfigDir()
internal/httpclient	Shared HTTP client	Client.Get(), Client.GetWithHeaders() — 3s timeout
internal/plugin	External plugin runner	DiscoverPlugins(), ExternalWidget (implements Widget interface)
internal/cli	CLI commands	One file per command (init, doctor, configure, pomo, track, hn, plugin, list, add, remove, etc.)