litestream/AGENTS.md

AGENTS.md - Litestream AI Agent Guide

Litestream is a disaster recovery tool for SQLite that runs as a background process, monitors the WAL, converts changes to immutable LTX files, and replicates them to cloud storage. It uses modernc.org/sqlite (pure Go, no CGO required).

Before You Start

1. Read AI_PR_GUIDE.md for contribution requirements
2. Check CONTRIBUTING.md for what we accept (bug fixes welcome, features need discussion)
3. Review recent PRs for current patterns

Critical Rules

• Lock page at 1GB: SQLite reserves page at 0x40000000. Always skip it. See docs/SQLITE_INTERNALS.md
• LTX files are immutable: Never modify after creation. See docs/LTX_FORMAT.md
• Single replica per database: Each DB replicates to exactly one destination
• Use litestream ltx: Not litestream wal (deprecated)

Layer Boundaries

Layer	File	Responsibility
DB	db.go	Database state, restoration, WAL monitoring
Replica	replica.go	Replication mechanics only
Storage	**/replica_client.go	Backend implementations

Database state logic belongs in DB layer, not Replica layer.

Quick Reference

Build:

go build -o bin/litestream ./cmd/litestream
go test -race -v ./...

Code quality:

pre-commit run --all-files

Documentation

Document	When to Read
docs/PATTERNS.md	Code patterns and anti-patterns
docs/ARCHITECTURE.md	Deep component details
docs/SQLITE_INTERNALS.md	WAL format, lock page
docs/LTX_FORMAT.md	Replication format
docs/TESTING_GUIDE.md	Test strategies
docs/REPLICA_CLIENT_GUIDE.md	Adding storage backends

Checklist

Before submitting changes:

• Read relevant docs above
• Follow patterns in docs/PATTERNS.md
• Test with race detector (go test -race)
• Run pre-commit run --all-files
• For page iteration: test with >1GB databases
• Show investigation evidence in PR (see AI_PR_GUIDE.md)