halfmoon: Instructions file for Claude Code

CLAUDE.md — Halfmoon

Ultra-lightweight personal AI assistant in Go. Runs on $10 hardware, <10MB RAM. Pure Go (CGO_ENABLED=0).

Commands

# Build
make build                    # Build halfmoon binary
make build-launcher           # Build web launcher (TUI)

# Test
make test                     # Run Go tests (excludes web/) + web tests
go test ./pkg/agent/...       # Test single package
go test -run TestName ./pkg/  # Run specific test

# Lint & Format (requires golangci-lint v2 — config uses version: "2")
make lint                     # golangci-lint run (all linters)
make fmt                      # golangci-lint fmt (auto-format: gci, gofmt, gofumpt, golines)
make fix                      # Auto-fix lint issues
make vet                      # go vet

# Full check before PR
make check                    # deps + fmt + vet + test

Validation Before Committing

Run these in order before considering work complete:

1. Build: go build ./... — must compile with zero errors
2. Test: go test ./pkg/... -count=1 — all tests must pass
3. Lint: make lint — zero issues. CI runs golangci-lint v2.10.1 with gci (import ordering), golines (max 120 chars), and spancheck (span leak detection) among others. Fix issues with make fmt first, then address remaining lint errors manually.
4. Vet: make vet — zero issues

If make lint fails with "Can't read config", your local golangci-lint is v1.x — update to v2: curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b /usr/local/bin v2.10.1

Architecture

cmd/halfmoon/           → CLI entry (Cobra). 10 subcommands.
pkg/agent/              → Core agent loop. THE most important package.
  loop.go               → Main reasoning loop (runTurn, turnLoop at line 1690)
  instance.go           → AgentInstance struct — model, tools, sessions, config
  context.go            → System prompt builder (AGENT.md + SOUL.md + skills + memory)
  hooks.go              → BeforeLLM/AfterLLM/BeforeTool/AfterTool interceptors
  eventbus.go           → 19 event types, multi-subscriber broadcaster
  subturn.go            → Sub-agent spawning (async/sync)
  turn.go               → Turn state management, parent-child hierarchy
pkg/providers/          → LLM provider adapters. Factory pattern + fallback chains.
pkg/channels/           → Chat platforms. 15+ channels, all funnel through BaseChannel.
  base.go               → HandleMessage() — shared entry for all channels
  manager.go            → Message routing, outbound delivery
pkg/tools/              → Tool registry. Interface: Name/Description/Parameters/Execute.
  base.go               → Tool interface + ToolResult (ForLLM, ForUser, IsError)
  registry.go           → Map-based lookup, clone support for sub-agents
  http_request.go       → HTTP request tool. Domain allowlist, auth profiles, SSRF protection.
pkg/bus/                → Message bus. Decouples channels from agent.
pkg/config/             → Config loading. JSON config + .security.yml + env vars + file:// refs
pkg/cron/               → In-process cron scheduler. Single goroutine + timer.
pkg/heartbeat/          → Periodic agent nudge from HEARTBEAT.md
pkg/routing/            → 7-level priority cascade for agent selection
web/backend/            → Go web server (REST API + WebSocket)
web/frontend/           → React 19 + Vite + TypeScript + Jotai + TanStack Router