iris

README

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

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)

Why IRIS instead of Fig

[!IMPORTANT] Fig was officially sunset in September 2024 and migrated to Amazon Q Developer (which requires cloud authentication and proprietary bloat)
IRIS is the lightweight, open-source, zero-telemetry alternative built purely on native Go and TTY with no accounts, no GUI app, and no background daemons required

How it compares

Feature	IRIS	Fig
Platforms	Linux, macOS	macOS only
Engine	Native Go (TTY)	Electron
Startup	Near-zero overhead	Low overhead
UI	Inline overlay	GUI popover
Remote SSH	TTY-native, portable	macOS GUI-bound
Tmux	✓	Limited
Linux virtual terminals	✓	-
Memory	Lightweight	Electron runtime

Why not shell autocomplete plugins?

Shell plugins are great, but they also come with trade-offs. And also, not everyone use Zsh or Fish especially on SSH.

Feature	IRIS	Shell plugins
Installation	Single binary	Plugin manager required
Shell support	Most shells supported	Usually shell-specific
Startup	No shell initialization	Increases shell startup time
SSH	One config	Per-shell config
Tmux	✓	Depends on the shell
Linux virtual terminals	✓	Depends on the shell

Install

Dependencies

• OS: Linux or macOS
• Terminal emulator with ANSI color support
• Go 1.24 or newer (if building from source)

Method 1: Install script (recommended)

curl -sSL https://raw.githubusercontent.com/versenilvis/iris/main/scripts/install.sh | sh

Method 2: Go install

go install github.com/versenilvis/iris/cmd/iris@latest

Method 3: Build from source (for developers)

git clone https://github.com/versenilvis/iris.git
cd iris
just reload

[!WARNING] Currently, Windows is not supported

Uninstall

To completely uninstall IRIS, remove all configurations, and clean up your shell integration files, simply run:

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):

if command -v iris >/dev/null 2>&1; then
    alias i="iris"
fi

Bash (~/.bashrc):

if command -v iris >/dev/null 2>&1; then
    alias i="iris"
fi

Fish (~/.config/fish/config.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

iris config init
iris config show

Sample config.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:

iris -d

or config.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:

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.

License

This project is licensed under the 0BSD 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
• Twitter
• GitHub issues