IRIS (Intelligent Real-time Input Suggestion) - A shell auto-completion tool that works like code editor's IntelliSense

[![macOS](https://img.shields.io/badge/macOS-FFFFFF?style=for-the-badge&logo=apple&logoColor=black)](https://www.apple.com/macos/) [![Linux](https://img.shields.io/badge/Linux-131415?style=for-the-badge&logo=linux&logoColor=white)](https://www.kernel.org/)
[![Status](https://img.shields.io/badge/status-beta-yellow?style=for-the-badge&logo=github&logoColor=white)]() [![License: 0BSD](https://img.shields.io/badge/License-0BSD-blue?style=for-the-badge&logo=github&logoColor=white)](./LICENSE) [![Documentation](https://img.shields.io/badge/docs-available-brightgreen?style=for-the-badge&logo=github&logoColor=white)](#install) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=for-the-badge&logo=github&logoColor=white)](./CONTRIBUTING.md) Comparison · Install · Shortcuts · Configuration · Reporting bugs

👻 Ghostty terminal

**IRIS is built on top of TTY, so it runs everywhere. It just needs a terminal!** Run iris wherever you already work; your local machine, a remote server, or anywhere you can ssh. Each suggestion menu renders directly inline inside your real terminal session, not an app's imitation of one, so it never breaks full-screen TUIs or terminal formatting. Automatically index your aliases and shell history to suggest commands that match your actual workflow in real time. Change configurations and propagate them instantly without restarting your shell. One single local native Go binary, not an app: no gui, no electron, no mac-only wrapper, no account, no telemetry. (if you've used fig: it's that, rebuilt to run purely on TTY) ## AI suggestions

IRIS has AI suggestions like your code editor (API key/Local)

Arch Linux (AUR)

IRIS is available on the Arch User Repository. You can install it using your favorite AUR helper: ```bash yay -S iris-autocomplete ``` OR ```bash paru -S iris-autocomplete ```

macOS / Linux (Homebrew)

Install IRIS via Homebrew tap: ```bash brew install versenilvis/iris/iris ```

Nix Flakes

If you are using Nix Flakes, you can consume this module directly without building it manually. 1. In your `flake.nix` inputs, add: ```nix iris.url = "github:versenilvis/iris/main"; ``` 2. Then, use one of the following options to add IRIS to your system: **Option A: Try without installing (ephemeral)** ```bash nix run github:versenilvis/iris ``` **Option B: Install to your user profile** ```bash nix profile install github:versenilvis/iris ``` **Option C: Using Home Manager** *(Ensure you pass `inputs` to modules via `extraSpecialArgs`)* ```nix home.packages = [ inputs.iris.packages.${pkgs.system}.default ]; ``` **Option D: Without Home Manager (NixOS System)** *(Ensure you pass `inputs` to modules via `specialArgs`)* ```nix environment.systemPackages = [ inputs.iris.packages.${pkgs.system}.default ]; ```

Debian / Ubuntu (.deb)

```bash curl -sLO https://github.com/versenilvis/iris/releases/latest/download/iris_linux_amd64.deb sudo dpkg -i iris_linux_amd64.deb rm iris_linux_amd64.deb ``` *(For ARM64 architecture, replace `amd64` with `arm64`)*

Fedora / RHEL (.rpm)

```bash curl -sLO https://github.com/versenilvis/iris/releases/latest/download/iris_linux_amd64.rpm sudo rpm -i iris_linux_amd64.rpm rm iris_linux_amd64.rpm ``` *(For ARM64 architecture, replace `amd64` with `arm64`)*

Aqua

If you use [aqua](https://aquaproj.github.io/), you can install IRIS by adding it to your `aqua.yaml`: ```yaml packages: - name: versenilvis/iris ``` Then run `aqua i`.

asdf

If you use [asdf](https://asdf-vm.com/), you can install IRIS via its plugin: ```bash asdf plugin add iris https://github.com/versenilvis/asdf-iris.git asdf install iris latest asdf set -u iris latest asdf current iris ```

#### Method 2: Install script (recommended) ```bash curl -sSL https://raw.githubusercontent.com/versenilvis/iris/main/scripts/install.sh | sh ``` #### Method 3: Go install ```bash go install github.com/versenilvis/iris/cmd/iris@latest ``` #### Method 4: Build from source (for developers) ```bash git clone https://github.com/versenilvis/iris.git cd iris just reload ``` ## Uninstall To completely uninstall IRIS, remove all configurations, and clean up your shell integration files, simply run: ```bash iris uninstall ``` ## Shell setup > [!WARNING] > **IRIS may cause visual conflicts and keybinding overlaps with other shell autosuggestion plugins or third-party completion tools. To prevent this, please disable them safely (e.g., zsh-autosuggestions, zsh-autocomplete, atuin, flyline, ...)** Add an alias to your shell configuration file to launch IRIS easily: **Zsh (`~/.zshrc`):** ```zsh if command -v iris >/dev/null 2>&1; then alias i="iris" fi ``` **Bash (`~/.bashrc`):** ```bash if command -v iris >/dev/null 2>&1; then alias i="iris" fi ``` **Fish (`~/.config/fish/config.fish`):** ```fish if command -v iris >/dev/null 2>&1 alias i="iris" end ``` ## Configuration guide IRIS uses a clean TOML configuration file located at `~/.config/iris/config.toml`. ### Creating & viewing config ```bash iris config init iris config show ``` ### Sample `config.toml` ```toml [core] version = 1 shell = "" # "zsh", "bash", "fish", or empty for auto-detection shell-login = false # run the selected shell as a login shell; can also be enabled with iris --shell-login mode = "last" # "last", "spec", or "history" debug = false expand-alias = true auto-execute = false [ui] style = "modern" # "modern" or "classic" ghost-text = true hidden-files = false max-suggestions = 100 max-height = 15 max-width = 0 nerd-fonts = true [keybindings] toggle-mode = "ctrl+r" toggle-menu = "shift+tab" select = "tab" navigate-up = "up" navigate-down = "down" [git] filter-active-branch = true deduplicate-branches = true [updater] check-on-startup = true channel = "stable" # "stable" or "nightly" check-interval = "24h" [ai] enabled = false provider = "groq" # "groq" or "ollama" debounce_ms = 400 # please use free subscription, that is enough for your daily usage [ai.providers.groq] endpoint = "https://api.groq.com/openai/v1/chat/completions" api_key_env = "GROQ_API_KEY" # or set api_key directly model = "llama-3.3-70b-versatile" timeout_ms = 3000 [ai.providers.ollama] endpoint = "http://localhost:11434/v1/chat/completions" model = "qwen2.5-coder" timeout_ms = 5000 ``` > [!NOTE] > Using `api_key_env` is recommended over hardcoding `api_key` in plain text to keep credentials out of configuration files. ## Default shortcuts | Shortcut | Action | Description | | :--------------------------------- | :---------------------- | :------------------------------------------------------------------------ | | Shift + Tab | Toggle menu | Show or hide the suggestion menu. | | Esc | Hide menu | Temporarily hide the menu until the next key press. | | Tab | Accept suggestion | Insert the currently selected suggestion into the prompt. | | Enter | Execute command | Close the menu and send the current command to the shell. | | ↑ | Navigate up / history | Move the selection up, or open command history when the prompt is empty. | | ↓ | Navigate down / history | Move the selection down, or open command history when the prompt is empty.| | → | Accept ghost text | Accept the faded ghost text suggestion when the menu is open. | | ← / → | Move cursor | Move the cursor inside the input buffer. Disabled when the prompt is empty| | Ctrl/⌘ + R | Switch mode | Toggle between `spec` and `history` mode. | | Ctrl/⌘ + A | Beginning of line | Move the cursor to the start of the command line. | | Ctrl/⌘ + E | End of line | Move the cursor to the end of the command line. | | Ctrl/⌘ + L | Clear screen | Clear the terminal while preserving the input buffer and redrawing the menu. | | Ctrl/⌘ + U | Clear command | Remove the entire current command and close the menu. | | Ctrl/⌘ + C | Cancel command | Send `SIGINT`, clear the input buffer, and close the menu. | | Ctrl/⌘ + W | Delete word | Delete the word immediately before the cursor. | > [!NOTE] > With Ctrl/⌘ + A, Ctrl/⌘ + E, Ctrl/⌘ + W, Ctrl/⌘ + U, Ctrl/⌘ + L, and Ctrl/⌘ + C: they belong to your shell by default. IRIS handles them directly in raw mode so your cursor and menu stay in sync ## Theme

😺 Kitty terminal

> [!NOTE] > Currently, IRIS doesn't have custom theme but it does have 2 basic styles

Modern style	Classic style

## Reporting bugs > [!NOTE] > When submitting a bug report, please include: > - A detailed description of the bug and steps to reproduce it > - Relevant log files captured while running in debug mode Run IRIS with debug mode: ```bash iris -d ``` or `config.toml`: ```toml debug=true ``` > [!IMPORTANT] > **Since IRIS logs everything you type, you should only enable debug mode when you need to report bugs** If IRIS crashes, it will automatically save a crash log and show the path on your terminal (`~/.iris/crash.log`). Or you can find the path to the latest crash log by running: ```bash iris crash-log ``` Please include this file when reporting a crash. ## Developer documentation For system architecture overview, engine design, and contribution guide, please refer to the [Developer documentation](./docs/dev/README.md). ## License This project is licensed under the [0BSD License](LICENSE) - no strings attached. Meaning you can do whatever you want with it. For those who fork it and want to publish a new version or something else; if you can, a credit or co-author mention is always welcome :) (though never required). Thank you! ## Feedback I'd love to hear your feedback Feel free to reach out via: - [Email](mailto:versedev.store@proton.me) - [Twitter](https://twitter.com/versenilvis) - [GitHub issues](https://github.com/versenilvis/iris/issues/new)