CLAUDE.md

Beacon Proxy

Transparent MCP audit proxy with intent-to-action tracing. Written in Go.

Build & Test

make build    # builds ./beacon-proxy
make test     # runs go test ./...
make lint     # runs go vet ./...

Architecture

• cmd/beacon-proxy/main.go — CLI entry point
• internal/proxy/ — core proxy (child process, stdin/stdout piping, JSON-RPC parsing)
• internal/audit/ — SQLite audit store (sessions, messages)
• internal/policy/ — policy engine (YAML rules, pause/approve flow)
• internal/web/ — dashboard web UI (embedded HTML, SSE live stream, API handlers)

Conventions

• Pure Go SQLite (modernc.org/sqlite) — no CGO dependency
• The proxy must never break the MCP protocol — if parsing fails, forward the raw message anyway
• Keep the spec (docs/beacon-proxy-spec.md) as the source of truth for data model and architecture
• Flush stdout after every proxied message (MCP clients expect low latency)
• Use log.Printf("beacon: ...") for proxy diagnostics on stderr

Dependencies

• Go 1.22+
• No external tools required beyond the Go toolchain