diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..b8fe03a
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,46 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+alerttonotify receives Alertmanager HTTP webhooks and forwards them as notifications via NATS to a dbus notify service. Written in Go (1.23.3).
+
+## Build & Development
+
+```bash
+# Build
+go build -v ./...
+
+# Lint (available in nix devshell)
+golangci-lint run
+
+# Enter dev environment (requires nix with flakes)
+nix develop
+
+# Build with nix
+nix build
+```
+
+No tests exist yet. The project uses direnv (`.envrc`) to auto-load the nix devshell.
+
+## Architecture
+
+**main.go** — Entry point. Reads config from environment variables, sets up NATS connection, creates the HTTP server, handles graceful shutdown on SIGINT.
+
+**server/server.go** — HTTP server with two routes:
+- `GET /` — health check
+- `POST /alert` — receives Alertmanager webhook payloads (`AlertMessage`/`Alert` structs), builds a summary, and publishes via `NotificationService`
+
+**server/notify.go** — `NotificationService` wraps a NATS connection. Serializes `BusNotification` (summary, body, timeout) to JSON and publishes to subject `home2rjusnet.notifications`. Uses NKey authentication.
+
+## Configuration
+
+All config is via environment variables:
+- `NATS_URL` (required) — NATS server URL
+- `NATS_NKEY` or `NATS_NKEY_FILE` (required) — NKey seed for NATS auth
+- `ALERTTONOTIFY_ADDR` (optional, default `:5001`) — HTTP listen address
+
+## Nix
+
+The flake builds with `buildGoModule`. The `vendorHash` in `flake.nix` must be updated when Go dependencies change.