# atuinsh/atuin architecture

> Architecture diagram of the GitHub repository atuinsh/atuin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/atuinsh/atuin
- Repository: https://github.com/atuinsh/atuin

## Overview

Atuin is a terminal history and agent-thread capture, search, resume, and synchronization product. Users invoke the CLI or shell search UI; recorded shell activity and supported agent sessions become searchable local history, while threads can be resumed across machines or harnesses. The README documents end-to-end encrypted sync and optional MCP access. The sampled sources show CLI dispatch, daemon RPC registration, search-engine selection, and agent-session persistence; several major feature links are documented in the README rather than verified in sampled implementation excerpts.

Main entry points: [`crates/atuin-client/src/database.rs`](https://github.com/atuinsh/atuin/blob/main/crates/atuin-client/src/database.rs) (History database), [`crates/atuin-client/src/ai_session/database.rs`](https://github.com/atuinsh/atuin/blob/main/crates/atuin-client/src/ai_session/database.rs) (Thread storage and search), [`crates/atuin-ai/src/commands/session.rs`](https://github.com/atuinsh/atuin/blob/main/crates/atuin-ai/src/commands/session.rs) (Thread commands), [`crates/atuin-ai/src/mcp.rs`](https://github.com/atuinsh/atuin/blob/main/crates/atuin-ai/src/mcp.rs) (Agent MCP access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_cli["Atuin CLI<br/>[main.rs]"]
  node_commands["Client commands<br/>[client.rs]"]
end

subgraph group_history["Shell history"]
  node_searchui["Interactive search<br/>[engines.rs]"]
  node_historydb[("History database<br/>[database.rs]")]
  node_historycapture["History capture<br/>[capture.rs]"]
  node_shellimport["Shell importers<br/>[mod.rs]"]
end

subgraph group_threads["Agent threads"]
  node_threadcapture["Harness capture<br/>[session.rs]"]
  node_threadindex[("Thread storage and search<br/>[database.rs]")]
  node_threadcommands["Thread commands<br/>[session.rs]"]
  node_resume["Resume workflow<br/>[resume.rs]"]
  node_resumetui["Resume interface<br/>[resumer.rs]"]
  node_mcp["Agent MCP access<br/>[mcp.rs]"]
end

subgraph group_daemon["Local daemon"]
  node_daemoncore["Daemon event loop<br/>[daemon.rs]"]
  node_rpc["Daemon RPC server<br/>[server.rs]"]
  node_daemonsearch["Daemon search<br/>[mod.rs]"]
end

subgraph group_sync["Sync and service"]
  node_syncengine["History sync engine<br/>[engine.rs]"]
  node_syncworker["Sync worker<br/>[worker.rs]"]
  node_syncserver["Sync service<br/>[router.rs]"]
  node_clientapi["Sync API client<br/>[api_client.rs]"]
  node_encryption["Encrypted records<br/>[paseto_v4.rs]"]
end

node_user(("Terminal user"))
node_agents(("AI agents"))

node_user -->|"runs"| node_cli
node_cli -->|"dispatches"| node_commands
node_user -->|"opens"| node_searchui
node_commands -->|"routes search"| node_searchui
node_searchui -->|"queries"| node_historydb
node_historycapture -.->|"records commands"| node_historydb
node_shellimport -.->|"imports history"| node_historydb
node_user -->|"runs threads"| node_threadcommands
node_threadcapture -.->|"captures sessions"| node_threadindex
node_threadcommands -->|"searches threads"| node_threadindex
node_threadcommands -->|"routes resume"| node_resume
node_resume -.->|"opens interface"| node_resumetui
node_agents -->|"requests context"| node_mcp
node_mcp -.->|"searches history"| node_historydb
node_mcp -.->|"searches threads"| node_threadindex
node_daemoncore -->|"serves RPCs"| node_rpc
node_rpc -->|"registers search"| node_daemonsearch
node_daemonsearch -.->|"searches history"| node_historydb
node_historydb -.->|"supplies history"| node_syncworker
node_threadindex -.->|"supplies threads"| node_syncworker
node_syncworker -.->|"coordinates sync"| node_syncengine
node_syncengine -.->|"uploads records"| node_clientapi
node_clientapi -->|"syncs remotely"| node_syncserver
node_syncengine -->|"encrypts data"| node_encryption

click node_cli "https://github.com/atuinsh/atuin/blob/main/crates/atuin/src/main.rs"
click node_commands "https://github.com/atuinsh/atuin/blob/main/crates/atuin/src/command/client.rs"
click node_searchui "https://github.com/atuinsh/atuin/blob/main/crates/atuin/src/command/client/search/engines.rs"
click node_historydb "https://github.com/atuinsh/atuin/blob/main/crates/atuin-client/src/database.rs"
click node_historycapture "https://github.com/atuinsh/atuin/blob/main/crates/atuin-client/src/history/capture.rs"
click node_shellimport "https://github.com/atuinsh/atuin/blob/main/crates/atuin-client/src/import/mod.rs"
click node_threadcapture "https://github.com/atuinsh/atuin/blob/main/crates/atuin-common/src/harnesstools/opencode/session.rs"
click node_threadindex "https://github.com/atuinsh/atuin/blob/main/crates/atuin-client/src/ai_session/database.rs"
click node_threadcommands "https://github.com/atuinsh/atuin/blob/main/crates/atuin-ai/src/commands/session.rs"
click node_resume "https://github.com/atuinsh/atuin/blob/main/crates/atuin-ai/src/commands/resume.rs"
click node_resumetui "https://github.com/atuinsh/atuin/blob/main/crates/atuin-ai/src/resume_tui/resumer.rs"
click node_mcp "https://github.com/atuinsh/atuin/blob/main/crates/atuin-ai/src/mcp.rs"
click node_daemoncore "https://github.com/atuinsh/atuin/blob/main/crates/atuin-daemon/src/daemon.rs"
click node_rpc "https://github.com/atuinsh/atuin/blob/main/crates/atuin-daemon/src/server.rs"
click node_daemonsearch "https://github.com/atuinsh/atuin/blob/main/crates/atuin-daemon/src/search/mod.rs"
click node_syncengine "https://github.com/atuinsh/atuin/blob/main/crates/atuin-daemon/src/octavo/client/active/engine.rs"
click node_syncworker "https://github.com/atuinsh/atuin/blob/main/crates/atuin-daemon/src/sync/engine/worker.rs"
click node_syncserver "https://github.com/atuinsh/atuin/blob/main/crates/atuin-server/src/router.rs"
click node_clientapi "https://github.com/atuinsh/atuin/blob/main/crates/atuin-client/src/api_client.rs"
click node_encryption "https://github.com/atuinsh/atuin/blob/main/crates/atuin-common/src/encryption/paseto_v4.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_commands,node_user toneBlue
class node_searchui,node_historydb,node_historycapture,node_shellimport toneAmber
class node_threadcapture,node_threadindex,node_threadcommands,node_resume,node_resumetui,node_mcp toneMint
class node_daemoncore,node_rpc,node_daemonsearch toneRose
class node_syncengine,node_syncworker,node_syncserver,node_clientapi,node_encryption,node_agents toneIndigo
```

## Components

### User entry points

- [Atuin CLI](https://github.com/atuinsh/atuin/blob/main/crates/atuin/src/main.rs): `crates/atuin/src/main.rs`
- [Client commands](https://github.com/atuinsh/atuin/blob/main/crates/atuin/src/command/client.rs): `crates/atuin/src/command/client.rs`

### Shell history

- [Interactive search](https://github.com/atuinsh/atuin/blob/main/crates/atuin/src/command/client/search/engines.rs): `crates/atuin/src/command/client/search/engines.rs`
- [History database](https://github.com/atuinsh/atuin/blob/main/crates/atuin-client/src/database.rs): `crates/atuin-client/src/database.rs`
- [History capture](https://github.com/atuinsh/atuin/blob/main/crates/atuin-client/src/history/capture.rs): `crates/atuin-client/src/history/capture.rs`
- [Shell importers](https://github.com/atuinsh/atuin/blob/main/crates/atuin-client/src/import/mod.rs): `crates/atuin-client/src/import/mod.rs`

### Agent threads

- [Harness capture](https://github.com/atuinsh/atuin/blob/main/crates/atuin-common/src/harnesstools/opencode/session.rs): `crates/atuin-common/src/harnesstools/opencode/session.rs`
- [Thread storage and search](https://github.com/atuinsh/atuin/blob/main/crates/atuin-client/src/ai_session/database.rs): `crates/atuin-client/src/ai_session/database.rs`
- [Thread commands](https://github.com/atuinsh/atuin/blob/main/crates/atuin-ai/src/commands/session.rs): `crates/atuin-ai/src/commands/session.rs`
- [Resume workflow](https://github.com/atuinsh/atuin/blob/main/crates/atuin-ai/src/commands/resume.rs): `crates/atuin-ai/src/commands/resume.rs`
- [Resume interface](https://github.com/atuinsh/atuin/blob/main/crates/atuin-ai/src/resume_tui/resumer.rs): `crates/atuin-ai/src/resume_tui/resumer.rs`
- [Agent MCP access](https://github.com/atuinsh/atuin/blob/main/crates/atuin-ai/src/mcp.rs): `crates/atuin-ai/src/mcp.rs`

### Local daemon

- [Daemon event loop](https://github.com/atuinsh/atuin/blob/main/crates/atuin-daemon/src/daemon.rs): `crates/atuin-daemon/src/daemon.rs`
- [Daemon RPC server](https://github.com/atuinsh/atuin/blob/main/crates/atuin-daemon/src/server.rs): `crates/atuin-daemon/src/server.rs`
- [Daemon search](https://github.com/atuinsh/atuin/blob/main/crates/atuin-daemon/src/search/mod.rs): `crates/atuin-daemon/src/search/mod.rs`

### Sync and service

- [History sync engine](https://github.com/atuinsh/atuin/blob/main/crates/atuin-daemon/src/octavo/client/active/engine.rs): `crates/atuin-daemon/src/octavo/client/active/engine.rs`
- [Sync worker](https://github.com/atuinsh/atuin/blob/main/crates/atuin-daemon/src/sync/engine/worker.rs): `crates/atuin-daemon/src/sync/engine/worker.rs`
- [Sync service](https://github.com/atuinsh/atuin/blob/main/crates/atuin-server/src/router.rs): `crates/atuin-server/src/router.rs`
- [Sync API client](https://github.com/atuinsh/atuin/blob/main/crates/atuin-client/src/api_client.rs): `crates/atuin-client/src/api_client.rs`
- [Encrypted records](https://github.com/atuinsh/atuin/blob/main/crates/atuin-common/src/encryption/paseto_v4.rs): `crates/atuin-common/src/encryption/paseto_v4.rs`

### Other components

- **Terminal user**
- **AI agents**

## Connections

- Terminal user → Atuin CLI: runs (evidence: `README.md`)
- Atuin CLI → Client commands: dispatches (evidence: `crates/atuin/src/main.rs`)
- Terminal user → Interactive search: opens (evidence: `README.md`)
- Client commands → Interactive search: routes search (evidence: `crates/atuin/src/command/client.rs`)
- Interactive search → History database: queries (evidence: `crates/atuin/src/command/client/search/engines.rs`)
- History capture → History database: records commands
- Shell importers → History database: imports history
- Terminal user → Thread commands: runs threads (evidence: `README.md`)
- Harness capture → Thread storage and search: captures sessions
- Thread commands → Thread storage and search: searches threads (evidence: `README.md`)
- Thread commands → Resume workflow: routes resume (evidence: `crates/atuin-ai/src/commands/session.rs`)
- Resume workflow → Resume interface: opens interface
- AI agents → Agent MCP access: requests context (evidence: `README.md`)
- Agent MCP access → History database: searches history
- Agent MCP access → Thread storage and search: searches threads
- Daemon event loop → Daemon RPC server: serves RPCs (evidence: `crates/atuin-daemon/src/server.rs`)
- Daemon RPC server → Daemon search: registers search (evidence: `crates/atuin-daemon/src/server.rs`)
- Daemon search → History database: searches history
- History database → Sync worker: supplies history
- Thread storage and search → Sync worker: supplies threads
- Sync worker → History sync engine: coordinates sync
- History sync engine → Sync API client: uploads records
- Sync API client → Sync service: syncs remotely (evidence: `README.md`)
- History sync engine → Encrypted records: encrypts data (evidence: `README.md`)
