maxclaw: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

maxclaw is an ultra-lightweight personal AI assistant framework written in Go (~3,500 lines of core code). It provides core agent functionality including tool use, multi-channel chat integrations, and scheduled tasks.

• Language: Go 1.24+
• Module: github.com/Lichas/maxclaw
• Entry point: cmd/maxclaw/main.go
• Binary name: maxclaw

Operating Rules (Must Follow)

• Do not ask the user to verify. You are responsible for running tests, validating behavior, and reporting results.
• Always verify changes: run relevant tests or smoke checks, and report what passed/failed.
• After successfully completing a request with repository changes, run make build and then create a git commit for that request.
• If you fix a bug, append a concise entry to BUGFIX.md (what broke, root cause, fix, verification).
• If a request changes repository files, append a concise entry to CHANGELOG.md under ## [Unreleased] (what changed, key files, verification command).
• When adding features, update the docs (README / architecture) and validate the path end-to-end.
• Assume ownership of outcomes: if something could be flaky, add logging/guards and document the caveats.
• For runtime incidents, follow MAINTENANCE.md first (process/port/proxy/log order) before ad-hoc debugging.

Development Commands

Build & Run

make build          # Build to build/maxclaw
make install        # Install to GOPATH/bin
make run            # Build and run
make dev            # Hot reload (requires air)

Testing

make test           # Run all tests (go test -v ./...)
make coverage       # Generate coverage report
# OR
go test ./...       # Direct go test
go test -v ./...    # Verbose output
go test -cover ./... # With coverage

Code Quality

make fmt            # Format code (go fmt ./...)
make vet            # Run go vet
make lint           # Run fmt and vet
make mod            # Tidy and verify modules