iris-context/AGENTS.md

To Clankers

IRIS - Shell Auto-Completion Tool

IRIS is a lightweight, TTY-native shell auto-completion tool written in Go. No Electron, no GUI, no telemetry-runs on macOS and Linux with terminal emulators supporting ANSI colors.

Product Language

• Core value: Real-time command suggestions rendered directly in the terminal (like IntelliSense for shells)
• Alternative to Fig (sunset Sept 2024): Lighter, open-source, multi-shell (bash/zsh/fish), runs on any terminal
• Design principle: Native Go binary, pure TTY, one process per session
• Two suggestion modes: "spec" (command specs/flags) or "history" (shell history + frecency)

Key Architectural Files

PTY & Input Handling

• root/wrapper.go:124-1230 - Core event loop: PTY setup, terminal raw mode, keystroke interception, signal handling. Dense and critical.
  • Signal handling: SIGWINCH (resize), SIGUSR1 (reload)
  • Input parsing: Enter, Tab, Shift+Tab, arrow keys, Ctrl+shortcuts
  • Output bridging: Shell stdout to real stdout
  • IPC listening: shell-to-iris communication via FD13

Suggestion Engine

• root/suggestions.go:18-111 - MergeResults: dedupes, scores, and ranks suggestions from history/spec/AI
  • Two paths: history mode (confidence-based) vs spec mode (frecency scoring)
  • Frecency: uses internal/scoring package with context signals (cwd, prev command, etc.)
  • AI injection: optional LLM suggestions via internal/ai

Configuration & Themes

• internal/config/config.go - Config struct, TOML parsing, hot-reload on file change
  • Default keybindings: Ctrl+R (toggle mode), Shift+Tab (toggle menu), Tab (select)
  • Validation rules: modes (last/spec/history), shells (bash/zsh/fish), channels (stable/nightly)
  • AutoDetectConfigChange: polls every 1s for config/theme changes

Terminal Rendering

• integration/overlay.go - Overlay struct, menu rendering, ghost text, cursor tracking
  • ComputeCursorCol: parses ANSI escape sequences to track cursor position
  • Renders using lipgloss v2 (charm.sh)

Data Structures

• spec/spec.go:1-59 - Suggestion, Spec, Subcommand, Option types
  • Suggestion: Cmd, Desc, Icon, Source ("history"/"spec"/"ai"), Confidence (0-100), Priority
  • Registry: global map of spec definitions

Shell Integration

• integration/shell/ - Adapters for bash/zsh/fish
  • GetEnv: constructs shell environment with FD13 for IPC
  • RecordSessionCommand: captures executed commands

Process Lifecycle

• root/root.go:81-192 - Watchdog parent process
  • Monitors child stderr for panics/crashes
  • Restores terminal state on crash
  • Triggers rescue shell and logs to ~/.iris/crash.log

Commands

• root/config_cmd.go - iris config init/show
• root/theme_cmd.go - iris theme init
• root/uninstall.go - iris uninstall (cleanup)
• root/update.go - Background version check

Common Flows

User Types Character

1. Shell process sends query via FD13 to iris
2. wrapper.go:480-582 receives on IPC scanner
3. MergeResults scores suggestions (history or spec mode)
4. overlay.Render() outputs menu to stdout
5. Terminal displays overlay above prompt

User Presses Tab (Select Suggestion)

1. wrapper.go:813-843 intercepts Tab
2. Gets current selection from overlay
3. If spec mode: adds trailing space
4. Writes to PTY (0x15 = Ctrl+U clears, then new text)
5. Clears overlay, triggers render

User Presses Ctrl+R (Toggle Mode)

1. wrapper.go:773-795 intercepts Ctrl+R
2. Swaps activeMode between "spec" and "history"
3. Saves mode to state file for next session
4. Re-renders menu with new scoring

Terminal Resizes (SIGWINCH)

1. wrapper.go:213-215 catches signal
2. pty.InheritSize syncs PTY to new size
3. Overlay re-renders with new width

Config Reloads

1. User edits ~/.config/iris/config.toml
2. config.AutoDetectConfigChange polls, detects mtime change
3. Calls config.Load(), updates global config
4. Callback triggers overlay re-render if visible

Design Patterns

• Mutex-protected state: naiveBuffer, cursorOffset, activeMode (avoid races in goroutines)
• Atomic flags: isCommandActive, userNavigated, disableGhostText (fast checks without locks)
• Debounced rendering: 20ms timer on keystroke to batch render calls
• AI suggestions: separate debounce (400ms default), cancellable context
• Ghost text: faded hint of next completion, cleared on user navigation
• Frecency scoring: combines frequency + recency + context signals (cwd, prev command, exit code)

Comments

• NO FUNCTION COMMENTS UNLESS IT'S TOO COMPLEX TO UNDERSTAND
• NO TOP FILE COMMENTS
• NO COMMENT LONGER THAN 2 LINES UNLESS ASKED EXPLICITLY
• ONLY COMMENT WHERE IT'S IMPORTANT TO UNDERSTAND
• THE COMMENT SHOULD EXPLAIN "WHY" OR "WHY WE NEED THIS" INSTEAD OF TELLING "WHAT IT DOES"

Configuration Paths

• Config: ~/.config/iris/config.toml
• Theme: ~/.config/iris/theme.toml
• State: ~/.local/share/iris/state.toml (or XDG_DATA_HOME)
• Logs: ~/.local/share/iris/iris.log (or XDG_CACHE_HOME)
• Crash: ~/.iris/crash.log

Testing

• Test files match source: *_test.go (unit tests, no integration tests yet)
• Mocks for git provider in root/mock_git_provider_test.go
• spec/cobra_complete_test.go tests command completion

Verify

• Run just test or go test ./... -v to make sure all tests passed
• Run just lint or golangci-lint run ./... to make sure zero linter problems
• Run go vet ./... to make sure there is no suspicious constructs, structural mistakes, and high-probability bugs
• Run go fix ./... to modernize all Go code

Commits

• If the agent is the one who commits, make sure follow the conventional commits style
• The commit should be as short as possible, but enough to describe changes

---

Minimal reference for rapid navigation. Read files directly-do not fabricate code from this index.