Navigation Patterns

Iris Studio follows vim-inspired keybindings for consistent, keyboard-driven navigation across all modes. This guide covers movement, selection, and panel focus.

Core Philosophy

Vim-like movement: hjkl or arrow keys
Context-aware actions: Keys behave intelligently based on what you're viewing
Modal focus: Different panels respond to the same keys differently
Keyboard-first, mouse fully supported: Click to focus a panel, double-click to activate items, drag in the code view to select lines, click files in the tree to load them

Movement Keys

These work in all scrollable contexts (file trees, code views, diffs, lists):

Key	Action	Context
`j` or `↓`	Move down one line/item	Universal
`k` or `↑`	Move up one line/item	Universal
`h` or `←`	Collapse directory / Previous item	Context-dependent
`l` or `→`	Expand directory / Next item	Context-dependent
`g` or `Home`	Jump to first item	Universal
`G` or `End`	Jump to last item	Universal
`Ctrl+d` or `PgDn`	Scroll down one page (~20 lines)	Universal
`Ctrl+u` or `PgUp`	Scroll up one page (~20 lines)	Universal

In file tree panels (Explore, Commit, Review):

src/
├─ agents/          ← Current selection
│  ├─ iris.rs
│  └─ tools/
└─ studio/

j/k — Move between files/directories
l or Enter — Expand directory or load file
h — Collapse expanded directory
g/G — Jump to top/bottom of tree

In code panels (Explore mode center panel):

rust

  1  pub fn handle_commit_key(...) {
  2      if state.editing {           ← Current line (highlighted)
  3          return handle_editing_key(state, key);
  4      }

j/k — Move cursor up/down by line
Ctrl+d/Ctrl+u — Page up/down
g/G — Jump to first/last line
v — Enter visual selection mode (Explore only)

In diff panels (Commit, Review, PR, Changelog, Release modes):

diff

@@ -10,6 +10,8 @@ impl CommitMode {

 fn handle_files_key(...) {
     match key.code {
+        KeyCode::Char('s') => { ... }  ← Current hunk
+        KeyCode::Char('u') => { ... }

j/k — Scroll diff line by line
[ / ] — Jump to previous/next hunk
n / p — Jump to next/previous file in diff
Ctrl+d/Ctrl+u — Page through diff

In commit lists (PR, Changelog, Release modes):

● abc123f Fix authentication bug        ← Selected
● def456a Add user settings panel
● ghi789b Update dependencies

j/k — Select previous/next commit
g/G — Jump to first/last commit
Enter — View commit details (context-dependent)

Panel Focus

Studio has three panels: Left, Center, Right. Only one has focus at a time, indicated by a bright border color (Electric Purple). Unfocused panels have dimmed borders.

Focus Control

Key	Action
`Tab`	Focus next panel (Left → Center → Right → Left)
`Shift+Tab`	Focus previous panel (reverse)

Smart Focus

Some actions automatically move focus:

File selection (Enter on file in tree) → Focus moves to content panel
Mode switch → Focus defaults to most relevant panel for that mode
- Commit: Center (message editor)
- Review/PR/Changelog/Release: Center (output)
- Explore: Left (file tree)

Visual Selection

Explore mode only: Select multiple lines for copying or analysis.

Entering Visual Mode

Press v while viewing code:

rust

  1  pub fn handle_commit_key(...) {
  2      if state.editing {           ← Anchor point
  3          return handle_editing_key(state, key);  ← Selection extends here
  4      }

Selection Controls

Key	Action
`v`	Enter/exit visual selection mode
`j`/`k`	Extend selection up/down
`y`	Copy selected lines to clipboard
`Esc`	Clear selection and exit visual mode

Selected lines are highlighted in Electric Purple (#e135ff).

Context-Specific Actions

Some keys have different meanings based on panel focus:

In File Trees (Left Panel)

Key	Action
`Enter`	Expand directory / Load file into view
`h` / `l`	Collapse / Expand directory
`s`	Stage file (Commit mode only)
`u`	Unstage file (Commit mode only)
`a`	Stage all files (Commit mode only)
`Shift+U`	Unstage all files (Commit mode only)

In Code Views (Center Panel)

Key	Action
`j` / `k`	Navigate by line
`v`	Visual selection (Explore)
`w`	Semantic blame (Explore)
`e`	Edit message (Commit)
`r`	Regenerate (Commit/Review/PR/etc.)
`y`	Copy to clipboard

In Diff Views (Right Panel)

Key	Action
`[` / `]`	Jump between hunks
`n` / `p`	Jump between files
`Ctrl+d` / `Ctrl+u`	Page through diff

Clipboard Operations

Copy content to system clipboard with y:

What Gets Copied

File Tree: File path
Code View: Current line (or selected range in visual mode)
Code View (Shift+Y): Entire file content
Message Editor: Full commit message
Review/PR/Changelog/Release: Full generated content

After copying, you'll see a success notification:

✓ Copied to clipboard

Scrolling Behavior

Automatic Scrolling

When you navigate past the visible area, the view automatically scrolls to keep your selection visible:

Visible area (20 lines)
┌─────────────────────┐
│  18  line           │
│  19  line           │
│  20  line  ← cursor │  ← Scrolls down when you press j
└─────────────────────┘

Page Scrolling

Ctrl+d and Ctrl+u move by ~20 lines (one page):

Keeps cursor in view
Overlaps a few lines for context
Works in all scrollable panels

Search & Jump

Quick Jump to File

In Explore mode:

Focus file tree (Left panel)
Start typing filename → files auto-filter (coming soon)
Navigate filtered results with j/k

Jump to Ref (Review/PR/Changelog/Release modes)

Key	Action
`f`	Select "from" ref (base branch/tag)
`t`	Select "to" ref (target branch/tag)

Opens a filterable ref selector modal.

When viewing diffs (Commit, Review, PR modes):

Hunks

A hunk is a contiguous block of changes:

diff

@@ -10,6 +10,8 @@  ← Hunk header
 existing line
+added line      ← This is hunk 1
 existing line

@@ -20,3 +22,4 @@  ← Hunk header
 another line
+another addition ← This is hunk 2

[ — Jump to previous hunk
] — Jump to next hunk

Files

When a diff contains multiple files:

diff

diff --git a/src/agents/iris.rs b/src/agents/iris.rs  ← File 1
...

diff --git a/src/studio/state.rs b/src/studio/state.rs  ← File 2
...

n — Jump to next file in diff
p — Jump to previous file in diff

When modals are open (Help, Chat, Settings, Selectors):

Key	Action
`Esc`	Close modal
`j`/`k`	Navigate options in selector modals only (refs, emoji, preset, settings list)
`↑`/`↓`	Universal navigation; the Chat modal scrolls history only with arrow keys (and PageUp/PageDown) — `j`/`k` are typed as message text
`Enter`	Confirm selection / send chat message
Text input	Type to filter (ref/emoji/preset selectors) or compose a chat message

See specific mode documentation for modal-specific keys.

1. Use Panel Focus Strategically

Start in Left panel to select files
Enter to auto-focus content panel
Tab to Right panel for diff details

2. Combine Movement Keys

g then ] — Jump to first hunk
G then [ — Jump to last hunk
v then G — Select from current to end

3. Use Smart Actions

Enter on a directory = expand it
Enter on a file = load and move focus
r anywhere = regenerate current context

4. Visual Selection Workflow

1. Press v to anchor
2. Press j/k to extend
3. Press y to copy
4. Press Esc to clear

Accessibility Notes

Keyboard-first, mouse fully supported: Every action has a keybinding, and the mouse handles click-to-focus, double-click activation, drag-to-select in code views, and file-tree clicks
Visual feedback: Active panel has bright border (Electric Purple)
Status indicators: Current line/item highlighted in selection color
Scroll indicators: ↓ and ↑ arrows show when content extends beyond view

Next Steps

See mode-specific guides for specialized keys:
Learn about Chat with Iris for command-based navigation

Navigation Patterns

Core Philosophy

Movement Keys

File Tree Navigation

Code View Navigation

Diff Navigation

List Navigation

Panel Focus

Focus Control

Smart Focus

Visual Selection

Entering Visual Mode

Selection Controls

Context-Specific Actions

In File Trees (Left Panel)

In Code Views (Center Panel)

In Diff Views (Right Panel)

Clipboard Operations

What Gets Copied

Scrolling Behavior

Automatic Scrolling

Page Scrolling

Search & Jump

Quick Jump to File

Jump to Ref (Review/PR/Changelog/Release modes)

Hunk & File Navigation in Diffs

Hunks

Files

Tips for Efficient Navigation

1. Use Panel Focus Strategically

2. Combine Movement Keys

3. Use Smart Actions

4. Visual Selection Workflow

Accessibility Notes

Next Steps

Navigation Patterns ​

Core Philosophy ​

Movement Keys ​

File Tree Navigation ​

Code View Navigation ​

Diff Navigation ​

List Navigation ​

Panel Focus ​

Focus Control ​

Smart Focus ​

Visual Selection ​

Entering Visual Mode ​

Selection Controls ​

Context-Specific Actions ​

In File Trees (Left Panel) ​

In Code Views (Center Panel) ​

In Diff Views (Right Panel) ​

Clipboard Operations ​

What Gets Copied ​

Scrolling Behavior ​

Automatic Scrolling ​

Page Scrolling ​

Search & Jump ​

Quick Jump to File ​

Jump to Ref (Review/PR/Changelog/Release modes) ​

Hunk & File Navigation in Diffs ​

Hunks ​

Files ​

Modal Navigation ​

Tips for Efficient Navigation ​

1. Use Panel Focus Strategically ​

2. Combine Movement Keys ​

3. Use Smart Actions ​

4. Visual Selection Workflow ​

Accessibility Notes ​

Next Steps ​

Navigation Patterns

Core Philosophy

Movement Keys

File Tree Navigation

Code View Navigation

Diff Navigation

List Navigation

Panel Focus

Focus Control

Smart Focus

Visual Selection

Entering Visual Mode

Selection Controls

Context-Specific Actions

In File Trees (Left Panel)

In Code Views (Center Panel)

In Diff Views (Right Panel)

Clipboard Operations

What Gets Copied

Scrolling Behavior

Automatic Scrolling

Page Scrolling

Search & Jump

Quick Jump to File

Jump to Ref (Review/PR/Changelog/Release modes)

Hunk & File Navigation in Diffs

Hunks

Files

Modal Navigation

Tips for Efficient Navigation

1. Use Panel Focus Strategically

2. Combine Movement Keys

3. Use Smart Actions

4. Visual Selection Workflow

Accessibility Notes

Next Steps