diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/docs/ai/images/tool_atuin_history.png | bin | 0 -> 80150 bytes | |||
| -rw-r--r-- | docs/docs/ai/introduction.md | 4 | ||||
| -rw-r--r-- | docs/docs/ai/settings.md | 2 | ||||
| -rw-r--r-- | docs/docs/ai/tools-permissions.md | 81 | ||||
| -rw-r--r-- | docs/mkdocs.yml | 1 |
5 files changed, 85 insertions, 3 deletions
diff --git a/docs/docs/ai/images/tool_atuin_history.png b/docs/docs/ai/images/tool_atuin_history.png Binary files differnew file mode 100644 index 00000000..c71d37bd --- /dev/null +++ b/docs/docs/ai/images/tool_atuin_history.png diff --git a/docs/docs/ai/introduction.md b/docs/docs/ai/introduction.md index b14634b3..c7f0af04 100644 --- a/docs/docs/ai/introduction.md +++ b/docs/docs/ai/introduction.md @@ -10,7 +10,7 @@ Atuin AI currently supports zsh, bash, and fish shells. Your shell's usual `atui !!! note "Disabling Atuin AI" - You can disable the default question mark key binding by passing `--disable-ai` to your shell's `atuin init` call. + You can disable the default question mark key binding by passing `--disable-ai` to your shell's `atuin init` call, or by setting `ai.enabled` to `false` in your Atuin config. ## Settings @@ -26,7 +26,7 @@ Prompt the LLM to create a command, and get one back, no fuss. Press `enter` to ### Follow-up -You can follow-up with a refinement prompt to update the command that will be inserted. +You can follow-up with another prompt to update the command that will be inserted. [](./images/basic-refine.png) diff --git a/docs/docs/ai/settings.md b/docs/docs/ai/settings.md index 83b6bf63..a3aa9513 100644 --- a/docs/docs/ai/settings.md +++ b/docs/docs/ai/settings.md @@ -28,7 +28,7 @@ Settings that control what capabilities are sent to the LLM. These are specified Default: `true` -Whether or not to include the "history search" capability in the context sent to the LLM. This allows the AI to request to search your command history for relevant commands when generating suggestions or answering questions. +Whether or not to include the "history search" capability in the context sent to the LLM. This allows the AI to request to search your Atuin history for relevant commands when generating suggestions or answering questions. **Example config** diff --git a/docs/docs/ai/tools-permissions.md b/docs/docs/ai/tools-permissions.md new file mode 100644 index 00000000..a8f16298 --- /dev/null +++ b/docs/docs/ai/tools-permissions.md @@ -0,0 +1,81 @@ +# Atuin AI Tools & Permissions + +Atuin AI has a number of tools that it can use to interact with your system, given your permission. The AI can use these tools to help answer questions and perform actions on your behalf. + +!!! note "More tools coming soon" + We will be expanding the list of tools that Atuin AI can use over time. + +## Permission System + +By default, Atuin AI asks your permission before using any client-side tool. You can change these defaults using a *permission file*. + +### Permission Files + +Permission files live at `.atuin/permissions.ai.toml` in any project. When the AI wants to run a tool, Atuin AI will check its working directory for a `.atuin/permissions.ai.toml` file, and will also check every permission file in parent directories, up to the root of the filesystem. Finally, Atuin AI checks for a `permissions.ai.toml` file in the Atuin config directory (`~/.config/atuin/permissions.ai.toml` by default). + +A permission file is a TOML file with the following format: + +```toml +[permissions] + +allow = [ + # rules for automatically allowed tools +] + +deny = [ + # rules for automatically denied tools +] + +ask = [ + # rules for tools that require asking for permission +] +``` + +If Atuin AI doesn't find a matching rule, it defaults to asking for permission before running the tool. + +Permission files found deeper in the filesystem take priority over permission files found higher up. For example, if Atuin AI finds a permission file in the current working directory that allows a tool, it will allow that tool, even if a parent directory has a permission file that denies it. + +Within a permissions file, `ask` rules take priority over `deny` rules, which take priority over `allow` rules. For example, if a permission file has a rule that allows a tool, but also has a rule that asks for permission for that tool, Atuin AI will ask for permission before running the tool. + +### Permission Scopes + +Most rules can be scoped to a particular path or other context. For example, you can allow Atuin AI to read files in a particular directory, but not in others. For rules pertaining to file operations, the scope is a glob pattern that matches file paths. + +### Example Config + +Here's an example of a permission file that allows Atuin AI to read and write any markdown files in the current project, but denies it access to any `.env` files. Attempts to read or write any *other* files will result in Atuin AI requesting permission before proceeding. + +!!! note "Reading and writing files" + Atuin AI cannot currently read or write files; that capability is currently in development. + +```toml +[permissions] + +allow = [ + "Read(**/*.md)", "Write(**/*.md)" +] + +deny = [ + "Read(.env)", "Write(.env)" +] +``` + +## Tools + +### Atuin History + +The `AtuinHistory` tool allows Atuin AI to search your Atuin history for relevant commands. This tool is read-only. Atuin AI might ask to use this tool when you ask it to recall a command or information about a command you ran in the past, or when you ask for help with a failing command (e.g. "why did my last command fail?"). + + + +**Permission rule and scope:** `AtuinHistory` + +**Config value:** `ai.capabilities.enable_history_search` (see [settings documentation](./settings.md#capabilities)) + +**Example permissions file:** + +```toml +[permissions] + +allow = ["AtuinHistory"] +``` diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index a25dfa8f..1d6d7006 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -100,6 +100,7 @@ nav: - AI: - Introduction: ai/introduction.md - Settings: ai/settings.md + - "Tools & Permissions": ai/tools-permissions.md - Known Issues: known-issues.md - Integrations: integrations.md - FAQ: faq.md |
