Explore Mode

Explore Mode is your semantic code browser. Navigate files, view syntax-highlighted source, and ask Iris "why does this code exist?" to get AI-powered historical analysis.

When to Use Explore Mode

• Understanding unfamiliar code: Jump into a new codebase and get oriented
• Investigating bugs: Find out why a suspicious line was added
• Code archaeology: Trace the evolution of a feature through commits
• Learning patterns: See how the codebase implements specific patterns

Panel Layout

Panel	Content
Left	File tree with git status indicators
Center	Syntax-highlighted code with line numbers
Right	Blame analysis and commit history

Left Panel: File Tree

• Shows repository directory structure
• Syntax-highlighted by file type
• Git status indicators (modified, staged, etc.)
• Collapsible directories

Center Panel: Code View

• Syntax-highlighted source code
• Line numbers
• Current line indicator
• Visual selection support
• Optional heat map (change frequency)

Right Panel: Blame Analysis

• Semantic "why" explanations (when requested)
• Related commit history
• Code evolution context
• Empty until you ask "why?"

Essential Keybindings

File Tree (Left Panel)

Key	Action
j / ↓	Select next file
k / ↑	Select previous file
h / ←	Collapse directory
l / →	Expand directory
Enter	Expand directory or load file (moves focus to code view)
g / Home	Jump to first file
G / End	Jump to last file
Ctrl+d / PgDn	Page down
Ctrl+u / PgUp	Page up

Code View (Center Panel)

Key	Action
j / ↓	Move down one line
k / ↑	Move up one line
g / Home	Jump to first line
G / End	Jump to last line
Ctrl+d / PgDn	Page down
Ctrl+u / PgUp	Page up
v	Enter/exit visual selection mode
w	Ask "why does this code exist?" (semantic blame)
y	Copy current line (or selection if in visual mode)
Shift+Y	Copy entire file content
Shift+H	Toggle heat map (shows change frequency)
o	Open in $EDITOR (shows command, doesn't suspend TUI)

Context Panel (Right Panel)

Key	Action
j / ↓	Scroll down
k / ↑	Scroll up
Ctrl+d / PgDn	Page down
Ctrl+u / PgUp	Page up

Visual Selection Mode

Press v to enter vim-style visual selection:

 42  pub fn new() {
 43    Self {                    ← Press 'v' here (anchor point)
 44      mode: EmojiMode::Auto,
 45      editing: false,
 46    }                          ← Press 'j' to extend selection
 47  }

Visual Mode Controls

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

What You Can Do with Selection

1. Copy code snippets: Select + y → paste anywhere
2. Ask about multiple lines: Select + w → Iris explains the entire block
3. Visual feedback: Selected lines highlighted in Electric Purple

Semantic Blame: The "Why?" Feature

Press w on any line to ask "why does this code exist?"

What Happens

1. Iris gathers git blame data for that line
2. Analyzes related commits
3. Reads commit messages and diffs
4. Generates a semantic explanation

Example

You press w on line 43:

 42  pub fn new() {
 43    Self {
 44      mode: EmojiMode::Auto,  ← Cursor here, press 'w'

Iris responds in the right panel:

Why does this code exist?

This initialization was added to support automatic emoji
selection in commit messages. Previously, emoji mode was a
simple boolean flag (use_gitmoji).

The change to an enum (EmojiMode::Auto) allows three states:
- None (no emoji)
- Auto (AI chooses)
- Custom (user picks)

This enables smarter defaults while preserving user control.

Related Commits:
• abc123f (2024-01-15) "Add emoji mode enum"
  Introduced EmojiMode to replace boolean flag

• def456a (2024-01-14) "Add emoji selector modal"
  Created UI for manual emoji selection

With Visual Selection

Select multiple lines, then press w:

 43    Self {
 44      mode: EmojiMode::Auto,
 45      editing: false,
 46      messages: vec![],  ← Selection from 43-46, press 'w'
 47    }

Iris explains the entire block and how it evolved together.

Heat Map

Press Shift+H to toggle the change frequency heat map:

 42  pub fn new() {               [████░░░░░░] 60% changed
 43    Self {                     [██████████] 100% hotspot!
 44      mode: EmojiMode::Auto,   [██████░░░░] 80%
 45      editing: false,          [██░░░░░░░░] 30%

• Dark/Empty: Rarely changed
• Bright bars: Frequently modified
• Red-ish hue: Very hot (changed in many commits)

What Heat Map Shows

• Lines that change frequently (potential code smells)
• Stable areas (well-tested, trusted)
• Recent churn (active development)

Useful for:

• Finding fragile code
• Identifying core vs. peripheral logic
• Spotting refactor candidates

Clipboard Integration

Copy Current Line

Position cursor, press y:

✓ Line copied to clipboard

Copy Selection

Enter visual mode (v), select lines, press y:

✓ 5 lines copied to clipboard

Copy Entire File

Press Shift+Y anywhere:

✓ File content copied to clipboard

Syntax Highlighting

Code is syntax-highlighted based on file extension:

• Rust (.rs): Keywords in Electric Purple, types in Neon Cyan
• JavaScript/TypeScript (.js, .ts, .tsx): Standard syntax colors
• Markdown (.md): Headers, links, code blocks
• TOML/YAML (.toml, .yml): Config-specific highlighting
• Plain text: Monochrome

Colors follow the SilkCircuit Neon palette.

Workflow Examples

Example 1: Understanding a New Codebase

Goal: Learn how the state management works

1. Open Studio in Explore mode
2. Navigate to src/studio/state/mod.rs in file tree
3. Press Enter to load file
4. Scan through code with j/k
5. See StudioState struct at line 789
6. Press w to ask why it exists
7. Read Iris's explanation in right panel
8. Press / to open chat: "Show me how state flows through the reducer"

Example 2: Investigating a Bug

Goal: Find out why file selection is broken

1. Navigate to src/studio/handlers/commit.rs
2. Find suspicious function sync_file_selection at line 35
3. Press v to start visual selection
4. Press j × 4 to select the function body
5. Press w to ask why this code exists
6. Iris explains: "Added to fix race condition between tree and diff views"
7. Press / to chat: "Is there a better way to sync these components?"

Example 3: Learning Code Patterns

Goal: See how the codebase uses Result types

1. Navigate to src/agents/iris.rs
2. Toggle heat map (Shift+H) to see active areas
3. Navigate to hot spots (frequently changed lines)
4. Press w on error handling code
5. Iris explains: "Added to gracefully handle JSON parse errors from LLM"
6. Copy pattern with y for reuse

Example 4: Code Review Prep

Goal: Understand changes before creating a PR

1. In Explore mode, navigate through changed files
2. For each file, press w on key changes
3. Build mental model of "why" changes were made
4. Switch to Review mode (Shift+R)
5. Generate review with full context
6. Switch to PR mode (Shift+P)
7. Generate PR description (Iris remembers your exploration)

Special Features

File Status Indicators

In the file tree, files show git status:

• Green M — Modified
• Purple A — Staged (added)
• Yellow ? — Untracked
• Cyan R — Renamed
• Red D — Deleted

Smart Navigation

• Press Enter on a directory → Expands it
• Press Enter on a file → Loads it and moves focus to code view
• No need to Tab manually

Context Persistence

When you switch modes, Explore remembers:

• Current file
• Cursor position
• Expanded directories
• Visual selection state (if any)

Return to Explore mode → pick up where you left off.

Tips & Tricks

1. Use Visual Selection for Context

Don't just ask "why" about a single line. Select the entire function/struct/block for richer explanations.

2. Heat Map + Blame Combo

1. Toggle heat map (Shift+H)
2. Navigate to hottest lines
3. Press w to understand why they change often
4. Consider refactoring high-churn areas

3. Copy Before Switching Modes

If you find useful code in Explore:

1. Select it (v + j/k)
2. Copy it (y)
3. Switch to Commit mode (Shift+C)
4. Paste into commit message if relevant

4. Chat for Deeper Dives

Semantic blame gives you "why this line." Chat gives you "how does this relate to everything else?"

• Press w for quick blame
• Press / for deep architectural questions

5. File Tree Filtering (Coming Soon)

Soon you'll be able to type in the file tree to filter:

• Type iris → Shows only files matching "iris"
• Clear filter → Back to full tree

Limitations

What Explore Can't Do

• Edit files: Read-only (use $EDITOR outside Studio)
• Show uncommitted changes: Displays HEAD version (use Commit mode for diffs)
• Navigate by symbol: No function/class jump (yet)

Performance Notes

• Large files (>10,000 lines): May scroll slower
• Binary files: Not displayed (shows placeholder)
• Very deep trees: Consider using fd or ripgrep outside TUI

Troubleshooting

"No file selected" when pressing w

You're in the file tree panel. Press Tab to move to code view, then try again.

Heat map shows all zeros

File hasn't been modified in tracked history. Try a file with recent commits.

Semantic blame takes too long

For large files or deep history:

• Select fewer lines (narrow scope)
• Use chat instead: "Why was X added?" (faster, cached)

Syntax highlighting looks wrong

Check file extension. Studio infers language from extension. Rename file or submit an issue if highlighting is broken.

Next Steps

• Learn Visual Selection techniques
• Master Chat for code questions
• Switch to Commit Mode to act on what you learned
• See Review Mode for quality analysis