medusa: Instructions file for Claude Code

CLAUDE.md

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

Definition of done

Before declaring any Go change complete:

1. make fmt — formats with gofmt + goimports.
2. golangci-lint run — must exit 0. Run on just the touched package for speed (e.g. golangci-lint run ./internal/app/...).
3. No .go file may exceed 500 lines. make lint enforces this; if you hit it, split by concern into sibling files in the same package rather than inflating a single file.
4. Tests pass for the touched package.
5. At the end of development, run make lint — it mirrors CI by running go test -race -v ./... followed by golangci-lint and the 500-line check. The race detector catches issues plain go test misses (e.g. value-receiver methods like Workspace.Root() copy the whole struct, so a goroutine calling them races with any concurrent field write). make test-race is the same race run without lint, handy for reproducing a CI failure in isolation.

Don't batch these up for a later cleanup pass — fix as you go.

Common commands

make build            # builds `medusa` and `medusa-hook-emit`
make run              # build + run the TUI
make dev              # hot-reload via air
make test             # go test -v ./...
make test-race        # go test -race -v ./... (mirrors CI; slower)
make lint             # full gate: test-race + golangci-lint + 500-line check
make fmt              # gofmt + goimports
make bench            # compositor render benchmarks

Run a single test:

go test ./internal/app -run TestCopyIgnoredFiles -v

Headless render/perf harness (no human, no terminal):

go run ./cmd/medusa-harness -mode monitor -frames 5 -warmup 1
go run ./cmd/medusa-harness -mode center  -frames 5 -warmup 1
go run ./cmd/medusa-harness -mode sidebar -frames 5 -warmup 1

release-check runs tests + all three harness modes — use it to validate UI-adjacent changes without a real terminal.