# Repository: benbjohnson/litestream
# Stars: 13459

## .cursorrules

AGENTS.md

## CLAUDE.md

# CLAUDE.md - Claude Code Configuration

Claude-specific optimizations for Litestream. See [AGENTS.md](AGENTS.md) for project documentation.

## Critical Coding Rules

- **Always return errors, never log and continue.** The only exception is DEBUG logging for best-effort operations that don't affect correctness. This is the #1 cause of PR review feedback. See [docs/PATTERNS.md](docs/PATTERNS.md#error-handling) for the full decision framework.

## Context Window

With Claude's large context window, load documentation as needed:

- Start with [AGENTS.md](AGENTS.md) for overview and checklist
- Load [docs/PATTERNS.md](docs/PATTERNS.md) when writing code
- Load [docs/SQLITE_INTERNALS.md](docs/SQLITE_INTERNALS.md) for WAL/page work
- Load [docs/PROVIDER_COMPATIBILITY.md](docs/PROVIDER_COMPATIBILITY.md) for storage backend configs

## Claude-Specific Resources

### Specialized Agents (.claude/agents/)

- `sqlite-expert.md` - SQLite WAL and page management
- `replica-client-developer.md` - Storage backend implementation
- `ltx-compaction-specialist.md` - LTX format and compaction
- `test-engineer.md` - Testing strategies
- `performance-optimizer.md` - Performance optimization

### Commands (.claude/commands/)

- `/analyze-ltx` - Analyze LTX file structure
- `/debug-ipc` - Debug IPC Unix socket issues
- `/debug-wal` - Debug WAL replication issues
- `/test-compaction` - Test compaction scenarios
- `/trace-replication` - Trace replication flow
- `/validate-replica` - Validate replica client
- `/add-storage-backend` - Create new storage backend
- `/fix-common-issues` - Diagnose common problems
- `/run-comprehensive-tests` - Execute full test suite

## Quick Commands

```bash
go build -o bin/litestream ./cmd/litestream
go test -race -v ./...
pre-commit run --all-files
```


## README.md

Litestream
![GitHub release (latest by date)](https://img.shields.io/github/v/release/benbjohnson/litestream)
![Status](https://img.shields.io/badge/status-beta-blue)
![GitHub](https://img.shields.io/github/license/benbjohnson/litestream)
[![Docker Pulls](https://img.shields.io/docker/pulls/litestream/litestream.svg?maxAge=604800)](https://hub.docker.com/r/litestream/litestream/)
==========

Litestream is a standalone disaster recovery tool for SQLite. It runs as a
background process and safely replicates changes incrementally to another file
or S3. Litestream only communicates with SQLite through the SQLite API so it
will not corrupt your database.

If you need support or have ideas for improving Litestream, please visit
[GitHub Issues](https://github.com/benbjohnson/litestream/issues).
Please visit the [Litestream web site](https://litestream.io) for installation
instructions and documentation.

If you find this project interesting, please consider starring the project on
GitHub.

Contributing
------------

We welcome bug reports, fixes, and patches! Please see our [Contributing Guide](CONTRIBUTING.md) for details on how to contribute.

Acknowledgements
----------------

I want to give special thanks to individuals who invest much of their time and
energy into the project to help make it better:

- Thanks to [Cory LaNou](https://twitter.com/corylanou) for giving early feedback and testing when Litestream was still pre-release.
- Thanks to [Michael Lynch](https://github.com/mtlynch) for digging into issues and contributing to the documentation.
- Thanks to [Kurt Mackey](https://twitter.com/mrkurt) for feedback and testing.
- Thanks to [Sam Weston](https://twitter.com/cablespaghetti) for figuring out how to run Litestream on Kubernetes and writing up the docs for it.
- Thanks to [Rafael](https://github.com/netstx) & [Jungle Boogie](https://github.com/jungle-boogie) for helping to get OpenBSD release builds working.
- Thanks to [Simon Gottschlag](https://github.com/simongottschlag), [Marin](https://github.com/supermarin),[Victor Björklund](https://github.com/victorbjorklund), [Jonathan Beri](https://twitter.com/beriberikix) [Yuri](https://github.com/yurivish), [Nathan Probst](https://github.com/nprbst), [Yann Coleu](https://github.com/yanc0), and [Nicholas Grilly](https://twitter.com/ngrilly) for frequent feedback, testing, & support.

Huge thanks to fly.io for their support and for contributing credits for testing and development!