diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..2f54c9d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,33 @@
+# Agent Guidelines for my-log
+
+## Build/Test/Lint Commands
+- Build: `make build` or `go build -o my-log`
+- Test all: `make test` (runs fmt + test with race + coverage)
+- Test single: `go test ./path/to/package -run TestName`
+- Format: `make fmt` or `go fmt ./...`
+- Coverage report: `make report` (generates cover.html)
+
+## Code Style
+- **Module**: `codeberg.org/danjones000/my-log`
+- **Go version**: 1.21.5
+- **Imports**: Standard library first, then external packages, then local packages. Use short aliases for common imports (e.g., `fp` for `path/filepath`, `mapst` for `mitchellh/mapstructure`)
+- **Formatting**: Always run `go fmt` before commits (included in test target)
+- **Types**: Use explicit types (e.g., `int64`, `float64`). Convert numbers appropriately when unmarshaling JSON
+- **Naming**: PascalCase for exported, camelCase for unexported. Use descriptive names
+- **Error handling**: Return wrapped errors with context. Define custom errors in models/errors.go. Use `ErrorIs` for error checking
+- **Testing**: Use testify/assert. Table-driven tests with helper functions. Test both marshal/unmarshal for encoding types
+- **Concurrency**: Use channels and goroutines with WaitGroups for parallel processing (see entry.go patterns)
+- **Comments**: Include license header on cmd files. Document exported functions and types
+
+## Git Commit Guidelines
+- **Format**: Prepend commit messages with a gitmoji emoji (see https://gitmoji.dev)
+- **Style**: Write detailed commit messages that explain what changed and why
+- **Examples**: `✨ Add JSON export functionality for log entries`, `🐛 Fix date parsing for RFC3339 timestamps`, `📝 Update README with configuration examples`
+
+## Project Structure
+- `cmd/`: Cobra commands (root, drop, config)
+- `models/`: Core types (Entry, Log, Meta) with marshal/unmarshal implementations
+- `config/`: TOML-based configuration with env overrides
+- `formatters/`: Output formatters (plain, json, null)
+- `files/`: File operations (append)
+- `tools/`: Utilities (date parsing, string parsing, write buffers)