sox/CLAUDE.md

CLAUDE.md

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

What this is

Sox is a Campfire bot written in Go. It runs as an HTTP server (default port 4567, overridable via PORT env var) that receives webhook POST requests from Campfire and responds with HTML-formatted text.

Commands

make build      # builds binary to bin/sox
make test       # runs all tests with verbose output
go test -run TestSplitFirstWord ./...   # run a single test

The math command requires qalc (libqalculate) on PATH. Tests that need it skip automatically if it's absent.

Architecture

Plugin system (plugin.go): Each command is a struct implementing the Plugin interface (Name(), ShortHelp(), DetailedHelp(), Execute()). Plugins self-register via registerPlugin() called from init() in main.go. The global registry map (map[string]Plugin) routes commands by name.

Request handling (main.go): commandHandler decodes the Campfire JSON webhook into BotMessage, then executeCommand splits the plain-text body into command + arguments. If the command isn't recognized, it falls back to the user's last successfully used command (stored in userLastCommandType, a map[string]string keyed by username). The help command is excluded from last-command memory.

Adding a new command: Create a cmd_<name>.go file, implement the Plugin interface, and add registerPlugin(YourPlugin{}) to init() in main.go.

HTTP tracing (request_trace.go, cmd_trace.go): TraceRequest uses net/http/httptrace to instrument a GET request with a 3-second timeout and returns a RequestTrace struct with timestamps for each phase (DNS, connect, TLS, headers, first byte, last byte).