cosmobar: Instructions file for Claude Code

CLAUDE.md

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

What this is

cosmobar is a single static Go binary that renders the Claude Code status line. Claude Code invokes it once per refresh, piping a session JSON blob to stdin; cosmobar prints one-or-more terminal rows to stdout. No runtime deps, no jq, no Nerd Font — the only module dependency is BurntSushi/toml.

Commands

make build                   # go build -o ./bin/cosmobar .
make test                    # go test ./...
make fmt                     # go fmt ./...
go test ./internal/render    # test one package
go test ./internal/segments -run TestCatalogMatchesRegistry  # one test
go vet ./...                 # must pass; CI runs it
go run . preview --cols 80   # fast visual loop without building
make dev                     # build + wire ./testsettings/.claude/settings.json for live testing

Never point the Claude Code statusLine command at go run . — it recompiles every refresh. Always use a built binary.

Architecture

Render pipeline (the spine). internal/cli/cmd_print.go:renderFromJSON is the testable core: it parses stdin (session.Parse), loads TOML config (config.Load/config.DefaultPath), detects the terminal render.Profile, does one git call (cached per session ~1s in the OS temp dir via git.Lookup; everything else comes from the stdin JSON), and hands everything to statusline.Render as a fully-injected statusline.Input (Git, Cols, Profile, Now are all passed in, so the render is deterministic and unit-testable). cosmobar preview (internal/cli/cmd_preview.go) reuses this exact same pipeline with mocked session/git data — preview output is guaranteed to match the live line.

Segments are a self-registering plugin registry. Each segment lives in internal/segments/<name>.go, implements Renderer (Name() + Render(ctx *Context) (Segment, bool) where ok=false hides it), and calls register(...) in an init(). statusline.Render walks config.Order, looks each name up via segments.Get, and collects the shown segments. To add a segment: create the file, register it, add a matching entry to the catalog in catalog.go, and add a table test.