feat: Generate commands or ask questions with `atuin ai` (#3199)

This PR refines the system created in #3178 to be suitable for a v1
release.

---

## Overview

`atuin-ai` is a separate binary that allows for generating commands and
asking questions from the command line.

It is fully opt-in.

## Usage

`atuin ai init` will output bindings for your shell. Currently, bash,
zsh, and fish are supported.

```bash
eval "$(atuin ai init)"
```

Once the hooks are installed, just press `?` on an empty prompt line to
call up the TUI.

`atuin ai` requires an account on [Atuin Hub](https://hub.atuin.sh/);
you will be prompted to log in on first use.

## Features

### Command generation

Prompt the LLM to create a command, and get one back, no fuss. Press
`enter` to run, or `tab` to insert.

```
┌Ask questions or generate a command:──────────────────────────┐
│                                                              │
│ > Get a list of running docker containers                    │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│ $ docker ps                                                  │
│                                                              │
└────[Enter]: Run  [Tab]: Insert  [f]: Follow-up  [Esc]: Cancel┘
```

### Follow-up

You can follow-up with `f` to specify a refinement prompt to update the
command that will be inserted.

```
┌Ask questions or generate a command:──────────────────────────┐
│                                                              │
│ > Get a list of running docker containers                    │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│ $ docker ps                                                  │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│ > Actually I want to get all docker containers               │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│ $ docker ps -a                                               │
│                                                              │
└────[Enter]: Run  [Tab]: Insert  [f]: Follow-up  [Esc]: Cancel┘
```

You can also follow-up with questions to get responses in natural
language.

```
┌Ask questions or generate a command:──────────────────────────┐
│                                                              │
│ > Get a list of running docker containers                    │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│ $ docker ps                                                  │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│ > Actually I want to get all docker containers               │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│ $ docker ps -a                                               │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│ > What other useful flags to `docker ps` should I know?      │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│   Here are some handy `docker ps` flags:                     │
│                                                              │
│   - `-q` — Only show container IDs (great for piping to      │
│   other commands)                                            │
│   - `-s` — Show container sizes                              │
│   - `-n 5` — Show the last 5 created containers              │
│   - `-l` — Show only the latest created container            │
│   - `--no-trunc` — Don't truncate output (shows full IDs and │
│   commands)                                                  │
│   - `-f` or `--filter` — Filter by condition, e.g.:          │
│     - `-f status=exited` — only exited containers            │
│     - `-f name=myapp` — filter by name                       │
│     - `-f ancestor=nginx` — filter by image                  │
│   - `--format` — Custom output using Go templates, e.g.:     │
│     `--format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"`   │
│                                                              │
│   A common combo is `docker ps -aq` to get all container     │
│   IDs, useful for bulk operations like `docker rm $(docker   │
│   ps -aq)`.                                                  │
│                                                              │
└────[Enter]: Run  [Tab]: Insert  [f]: Follow-up  [Esc]: Cancel┘
```

You can use `enter` or `tab` at any time to run or insert the last
suggested command, even if it was suggested in a previous turn.

### Conversational and search usage

If you prompt the LLM with a question that doesn't imply you want to
generate a command, it can respond in natural language, and use web
search if necessary to fetch the data it needs.

```
┌Ask questions or generate a command:──────────────────────────┐
│                                                              │
│ > What is the latest version of atuin?                       │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│ ✓ Used 2 tools                                               │
│                                                              │
│   The latest version of Atuin is **v18.12.0**, available on  │
│   the [GitHub releases                                       │
│   page](https://github.com/atuinsh/atuin/releases).          │
│                                                              │
└─────────────────────────────────[f]: Follow-up  [Esc]: Cancel┘
```

### Dangerous or low-confidence command detection

The LLM scores its confidence in the command, as well as how dangerous
the command is. This information is shown if a threshold is exceeded,
and requires an extra confirmation step before running automatically
with `enter`.

The Atuin Hub server also monitors suggested commands for dangerous
patterns the LLM didn't catch, and appends its own assessment at the end
of the LLM's own assessment.

```
┌Ask questions or generate a command:──────────────────────────┐
│                                                              │
│ > Delete all files from $HOME                                │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│ $ rm -rf $HOME/*                                             │
│                                                              │
│ ! ⚠️  This will PERMANENTLY delete ALL files and directories │
│   in your home directory, including documents, downloads,    │
│   configurations, SSH keys, and everything else. This is     │
│   irreversible and will likely break your system. Also note  │
│   this won't delete hidden (dot) files — if you want those   │
│   too, that's even more destructive.; [Server] Recursive     │
│   delete of critical directory                               │
│                                                              │
└────[Enter]: Run  [Tab]: Insert  [f]: Follow-up  [Esc]: Cancel┘
```

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

6 files changed, 191 insertions, 3 deletions

diff --git a/docs/docs/ai/introduction.md b/docs/docs/ai/introduction.md
new file mode 100644
index 00000000..39c45eec
--- /dev/null
+++ b/docs/docs/ai/introduction.md
@@ -0,0 +1,157 @@
+# Atuin AI
+
+Atuin AI is a separate binary that enables command generation and other information lookup via an LLM directly from your terminal. It is completely opt-in, and will not change the behavior of Atuin at all if you choose not to use it.
+
+Atuin AI requires an account on [Atuin Hub](https://hub.atuin.sh/), and you'll be prompted to login upon first use of the binary.
+
+## Getting Started
+
+Atuin AI currently supports zsh, bash, and fish shells. To get started, add the following to your shell's initialization file:
+
+```bash
+eval "$(atuin ai init)"
+```
+
+Once you've set it up and restarted your shell, you can invoke Atuin AI by pressing question mark (`?`) on an empty terminal line.
+
+## Settings
+
+For a list of settings that control the behavior of Atuin AI, see [its dedicated settings documentation](./settings.md).
+
+## Features
+
+### Command generation
+
+Prompt the LLM to create a command, and get one back, no fuss. Press `enter` to run, or `tab` to insert.
+
+```
+┌Ask questions or generate a command:──────────────────────────┐
+│                                                              │
+│ > Get a list of running docker containers                    │
+│                                                              │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│ $ docker ps                                                  │
+│                                                              │
+└────[Enter]: Run  [Tab]: Insert  [f]: Follow-up  [Esc]: Cancel┘
+```
+
+### Follow-up
+
+You can follow-up with `f` to specify a refinement prompt to update the command that will be inserted.
+
+```
+┌Ask questions or generate a command:──────────────────────────┐
+│                                                              │
+│ > Get a list of running docker containers                    │
+│                                                              │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│ $ docker ps                                                  │
+│                                                              │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│ > Actually I want to get all docker containers               │
+│                                                              │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│ $ docker ps -a                                               │
+│                                                              │
+└────[Enter]: Run  [Tab]: Insert  [f]: Follow-up  [Esc]: Cancel┘
+```
+
+You can also follow-up with questions to get responses in natural language.
+
+```
+┌Ask questions or generate a command:──────────────────────────┐
+│                                                              │
+│ > Get a list of running docker containers                    │
+│                                                              │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│ $ docker ps                                                  │
+│                                                              │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│ > Actually I want to get all docker containers               │
+│                                                              │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│ $ docker ps -a                                               │
+│                                                              │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│ > What other useful flags to `docker ps` should I know?      │
+│                                                              │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│   Here are some handy `docker ps` flags:                     │
+│                                                              │
+│   - `-q` — Only show container IDs (great for piping to      │
+│   other commands)                                            │
+│   - `-s` — Show container sizes                              │
+│   - `-n 5` — Show the last 5 created containers              │
+│   - `-l` — Show only the latest created container            │
+│   - `--no-trunc` — Don't truncate output (shows full IDs and │
+│   commands)                                                  │
+│   - `-f` or `--filter` — Filter by condition, e.g.:          │
+│     - `-f status=exited` — only exited containers            │
+│     - `-f name=myapp` — filter by name                       │
+│     - `-f ancestor=nginx` — filter by image                  │
+│   - `--format` — Custom output using Go templates, e.g.:     │
+│     `--format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"`   │
+│                                                              │
+│   A common combo is `docker ps -aq` to get all container     │
+│   IDs, useful for bulk operations like `docker rm $(docker   │
+│   ps -aq)`.                                                  │
+│                                                              │
+└────[Enter]: Run  [Tab]: Insert  [f]: Follow-up  [Esc]: Cancel┘
+```
+
+You can use `enter` or `tab` at any time to run or insert the last suggested command, even if it was suggested in a previous turn.
+
+### Conversational and search usage
+
+If you prompt the LLM with a question that doesn't imply you want to generate a command, it can respond in natural language, and use web search if necessary to fetch the data it needs.
+
+```
+┌Ask questions or generate a command:──────────────────────────┐
+│                                                              │
+│ > What is the latest version of atuin?                       │
+│                                                              │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│ ✓ Used 2 tools                                               │
+│                                                              │
+│   The latest version of Atuin is **v18.12.0**, available on  │
+│   the [GitHub releases                                       │
+│   page](https://github.com/atuinsh/atuin/releases).          │
+│                                                              │
+└─────────────────────────────────[f]: Follow-up  [Esc]: Cancel┘
+```
+
+### Dangerous or low-confidence command detection
+
+The LLM scores its confidence in the command, as well as how dangerous the command is. This information is shown if a threshold is exceeded, and requires an extra confirmation step before running automatically with `enter`.
+
+The Atuin Hub server also monitors suggested commands for dangerous patterns the LLM didn't catch, and appends its own assessment at the end of the LLM's own assessment.
+
+```
+┌Ask questions or generate a command:──────────────────────────┐
+│                                                              │
+│ > Delete all files from $HOME                                │
+│                                                              │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│ $ rm -rf $HOME/*                                             │
+│                                                              │
+│ ! This will PERMANENTLY delete ALL files and directories in  │
+│   your home directory, including documents, downloads,       │
+│   configurations, SSH keys, and everything else. This is     │
+│   irreversible and will likely break your system. Also note  │
+│   this won't delete hidden (dot) files — if you want those   │
+│   too, that's even more destructive.; [Server] Recursive     │
+│   delete of critical directory                               │
+│                                                              │
+└────[Enter]: Run  [Tab]: Insert  [f]: Follow-up  [Esc]: Cancel┘
+```
diff --git a/docs/docs/ai/settings.md b/docs/docs/ai/settings.md
new file mode 100644
index 00000000..eb868f91
--- /dev/null
+++ b/docs/docs/ai/settings.md
@@ -0,0 +1,16 @@
+# AI Settings
+
+All the settings that control the behavior of [Atuin AI](./introduction.md) are specified in an `[ai]` section in your `config.toml`. See [the configuration documentation](../../configuration/config/) for more detailed information about Atuin's configuration system.
+
+### send_cwd
+
+Default: `false`
+
+Whether or not to include your current working directory in the context sent to the LLM. By default, only your OS and current shell are sent.
+
+**Example config**
+
+```toml
+[ai]
+send_cwd = true
+```
diff --git a/docs/docs/configuration/config.md b/docs/docs/configuration/config.md
index 8f0c6024..2bc1a682 100644
--- a/docs/docs/configuration/config.md
+++ b/docs/docs/configuration/config.md
@@ -873,3 +873,7 @@ columns = ["exit", "duration", "command"]
 # Make directory expand instead of command
 columns = ["duration", "time", { type = "directory", expand = true }, { type = "command", expand = false }]
 ```
+
+## ai
+
+The settings for Atuin AI are listed in [a separate section](../../ai/settings/).
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 26bf0bee..32df120c 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -89,6 +89,9 @@ nav:
       - Docker: self-hosting/docker.md
       - Kubernetes: self-hosting/kubernetes.md
       - Systemd: self-hosting/systemd.md
+  - AI:
+      - Introduction: ai/introduction.md
+      - Settings: ai/settings.md
   - Known Issues: known-issues.md
   - Integrations: integrations.md
   - FAQ: faq.md
diff --git a/docs/pyproject.toml b/docs/pyproject.toml
index e3bef982..2d58e8c7 100644
--- a/docs/pyproject.toml
+++ b/docs/pyproject.toml
@@ -11,5 +11,10 @@ dependencies = [
   "mkdocs-redirects>=1.2.2",
 ]
 
+[tool.uv]
+override-dependencies = [
+    "click==8.2.1",
+]
+
 [dependency-groups]
 dev = []
diff --git a/docs/uv.lock b/docs/uv.lock
index 9575e6ea..e9f9b420 100644
--- a/docs/uv.lock
+++ b/docs/uv.lock
@@ -2,6 +2,9 @@ version = 1
 revision = 3
 requires-python = ">=3.11"
 
+[manifest]
+overrides = [{ name = "click", specifier = "==8.2.1" }]
+
 [[package]]
 name = "atuin-cli-docs"
 version = "1.0.0"
@@ -133,14 +136,14 @@ wheels = [
 
 [[package]]
 name = "click"
-version = "8.3.1"
+version = "8.2.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "colorama", marker = "sys_platform == 'win32'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/3d/fa/656b739db8587d7b5dfa22e22ed02566950fbfbcdc20311993483657a5c0/click-8.3.1.tar.gz", hash = "sha256:12ff4785d337a1bb490bb7e9c2b1ee5da3112e94a8622f26a6c77f5d2fc6842a", size = 295065, upload-time = "2025-11-15T20:45:42.706Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/60/6c/8ca2efa64cf75a977a0d7fac081354553ebe483345c734fb6b6515d96bbc/click-8.2.1.tar.gz", hash = "sha256:27c491cc05d968d271d5a1db13e3b5a184636d9d930f148c50b038f0d0646202", size = 286342, upload-time = "2025-05-20T23:19:49.832Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/98/78/01c019cdb5d6498122777c1a43056ebb3ebfeef2076d9d026bfe15583b2b/click-8.3.1-py3-none-any.whl", hash = "sha256:981153a64e25f12d547d3426c367a4857371575ee7ad18df2a6183ab0545b2a6", size = 108274, upload-time = "2025-11-15T20:45:41.139Z" },
+    { url = "https://files.pythonhosted.org/packages/85/32/10bb5764d90a8eee674e9dc6f4db6a0ab47c8c4d0d83c27f7c39ac415a4d/click-8.2.1-py3-none-any.whl", hash = "sha256:61a3265b914e850b85317d0b3109c7f8cd35a670f963866005d6ef1d5175a12b", size = 102215, upload-time = "2025-05-20T23:19:47.796Z" },
 ]
 
 [[package]]