{"owner":"atuinsh","repo":"atuin","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"files":{"AGENTS.md":"# Atuin\n\nShell history tool. Replaces your shell's built-in history with a SQLite database, adds context (cwd, exit code, duration, hostname), and optionally syncs across machines with end-to-end encryption.\n\n## Workspace crates\n\n```\natuin                  CLI binary + TUI (clap, ratatui, crossterm)\natuin-client           Client library: local DB, encryption, sync, settings\natuin-common           Shared types, API models, utils\natuin-daemon           Background gRPC daemon (tonic) for shell hooks\natuin-dotfiles         Alias/var sync via record store\natuin-history          Sorting algorithms, stats\natuin-kv               Key-value store (synced)\natuin-scripts          Script management (minijinja)\natuin-server           HTTP sync server (axum) - lib + standalone binary\natuin-server-database  Database trait for server\natuin-server-postgres  Postgres implementation (sqlx)\natuin-server-sqlite    SQLite implementation (sqlx)\n```\n\n## Two sync protocols\n\n- **V1 (legacy)**: Syncs history entries directly. Being phased out. Toggleable via `sync_v1_enabled`.\n- **V2 (current)**: Record store abstraction. All data types (history, KV, aliases, vars, scripts) share the same sync infrastructure using tagged records. Envelope-encrypted with PASETO V4 and per-record CEKs.\n\n## Encryption\n\n- **V1**: XSalsa20Poly1305 (secretbox). Key at `~/.local/share/atuin/key`.\n- **V2**: PASETO V4 Local (XChaCha20-Poly1305 + Blake2b). Envelope encryption: each record gets a random CEK wrapped with the master key. Record metadata (id, idx, version, tag, host) is authenticated as implicit assertions.\n\n## Databases\n\n- **Client**: SQLite everywhere. Separate DBs for history, record store, KV, scripts. All use sqlx + WAL mode.\n- **Server**: Postgres (primary) or SQLite. Auto-detected from URI prefix.\n- Migrations live alongside each crate. Never modify existing migrations, only add new ones.\n\n## Hot paths\n\n`history start`, `history end`, and `init` skip database initialization for latency. Don't add DB calls to these without good reason.\n\n## Conventions\n\n- Rust 2024 edition, toolchain 1.97.0.\n- Errors: `eyre::Result` in binaries, `thiserror` for typed errors in libraries.\n- Derive boilerplate: `derive_more` (workspace dep) for `Display`, `From`, `Into`, `AsRef`, `Deref`, `Debug` on newtypes and simple enums. Prefer `derive_more` over manual `impl` when the formatting/conversion is a straight delegation. Use `thiserror` (not `derive_more`) for error types. Use `#[as_ref(str)]` on string newtypes for `AsRef<str>`.\n- Async: tokio. Client uses `current_thread`; server uses `multi_thread`.\n- `#![deny(unsafe_code)]` on client/common, `#![forbid(unsafe_code)]` on server.\n- Clippy: `pedantic` + `nursery` on main crate. CI enforces `-D warnings -D clippy::redundant_clone`, on both the default targets and `--tests`.\n- Rustdoc: CI runs `cargo doc --document-private-items --no-deps --workspace` with `RUSTDOCFLAGS=-D warnings`. Broken intra-doc links fail the build.\n- Format: `cargo fmt`. Only non-default: `reorder_imports = true`.\n- IDs: UUIDv7 (time-ordered), newtype wrappers (`HistoryId`, `RecordId`, `HostId`).\n- Serialization: MessagePack for encrypted payloads, JSON for API, TOML for config.\n- Storage traits: `Database` (client), `Store` (record store), `Database` (server) -- all `async_trait`.\n- History builders: `HistoryImported`, `HistoryCaptured`, `HistoryFromDb` with compile-time field validation.\n- Feature flags: `client`, `sync`, `daemon`, `clipboard`, `check-update`.\n\n## Testing\n\n- Unit tests inline with `#[cfg(test)]`, async via `#[tokio::test]`.\n- Integration tests in `crates/atuin/tests/` need Postgres (`ATUIN_DB_URI` env var).\n- Use `rstest` for tests, especially when they can be made simpler using `case`s and `fixture`s.\n- Use `\":memory:\"` SQLite for unit tests needing a database.\n- Runner: `cargo nextest`.\n- Benchmarks: `divan` in `atuin-client`, `atuin-history` and `atuin-nucleo-matcher`, tracked in CI\n  by CodSpeed. Run them locally with `cargo codspeed build && cargo codspeed run`, or with plain\n  `cargo bench`.\n\n## Build and check\n\n```sh\ncargo build\ncargo test\ncargo clippy -- -D warnings -D clippy::redundant_clone\ncargo clippy --tests -- -D warnings -D clippy::redundant_clone\ncargo fmt --check\nRUSTDOCFLAGS=\"-D warnings\" cargo doc --document-private-items --no-deps --workspace\n```\n"}}