iris-context/docs/dev/root.md

Iris central integration & event loop (root/)

The root package is the entry point and orchestration layer of Iris, handling low-level terminal PTY manipulation and the main interaction loop.

How it works

1. PTY wrapper: Starts a pseudoterminal (PTY) wrapping the user's shell (zsh, bash, or fish). Shell is selected via --shell flag, config, or auto-detected by walking /proc/<pid>/comm up the parent process tree, falling back to $SHELL, and ultimately defaulting to bash if nothing matches.
2. IO interception: Runs two pumps:
   • Output pump: Forwards shell output to terminal screen via synchronized TermWrite.
   • Input pump: Listens to keystrokes in raw mode, tracks typed characters in naiveBuffer, and triggers suggestion rendering.
3. State management: Tracks active completion mode (spec vs history). Shell-specific IPC hooks (preexec/precmd for zsh, PROMPT_COMMAND for bash, fish_postexec for fish) signal command boundaries via IRIS_CMD_STOP.

Key components

root/wrapper.go

Contains the core PTY loop:

• Sets terminal to raw mode to intercept keys like Tab, Esc, or Ctrl+C.
• Manages naiveBuffer string tracking prompt input state.
• Handles suggestion insertion when pressing Tab or Enter.

root/term_sync.go

Provides TermWrite, a thread-safe stdout wrapper using sync.Mutex to prevent screen garbling when shell output and overlay rendering overlap.

Example flow

1. User types g.
2. root captures g, appends to naiveBuffer.
3. root calls renderOverlay().
4. renderOverlay calls Lookup("g").
5. overlay renders suggestions box.
6. User presses Tab.
7. root inserts completion into prompt buffer.

Hot-reload

Iris includes an atomic hot-reload mechanism for rapid local development:

• Signal listener: The root process listens for SIGUSR1.
• Process replace: Uses syscall.Exec to replace the running binary in-place without killing the underlying PTY shell session.