iris-context/docs/README.md

User guide

Iris is a fast terminal autocomplete assistant written in Go. It wraps around your shell (Zsh, Bash, or Fish) to give you real-time command suggestions, a floating dropdown menu, and smart history search right where you type.

Table of contents

• Getting started
• Shortcuts
• Configuration guide
• Reporting bugs
• Developer documentation

Getting started

Dependencies

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

Installation

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@latest

Method 3: Build from source

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

Shell setup

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

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

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
mode = "last"     # "last", "spec", or "history"
debug = false
expand-alias = true

[ui]
style = "modern"  # "modern" or "classic"
ghost-text = true
hidden-files = false
max-suggestions = 100
max-height = 15
nerd-fonts = true

[keybindings]
toggle-mode = "ctrl+r"
toggle-menu = "ctrl+space"

[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

[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.

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