diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..ff8c021
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,32 @@
+# Agents
+
+This role configures [Atuin](https://atuin.sh/) server - a modern replacement for shell history with encrypted sync and cloud support.
+
+## Role Analysis
+
+- **Type**: Application server role
+- **OS Support**: Debian 12
+- **Deployment Method**: Docker (inferred from structure)
+- **Dependencies**: Docker must be installed on the target host
+
+## Key Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `atuin_version` | `18.11.0` | Atuin server version |
+| `atuin_db_host` | `localhost` | Database host |
+| `atuin_db_name` | `atuin` | Database name |
+| `atuin_db_user` | `atuin` | Database user |
+| `atuin_db_pass` | `atuin` | Database password |
+
+## Tasks
+
+1. **install** - Installs Atuin via Docker
+2. **config** - Configures Atuin settings
+
+## Testing
+
+```bash
+ansible-lint
+molecule test
+```