From 9720340880c2e663d3497d252ce3465d42b560db Mon Sep 17 00:00:00 2001
From: Dave Gaeddert <dave.gaeddert@gmail.com>
Date: Sun, 1 Feb 2026 21:34:08 -0600
Subject: [PATCH 1/2] Add self-contained DiffMinimap with internal scroll
 tracking
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The minimap now attaches its own passive scroll listener and
ResizeObserver on the scrollContainer prop, directly mutating
its viewport indicator div. This removes the forwardRef/
useImperativeHandle plumbing and the useScrollPosition hook
from CodeViewer, simplifying parent↔minimap communication.
---
 src/components/CodeViewer/DiffMinimap.tsx   | 162 ++++++++++++++++++++
 src/components/CodeViewer/HunkNavigator.tsx |  16 +-
 src/components/CodeViewer/index.tsx         |  75 ++++++++-
 src/index.css                               |  11 ++
 4 files changed, 247 insertions(+), 17 deletions(-)
 create mode 100644 src/components/CodeViewer/DiffMinimap.tsx

diff --git a/src/components/CodeViewer/DiffMinimap.tsx b/src/components/CodeViewer/DiffMinimap.tsx
new file mode 100644
index 00000000..3353c2f7
--- /dev/null
+++ b/src/components/CodeViewer/DiffMinimap.tsx
@@ -0,0 +1,162 @@
+import { useCallback, useEffect, useRef } from "react";
+import type { ReviewState } from "../../types";
+import { isHunkTrusted } from "../../types";
+import { usePrefersReducedMotion } from "../../hooks";
+
+// --- Public types ---
+
+export type HunkStatus =
+  | "pending"
+  | "trusted"
+  | "approved"
+  | "rejected"
+  | "classifying";
+
+export interface MinimapMarker {
+  id: string;
+  topFraction: number;
+  heightFraction: number;
+  status: HunkStatus;
+  isFocused: boolean;
+}
+
+interface DiffMinimapProps {
+  markers: MinimapMarker[];
+  scrollContainer: HTMLElement | null;
+  onMarkerClick: (index: number) => void;
+}
+
+// --- Helpers ---
+
+export function getHunkStatus(
+  hunkId: string,
+  reviewState: ReviewState | null,
+  trustList: string[],
+  classifyingHunkIds: Set<string>,
+): HunkStatus {
+  if (classifyingHunkIds.has(hunkId)) return "classifying";
+  const hunkState = reviewState?.hunks[hunkId];
+  if (!hunkState) return "pending";
+  if (hunkState.status === "approved") return "approved";
+  if (hunkState.status === "rejected") return "rejected";
+  if (isHunkTrusted(hunkState, trustList)) return "trusted";
+  return "pending";
+}
+
+const STATUS_COLORS: Record<HunkStatus, string> = {
+  pending: "bg-stone-500",
+  trusted: "bg-cyan-400",
+  approved: "bg-lime-400",
+  rejected: "bg-rose-400",
+  classifying: "bg-violet-400",
+};
+
+// --- Component ---
+
+export function DiffMinimap({
+  markers,
+  scrollContainer,
+  onMarkerClick,
+}: DiffMinimapProps) {
+  const viewportRef = useRef<HTMLDivElement>(null);
+  const rafId = useRef(0);
+  const prefersReducedMotion = usePrefersReducedMotion();
+
+  // Self-manage scroll tracking: attach passive scroll listener + ResizeObserver
+  // on the scrollContainer and directly mutate the viewport indicator div.
+  useEffect(() => {
+    if (!scrollContainer) return;
+
+    const update = () => {
+      const el = viewportRef.current;
+      if (!el) return;
+      const { scrollTop, scrollHeight, clientHeight } = scrollContainer;
+      const topPercent =
+        scrollHeight > 0 ? (scrollTop / scrollHeight) * 100 : 0;
+      const heightPercent =
+        scrollHeight > 0 ? Math.min(clientHeight / scrollHeight, 1) * 100 : 100;
+      el.style.top = `${topPercent}%`;
+      el.style.height = `${heightPercent}%`;
+    };
+
+    const scheduleUpdate = () => {
+      cancelAnimationFrame(rafId.current);
+      rafId.current = requestAnimationFrame(update);
+    };
+
+    // Initial measurement
+    update();
+
+    scrollContainer.addEventListener("scroll", scheduleUpdate, {
+      passive: true,
+    });
+
+    const observer = new ResizeObserver(scheduleUpdate);
+    observer.observe(scrollContainer);
+
+    return () => {
+      cancelAnimationFrame(rafId.current);
+      scrollContainer.removeEventListener("scroll", scheduleUpdate);
+      observer.disconnect();
+    };
+  }, [scrollContainer]);
+
+  const handleTrackClick = useCallback(
+    (e: React.MouseEvent<HTMLDivElement>) => {
+      // Only respond to clicks directly on the track (not on markers)
+      if (e.target !== e.currentTarget) return;
+      if (!scrollContainer) return;
+
+      const rect = e.currentTarget.getBoundingClientRect();
+      const fraction = (e.clientY - rect.top) / rect.height;
+      const maxScroll =
+        scrollContainer.scrollHeight - scrollContainer.clientHeight;
+      scrollContainer.scrollTo({
+        top: fraction * maxScroll,
+        behavior: "smooth",
+      });
+    },
+    [scrollContainer],
+  );
+
+  return (
+    <div
+      className="relative w-2 shrink-0 opacity-60 hover:opacity-100 transition-opacity cursor-pointer"
+      onClick={handleTrackClick}
+      aria-hidden="true"
+    >
+      {/* Viewport indicator — positioned via internal scroll tracking */}
+      <div
+        ref={viewportRef}
+        className="absolute left-0 right-0 bg-stone-400/25 border-y border-stone-400/50 pointer-events-none"
+        style={{ top: "0%", height: "100%" }}
+      />
+
+      {/* Hunk markers */}
+      {markers.map((marker, i) => {
+        const colorClass = STATUS_COLORS[marker.status];
+        const pulseClass =
+          marker.status === "classifying" && !prefersReducedMotion
+            ? " animate-pulse"
+            : "";
+        const focusClass = marker.isFocused ? " ring-1 ring-amber-400" : "";
+
+        return (
+          <div
+            key={marker.id}
+            className={`absolute left-0 right-0 rounded-sm ${colorClass}${pulseClass}${focusClass}`}
+            style={{
+              top: `${marker.topFraction * 100}%`,
+              height: `${marker.heightFraction * 100}%`,
+              minHeight: "2px",
+            }}
+            onClick={(e) => {
+              e.stopPropagation();
+              onMarkerClick(i);
+            }}
+          />
+        );
+      })}
+    </div>
+  );
+}
diff --git a/src/components/CodeViewer/HunkNavigator.tsx b/src/components/CodeViewer/HunkNavigator.tsx
index c8e92ff3..abc3a939 100644
--- a/src/components/CodeViewer/HunkNavigator.tsx
+++ b/src/components/CodeViewer/HunkNavigator.tsx
@@ -1,25 +1,13 @@
-import { useMemo } from "react";
 import { useReviewStore } from "../../stores";
 import { SimpleTooltip } from "../ui/tooltip";
 
 interface HunkNavigatorProps {
-  filePath: string;
+  fileHunkIndices: number[];
 }
 
-export function HunkNavigator({ filePath }: HunkNavigatorProps) {
-  const hunks = useReviewStore((s) => s.hunks);
+export function HunkNavigator({ fileHunkIndices }: HunkNavigatorProps) {
   const focusedHunkIndex = useReviewStore((s) => s.focusedHunkIndex);
 
-  // Global indices of hunks belonging to this file
-  const fileHunkIndices = useMemo(
-    () =>
-      hunks.reduce<number[]>((acc, h, i) => {
-        if (h.filePath === filePath) acc.push(i);
-        return acc;
-      }, []),
-    [hunks, filePath],
-  );
-
   // Don't render when file has fewer than 2 hunks
   if (fileHunkIndices.length < 2) return null;
 
diff --git a/src/components/CodeViewer/index.tsx b/src/components/CodeViewer/index.tsx
index 1a2a6712..0f2d508b 100644
--- a/src/components/CodeViewer/index.tsx
+++ b/src/components/CodeViewer/index.tsx
@@ -18,6 +18,7 @@ import {
 import { SimpleTooltip } from "../ui/tooltip";
 import { FileContentRenderer } from "./FileContentRenderer";
 import { HunkNavigator } from "./HunkNavigator";
+import { DiffMinimap, getHunkStatus, type MinimapMarker } from "./DiffMinimap";
 import { InFileSearchBar } from "./InFileSearchBar";
 import {
   isMarkdownFile,
@@ -51,6 +52,9 @@ export function CodeViewer({ filePath }: CodeViewerProps) {
   const setDiffIndicators = useReviewStore((s) => s.setDiffIndicators);
   const viewMode = useReviewStore((s) => s.diffViewMode);
   const setViewMode = useReviewStore((s) => s.setDiffViewMode);
+  const classifyingHunkIds = useReviewStore((s) => s.classifyingHunkIds);
+
+  const [scrollNode, setScrollNode] = useState<HTMLDivElement | null>(null);
 
   // Get the focused hunk ID if it's in this file
   const focusedHunk = allHunks[focusedHunkIndex];
@@ -221,6 +225,61 @@ export function CodeViewer({ filePath }: CodeViewerProps) {
     };
   }, [repoPath, filePath, comparison, fileHunkKey]);
 
+  // Minimap hooks — must be before early returns
+  const fileHunkIndices = useMemo(
+    () =>
+      allHunks.reduce<number[]>((acc, h, i) => {
+        if (h.filePath === filePath) acc.push(i);
+        return acc;
+      }, []),
+    [allHunks, filePath],
+  );
+
+  const handleMinimapHunkClick = useCallback(
+    (localIndex: number) => {
+      const globalIndex = fileHunkIndices[localIndex];
+      if (globalIndex !== undefined) {
+        useReviewStore.setState({ focusedHunkIndex: globalIndex });
+      }
+    },
+    [fileHunkIndices],
+  );
+
+  const totalLineCount = useMemo(() => {
+    const s = fileContent?.content;
+    if (!s) return 0;
+    let count = 1;
+    for (let i = 0; i < s.length; i++) {
+      if (s.charCodeAt(i) === 10) count++;
+    }
+    return count;
+  }, [fileContent?.content]);
+
+  const trustList = reviewState?.trustList ?? [];
+
+  const minimapMarkers = useMemo<MinimapMarker[]>(() => {
+    if (!fileContent || totalLineCount === 0) return [];
+    return fileContent.hunks.map((hunk) => ({
+      id: hunk.id,
+      topFraction: (hunk.newStart - 1) / totalLineCount,
+      heightFraction: hunk.newCount / totalLineCount,
+      status: getHunkStatus(
+        hunk.id,
+        reviewState,
+        trustList,
+        classifyingHunkIds,
+      ),
+      isFocused: hunk.id === focusedHunkId,
+    }));
+  }, [
+    fileContent,
+    totalLineCount,
+    reviewState,
+    trustList,
+    classifyingHunkIds,
+    focusedHunkId,
+  ]);
+
   if (loading) {
     return (
       <div className="flex flex-1 items-center justify-center">
@@ -615,8 +674,11 @@ export function CodeViewer({ filePath }: CodeViewerProps) {
       </div>
 
       {/* Content area */}
-      <div className="relative flex-1 overflow-hidden">
-        <div className="h-full overflow-auto scrollbar-thin bg-stone-950">
+      <div className="relative flex flex-1 overflow-hidden">
+        <div
+          ref={setScrollNode}
+          className={`min-w-0 flex-1 h-full overflow-auto bg-stone-950 ${hasChanges && !showImageViewer ? "scrollbar-none" : "scrollbar-thin"}`}
+        >
           {/* In-file search bar */}
           {inFileSearchOpen && fileContent && (
             <div className="sticky top-0 z-10 flex justify-end p-2">
@@ -651,7 +713,14 @@ export function CodeViewer({ filePath }: CodeViewerProps) {
             deleteAnnotation={deleteAnnotation}
           />
         </div>
-        {hasChanges && <HunkNavigator filePath={filePath} />}
+        {hasChanges && !showImageViewer && (
+          <DiffMinimap
+            markers={minimapMarkers}
+            scrollContainer={scrollNode}
+            onMarkerClick={handleMinimapHunkClick}
+          />
+        )}
+        {hasChanges && <HunkNavigator fileHunkIndices={fileHunkIndices} />}
       </div>
     </div>
   );
diff --git a/src/index.css b/src/index.css
index ac39af2d..5d127f63 100644
--- a/src/index.css
+++ b/src/index.css
@@ -222,6 +222,17 @@ html {
   background: var(--stone-600);
 }
 
+/* Hide scrollbar while still allowing scroll */
+/* Firefox */
+.scrollbar-none {
+  scrollbar-width: none;
+}
+
+/* Chrome/Safari/Edge */
+.scrollbar-none::-webkit-scrollbar {
+  display: none;
+}
+
 /* Button base */
 .btn {
   padding: 0.5rem 1rem;

From 3229fe6eb66e770147c6bea7d3e432095d62349f Mon Sep 17 00:00:00 2001
From: Dave Gaeddert <dave.gaeddert@gmail.com>
Date: Sun, 1 Feb 2026 21:53:36 -0600
Subject: [PATCH 2/2] Add Cmd+Click go-to-definition in code viewer

Cmd+Click on a symbol in the diff/file viewer navigates to its
definition. Uses git grep to narrow candidate files, then tree-sitter
symbol extraction to find exact matches. Single result navigates
directly; multiple results show a picker dialog.

- Rust: new find_symbol_definitions Tauri command with parallel
  tree-sitter processing
- TypeScript: SymbolDefinition type, API client method
- React: useCmdKeyHeld and useGoToDefinition hooks
- UI: DefinitionPicker dialog, Cmd+hover cursor/underline styling
  via onLineClick in @pierre/diffs
---
 review/src/sources/local_git.rs               |   2 +-
 review/src/symbols/extractor.rs               |  38 +++-
 review/src/symbols/mod.rs                     |  13 ++
 src-tauri/src/desktop/commands.rs             |  76 ++++++-
 src-tauri/src/desktop/mod.rs                  |   1 +
 src/api/client.ts                             |   7 +
 src/api/http-client.ts                        |   9 +
 src/api/tauri-client.ts                       |  11 +
 .../CodeViewer/DefinitionPicker.tsx           | 106 +++++++++
 src/components/CodeViewer/DiffView.tsx        |  29 ++-
 .../CodeViewer/FileContentRenderer.tsx        |   8 +
 src/components/CodeViewer/PlainCodeView.tsx   |  19 +-
 src/components/CodeViewer/index.tsx           |  21 ++
 src/hooks/index.ts                            |   2 +
 src/hooks/useCmdKeyHeld.ts                    |  30 +++
 src/hooks/useGoToDefinition.ts                | 207 ++++++++++++++++++
 src/types/index.ts                            |   8 +
 17 files changed, 581 insertions(+), 6 deletions(-)
 create mode 100644 src/components/CodeViewer/DefinitionPicker.tsx
 create mode 100644 src/hooks/useCmdKeyHeld.ts
 create mode 100644 src/hooks/useGoToDefinition.ts

diff --git a/review/src/sources/local_git.rs b/review/src/sources/local_git.rs
index bac12e23..329536a2 100644
--- a/review/src/sources/local_git.rs
+++ b/review/src/sources/local_git.rs
@@ -423,7 +423,7 @@ impl LocalGitSource {
     }
 
     /// Get all tracked files from git (fast, uses index)
-    fn get_tracked_files(&self) -> Result<Vec<String>, LocalGitError> {
+    pub fn get_tracked_files(&self) -> Result<Vec<String>, LocalGitError> {
         let output = self.run_git(&["ls-files"])?;
         Ok(output.lines().map(std::borrow::ToOwned::to_owned).collect())
     }
diff --git a/review/src/symbols/extractor.rs b/review/src/symbols/extractor.rs
index 9e8c531c..4298608e 100644
--- a/review/src/symbols/extractor.rs
+++ b/review/src/symbols/extractor.rs
@@ -1,6 +1,8 @@
 //! Tree-sitter based symbol extraction and hunk mapping.
 
-use super::{FileSymbolDiff, LineRange, Symbol, SymbolChangeType, SymbolDiff, SymbolKind};
+use super::{
+    FileSymbolDiff, LineRange, Symbol, SymbolChangeType, SymbolDefinition, SymbolDiff, SymbolKind,
+};
 use crate::diff::parser::DiffHunk;
 use std::collections::HashMap;
 use tree_sitter::{Language, Node, Parser};
@@ -56,6 +58,40 @@ pub fn extract_symbols(source: &str, file_path: &str) -> Option<Vec<Symbol>> {
     Some(extract_symbols_from_node(root, source, &ext))
 }
 
+/// Find all symbol definitions matching the given name in a file.
+///
+/// Searches the extracted symbols (including children) for exact name matches.
+pub fn find_definitions(source: &str, file_path: &str, symbol_name: &str) -> Vec<SymbolDefinition> {
+    let Some(symbols) = extract_symbols(source, file_path) else {
+        return Vec::new();
+    };
+
+    let mut results = Vec::new();
+    collect_matching_symbols(&symbols, file_path, symbol_name, &mut results);
+    results
+}
+
+/// Recursively collect symbols matching the given name.
+fn collect_matching_symbols(
+    symbols: &[Symbol],
+    file_path: &str,
+    symbol_name: &str,
+    results: &mut Vec<SymbolDefinition>,
+) {
+    for symbol in symbols {
+        if symbol.name == symbol_name {
+            results.push(SymbolDefinition {
+                file_path: file_path.to_owned(),
+                name: symbol.name.clone(),
+                kind: symbol.kind.clone(),
+                start_line: symbol.start_line,
+                end_line: symbol.end_line,
+            });
+        }
+        collect_matching_symbols(&symbol.children, file_path, symbol_name, results);
+    }
+}
+
 /// Recursively extract symbol definitions from a tree-sitter node.
 fn extract_symbols_from_node(node: Node, source: &str, ext: &str) -> Vec<Symbol> {
     let mut symbols = Vec::new();
diff --git a/review/src/symbols/mod.rs b/review/src/symbols/mod.rs
index 1a9e4f35..34123d11 100644
--- a/review/src/symbols/mod.rs
+++ b/review/src/symbols/mod.rs
@@ -36,6 +36,19 @@ pub struct Symbol {
     pub children: Vec<Symbol>,
 }
 
+/// A symbol definition found in the repository, with file location.
+#[derive(Debug, Clone, Serialize)]
+pub struct SymbolDefinition {
+    #[serde(rename = "filePath")]
+    pub file_path: String,
+    pub name: String,
+    pub kind: SymbolKind,
+    #[serde(rename = "startLine")]
+    pub start_line: u32,
+    #[serde(rename = "endLine")]
+    pub end_line: u32,
+}
+
 /// Maps symbols to hunks for a single file.
 #[derive(Debug, Clone, Serialize)]
 pub struct FileSymbolMap {
diff --git a/src-tauri/src/desktop/commands.rs b/src-tauri/src/desktop/commands.rs
index d475389b..520b8e93 100644
--- a/src-tauri/src/desktop/commands.rs
+++ b/src-tauri/src/desktop/commands.rs
@@ -23,7 +23,7 @@ use review::sources::local_git::{LocalGitSource, RemoteInfo, SearchMatch};
 use review::sources::traits::{
     BranchList, CommitDetail, CommitEntry, Comparison, DiffSource, FileEntry, GitStatusSummary,
 };
-use review::symbols::{self, FileSymbolDiff, Symbol};
+use review::symbols::{self, FileSymbolDiff, Symbol, SymbolDefinition};
 use review::trust::patterns::TrustCategory;
 use serde::Serialize;
 use std::collections::hash_map::DefaultHasher;
@@ -1284,6 +1284,80 @@ pub async fn get_file_symbols(
     .map_err(|e| e.to_string())?
 }
 
+#[tauri::command]
+pub async fn find_symbol_definitions(
+    repo_path: String,
+    symbol_name: String,
+) -> Result<Vec<SymbolDefinition>, String> {
+    debug!(
+        "[find_symbol_definitions] repo_path={}, symbol={}",
+        repo_path, symbol_name
+    );
+
+    tokio::task::spawn_blocking(move || {
+        let source = LocalGitSource::new(PathBuf::from(&repo_path)).map_err(|e| {
+            error!("[find_symbol_definitions] ERROR creating source: {e}");
+            e.to_string()
+        })?;
+
+        // Use git grep to quickly find candidate files containing the symbol name
+        let grep_output = std::process::Command::new("git")
+            .args(["grep", "-l", "-F", "--", &symbol_name])
+            .current_dir(&repo_path)
+            .output()
+            .map_err(|e| e.to_string())?;
+
+        let candidates: Vec<String> = if grep_output.status.success() {
+            String::from_utf8_lossy(&grep_output.stdout)
+                .lines()
+                .filter(|line| !line.is_empty())
+                .filter(|line| symbols::extractor::get_language_for_file(line).is_some())
+                .map(|s| s.to_owned())
+                .collect()
+        } else {
+            // No matches or error — fall back to all tracked files with grammars
+            source
+                .get_tracked_files()
+                .unwrap_or_default()
+                .into_iter()
+                .filter(|f| symbols::extractor::get_language_for_file(f).is_some())
+                .collect()
+        };
+
+        // Process candidate files in parallel
+        let results: Vec<SymbolDefinition> = std::thread::scope(|s| {
+            let handles: Vec<_> = candidates
+                .iter()
+                .map(|file_path| {
+                    let repo_path = repo_path.as_str();
+                    let symbol_name = symbol_name.as_str();
+                    s.spawn(move || {
+                        let full_path = PathBuf::from(repo_path).join(file_path);
+                        let content = match std::fs::read_to_string(&full_path) {
+                            Ok(c) => c,
+                            Err(_) => return Vec::new(),
+                        };
+                        symbols::extractor::find_definitions(&content, file_path, symbol_name)
+                    })
+                })
+                .collect();
+            handles
+                .into_iter()
+                .filter_map(|h| h.join().ok())
+                .flatten()
+                .collect()
+        });
+
+        info!(
+            "[find_symbol_definitions] SUCCESS: {} definitions found",
+            results.len()
+        );
+        Ok(results)
+    })
+    .await
+    .map_err(|e| e.to_string())?
+}
+
 #[tauri::command]
 pub fn search_file_contents(
     repo_path: String,
diff --git a/src-tauri/src/desktop/mod.rs b/src-tauri/src/desktop/mod.rs
index 3b3a6d96..07a9e6ad 100644
--- a/src-tauri/src/desktop/mod.rs
+++ b/src-tauri/src/desktop/mod.rs
@@ -317,6 +317,7 @@ pub fn run() {
             commands::search_file_contents,
             commands::get_file_symbol_diffs,
             commands::get_file_symbols,
+            commands::find_symbol_definitions,
             commands::generate_narrative,
         ])
         .build(tauri::generate_context!())
diff --git a/src/api/client.ts b/src/api/client.ts
index 38c72f11..05aa2314 100644
--- a/src/api/client.ts
+++ b/src/api/client.ts
@@ -27,6 +27,7 @@ import type {
   SearchMatch,
   FileSymbol,
   FileSymbolDiff,
+  SymbolDefinition,
   RemoteInfo,
   NarrativeInput,
 } from "../types";
@@ -192,6 +193,12 @@ export interface ApiClient {
     gitRef?: string,
   ): Promise<FileSymbol[] | null>;
 
+  /** Find symbol definitions across the repository */
+  findSymbolDefinitions(
+    repoPath: string,
+    symbolName: string,
+  ): Promise<SymbolDefinition[]>;
+
   // ----- File watcher -----
 
   /** Start watching for file changes in the repo */
diff --git a/src/api/http-client.ts b/src/api/http-client.ts
index 847c64e8..ebd89115 100644
--- a/src/api/http-client.ts
+++ b/src/api/http-client.ts
@@ -27,6 +27,7 @@ import type {
   SearchMatch,
   FileSymbol,
   FileSymbolDiff,
+  SymbolDefinition,
   RemoteInfo,
 } from "../types";
 
@@ -491,6 +492,14 @@ export class HttpClient implements ApiClient {
     return null;
   }
 
+  async findSymbolDefinitions(
+    _repoPath: string,
+    _symbolName: string,
+  ): Promise<SymbolDefinition[]> {
+    console.warn("[HttpClient] findSymbolDefinitions not implemented");
+    return [];
+  }
+
   // ----- File watcher -----
 
   async startFileWatcher(_repoPath: string): Promise<void> {
diff --git a/src/api/tauri-client.ts b/src/api/tauri-client.ts
index 01198cbf..76b9692d 100644
--- a/src/api/tauri-client.ts
+++ b/src/api/tauri-client.ts
@@ -29,6 +29,7 @@ import type {
   SearchMatch,
   FileSymbol,
   FileSymbolDiff,
+  SymbolDefinition,
   RemoteInfo,
   NarrativeInput,
 } from "../types";
@@ -286,6 +287,16 @@ export class TauriClient implements ApiClient {
     });
   }
 
+  async findSymbolDefinitions(
+    repoPath: string,
+    symbolName: string,
+  ): Promise<SymbolDefinition[]> {
+    return invoke<SymbolDefinition[]>("find_symbol_definitions", {
+      repoPath,
+      symbolName,
+    });
+  }
+
   // ----- File watcher -----
 
   async startFileWatcher(repoPath: string): Promise<void> {
diff --git a/src/components/CodeViewer/DefinitionPicker.tsx b/src/components/CodeViewer/DefinitionPicker.tsx
new file mode 100644
index 00000000..1fad8936
--- /dev/null
+++ b/src/components/CodeViewer/DefinitionPicker.tsx
@@ -0,0 +1,106 @@
+import { useState, useEffect, useCallback } from "react";
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogDescription,
+} from "../ui/dialog";
+import { SymbolKindBadge } from "../symbols";
+import type { SymbolDefinition } from "../../types";
+
+interface DefinitionPickerProps {
+  open: boolean;
+  definitions: SymbolDefinition[];
+  onSelect: (def: SymbolDefinition) => void;
+  onClose: () => void;
+}
+
+export function DefinitionPicker({
+  open,
+  definitions,
+  onSelect,
+  onClose,
+}: DefinitionPickerProps) {
+  const [selectedIndex, setSelectedIndex] = useState(0);
+
+  // Reset selection when definitions change
+  useEffect(() => {
+    setSelectedIndex(0);
+  }, [definitions]);
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      switch (e.key) {
+        case "ArrowDown":
+          e.preventDefault();
+          setSelectedIndex((i) => Math.min(i + 1, definitions.length - 1));
+          break;
+        case "ArrowUp":
+          e.preventDefault();
+          setSelectedIndex((i) => Math.max(i - 1, 0));
+          break;
+        case "Enter":
+          e.preventDefault();
+          if (definitions[selectedIndex]) {
+            onSelect(definitions[selectedIndex]);
+          }
+          break;
+      }
+    },
+    [definitions, selectedIndex, onSelect],
+  );
+
+  return (
+    <Dialog open={open} onOpenChange={(isOpen) => !isOpen && onClose()}>
+      <DialogContent
+        className="w-[480px] max-h-[400px] rounded-lg overflow-hidden"
+        onKeyDown={handleKeyDown}
+      >
+        <DialogHeader>
+          <DialogTitle>
+            {definitions.length} definition{definitions.length !== 1 && "s"}{" "}
+            found
+          </DialogTitle>
+          <DialogDescription>
+            {definitions[0]?.name ?? "symbol"}
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="overflow-auto max-h-[300px] py-1">
+          {definitions.map((def, index) => {
+            const fileName = def.filePath.split("/").pop() ?? def.filePath;
+            const dirPath = def.filePath.includes("/")
+              ? def.filePath.substring(0, def.filePath.lastIndexOf("/"))
+              : "";
+
+            return (
+              <button
+                key={`${def.filePath}:${def.startLine}`}
+                className={`flex w-full items-center gap-2 px-3 py-1.5 text-left transition-colors ${
+                  index === selectedIndex
+                    ? "bg-stone-800 text-stone-100"
+                    : "text-stone-300 hover:bg-stone-800/50"
+                }`}
+                onClick={() => onSelect(def)}
+                onMouseEnter={() => setSelectedIndex(index)}
+              >
+                <SymbolKindBadge kind={def.kind} />
+                <span className="font-mono text-xs font-medium text-stone-200">
+                  {def.name}
+                </span>
+                <span className="min-w-0 flex-1 truncate text-xs text-stone-500">
+                  {dirPath && <span>{dirPath}/</span>}
+                  <span className="text-stone-400">{fileName}</span>
+                </span>
+                <span className="flex-shrink-0 font-mono text-xxs tabular-nums text-stone-600">
+                  :{def.startLine}
+                </span>
+              </button>
+            );
+          })}
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/src/components/CodeViewer/DiffView.tsx b/src/components/CodeViewer/DiffView.tsx
index 74dfe964..b4a205c4 100644
--- a/src/components/CodeViewer/DiffView.tsx
+++ b/src/components/CodeViewer/DiffView.tsx
@@ -119,6 +119,10 @@ interface DiffViewProps {
   focusedHunkId?: string | null;
   /** Language override for syntax highlighting */
   language?: SupportedLanguages;
+  /** Callback for Cmd+Click go-to-definition */
+  onGoToDefinition?: (event: PointerEvent) => void;
+  /** Whether Cmd key is held (for cursor styling) */
+  cmdKeyHeld?: boolean;
 }
 
 export function DiffView({
@@ -133,6 +137,8 @@ export function DiffView({
   newContent,
   focusedHunkId,
   language,
+  onGoToDefinition,
+  cmdKeyHeld,
 }: DiffViewProps) {
   const reviewState = useReviewStore((s) => s.reviewState);
   const approveHunk = useReviewStore((s) => s.approveHunk);
@@ -426,6 +432,10 @@ export function DiffView({
       ? "none"
       : prefLineDiffType;
 
+  const cmdHoverCSS = cmdKeyHeld
+    ? "code span { cursor: pointer; } code span:hover { text-decoration: underline; }"
+    : "";
+
   const diffOptions = useMemo(
     () => ({
       diffStyle: viewMode,
@@ -437,7 +447,7 @@ export function DiffView({
       diffIndicators: prefDiffIndicators,
       disableBackground: false,
       enableHoverUtility: true,
-      unsafeCSS: fontSizeCSS,
+      unsafeCSS: fontSizeCSS + cmdHoverCSS,
       expandUnchanged: true,
       expansionLineCount: 20,
       hunkSeparators: "line-info" as const,
@@ -445,8 +455,23 @@ export function DiffView({
       tokenizeMaxLineLength: 1000, // Skip syntax highlighting for very long lines
       maxLineDiffLength: 500, // Skip word-level diff for long lines
       lineDiffType, // Adaptive based on file type/size, user preference as default
+      onLineClick: onGoToDefinition
+        ? (props: { event: PointerEvent }) => {
+            if (props.event.metaKey) {
+              onGoToDefinition(props.event);
+            }
+          }
+        : undefined,
     }),
-    [viewMode, theme, prefDiffIndicators, fontSizeCSS, lineDiffType],
+    [
+      viewMode,
+      theme,
+      prefDiffIndicators,
+      fontSizeCSS,
+      cmdHoverCSS,
+      lineDiffType,
+      onGoToDefinition,
+    ],
   );
 
   const renderHoverUtility = (
diff --git a/src/components/CodeViewer/FileContentRenderer.tsx b/src/components/CodeViewer/FileContentRenderer.tsx
index 53432654..149f07d5 100644
--- a/src/components/CodeViewer/FileContentRenderer.tsx
+++ b/src/components/CodeViewer/FileContentRenderer.tsx
@@ -32,6 +32,8 @@ interface FileContentRendererProps {
   ) => void;
   updateAnnotation: (id: string, content: string) => void;
   deleteAnnotation: (id: string) => void;
+  onGoToDefinition?: (event: PointerEvent) => void;
+  cmdKeyHeld?: boolean;
 }
 
 export function FileContentRenderer({
@@ -53,6 +55,8 @@ export function FileContentRenderer({
   addAnnotation,
   updateAnnotation,
   deleteAnnotation,
+  onGoToDefinition,
+  cmdKeyHeld,
 }: FileContentRendererProps) {
   // Markdown preview mode
   if (isMarkdownFile(filePath) && markdownViewMode === "preview") {
@@ -100,6 +104,8 @@ export function FileContentRenderer({
         newContent={fileContent.content}
         focusedHunkId={focusedHunkId}
         language={effectiveLanguage}
+        onGoToDefinition={onGoToDefinition}
+        cmdKeyHeld={cmdKeyHeld}
       />
     );
   }
@@ -122,6 +128,8 @@ export function FileContentRenderer({
       }
       onUpdateAnnotation={updateAnnotation}
       onDeleteAnnotation={deleteAnnotation}
+      onGoToDefinition={onGoToDefinition}
+      cmdKeyHeld={cmdKeyHeld}
     />
   );
 }
diff --git a/src/components/CodeViewer/PlainCodeView.tsx b/src/components/CodeViewer/PlainCodeView.tsx
index 9f26f773..c4e2c726 100644
--- a/src/components/CodeViewer/PlainCodeView.tsx
+++ b/src/components/CodeViewer/PlainCodeView.tsx
@@ -29,6 +29,10 @@ interface PlainCodeViewProps {
   onUpdateAnnotation?: (id: string, content: string) => void;
   /** Callback when deleting an annotation */
   onDeleteAnnotation?: (id: string) => void;
+  /** Callback for Cmd+Click go-to-definition */
+  onGoToDefinition?: (event: PointerEvent) => void;
+  /** Whether Cmd key is held (for cursor styling) */
+  cmdKeyHeld?: boolean;
 }
 
 export function PlainCodeView({
@@ -43,6 +47,8 @@ export function PlainCodeView({
   onAddAnnotation,
   onUpdateAnnotation,
   onDeleteAnnotation,
+  onGoToDefinition,
+  cmdKeyHeld,
 }: PlainCodeViewProps) {
   const containerRef = useRef<HTMLDivElement>(null);
 
@@ -210,6 +216,10 @@ export function PlainCodeView({
     );
   };
 
+  const cmdHoverCSS = cmdKeyHeld
+    ? "code span { cursor: pointer; } code span:hover { text-decoration: underline; }"
+    : "";
+
   return (
     <div ref={containerRef}>
       <div key={language}>
@@ -235,8 +245,15 @@ export function PlainCodeView({
             },
             themeType: "dark",
             disableFileHeader: true,
-            unsafeCSS: fontSizeCSS,
+            unsafeCSS: fontSizeCSS + cmdHoverCSS,
             enableHoverUtility: true,
+            onLineClick: onGoToDefinition
+              ? (props: { event: PointerEvent }) => {
+                  if (props.event.metaKey) {
+                    onGoToDefinition(props.event);
+                  }
+                }
+              : undefined,
           }}
         />
       </div>
diff --git a/src/components/CodeViewer/index.tsx b/src/components/CodeViewer/index.tsx
index 0f2d508b..2ddc1831 100644
--- a/src/components/CodeViewer/index.tsx
+++ b/src/components/CodeViewer/index.tsx
@@ -20,12 +20,14 @@ import { FileContentRenderer } from "./FileContentRenderer";
 import { HunkNavigator } from "./HunkNavigator";
 import { DiffMinimap, getHunkStatus, type MinimapMarker } from "./DiffMinimap";
 import { InFileSearchBar } from "./InFileSearchBar";
+import { DefinitionPicker } from "./DefinitionPicker";
 import {
   isMarkdownFile,
   detectLanguage,
   type SupportedLanguages,
 } from "./languageMap";
 import { LanguageSelector } from "./LanguageSelector";
+import { useCmdKeyHeld, useGoToDefinition } from "../../hooks";
 
 interface CodeViewerProps {
   filePath: string;
@@ -82,6 +84,16 @@ export function CodeViewer({ filePath }: CodeViewerProps) {
     SupportedLanguages | undefined
   >(undefined);
 
+  // Go-to-definition
+  const cmdKeyHeld = useCmdKeyHeld();
+  const {
+    handleGoToDefinition,
+    definitions,
+    pickerOpen,
+    closePicker,
+    navigateToDefinition,
+  } = useGoToDefinition();
+
   // Diff options popover state
   const [showDiffOptions, setShowDiffOptions] = useState(false);
   const diffOptionsRef = useRef<HTMLDivElement>(null);
@@ -711,6 +723,8 @@ export function CodeViewer({ filePath }: CodeViewerProps) {
             addAnnotation={addAnnotation}
             updateAnnotation={updateAnnotation}
             deleteAnnotation={deleteAnnotation}
+            onGoToDefinition={handleGoToDefinition}
+            cmdKeyHeld={cmdKeyHeld}
           />
         </div>
         {hasChanges && !showImageViewer && (
@@ -722,6 +736,13 @@ export function CodeViewer({ filePath }: CodeViewerProps) {
         )}
         {hasChanges && <HunkNavigator fileHunkIndices={fileHunkIndices} />}
       </div>
+
+      <DefinitionPicker
+        open={pickerOpen}
+        definitions={definitions}
+        onSelect={navigateToDefinition}
+        onClose={closePicker}
+      />
     </div>
   );
 }
diff --git a/src/hooks/index.ts b/src/hooks/index.ts
index 60aade13..a3150395 100644
--- a/src/hooks/index.ts
+++ b/src/hooks/index.ts
@@ -17,3 +17,5 @@ export {
   highlightCode,
 } from "./useHighlighter";
 export { usePrefersReducedMotion } from "./usePrefersReducedMotion";
+export { useCmdKeyHeld } from "./useCmdKeyHeld";
+export { useGoToDefinition } from "./useGoToDefinition";
diff --git a/src/hooks/useCmdKeyHeld.ts b/src/hooks/useCmdKeyHeld.ts
new file mode 100644
index 00000000..47388bc3
--- /dev/null
+++ b/src/hooks/useCmdKeyHeld.ts
@@ -0,0 +1,30 @@
+import { useState, useEffect } from "react";
+
+/**
+ * Tracks whether the Cmd (Meta) key is currently held down.
+ * Handles keydown, keyup, and blur (in case key release happens while window is unfocused).
+ */
+export function useCmdKeyHeld(): boolean {
+  const [held, setHeld] = useState(false);
+
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Meta") setHeld(true);
+    };
+    const handleKeyUp = (e: KeyboardEvent) => {
+      if (e.key === "Meta") setHeld(false);
+    };
+    const handleBlur = () => setHeld(false);
+
+    window.addEventListener("keydown", handleKeyDown);
+    window.addEventListener("keyup", handleKeyUp);
+    window.addEventListener("blur", handleBlur);
+    return () => {
+      window.removeEventListener("keydown", handleKeyDown);
+      window.removeEventListener("keyup", handleKeyUp);
+      window.removeEventListener("blur", handleBlur);
+    };
+  }, []);
+
+  return held;
+}
diff --git a/src/hooks/useGoToDefinition.ts b/src/hooks/useGoToDefinition.ts
new file mode 100644
index 00000000..51eb4aea
--- /dev/null
+++ b/src/hooks/useGoToDefinition.ts
@@ -0,0 +1,207 @@
+import { useState, useCallback } from "react";
+import { getApiClient } from "../api";
+import { useReviewStore } from "../stores";
+import type { SymbolDefinition } from "../types";
+
+// Common language keywords to ignore when Cmd+clicking
+const KEYWORDS = new Set([
+  // JS/TS
+  "if",
+  "else",
+  "for",
+  "while",
+  "do",
+  "switch",
+  "case",
+  "break",
+  "continue",
+  "return",
+  "throw",
+  "try",
+  "catch",
+  "finally",
+  "new",
+  "delete",
+  "typeof",
+  "instanceof",
+  "void",
+  "in",
+  "of",
+  "let",
+  "const",
+  "var",
+  "function",
+  "class",
+  "extends",
+  "super",
+  "this",
+  "import",
+  "export",
+  "default",
+  "from",
+  "as",
+  "async",
+  "await",
+  "yield",
+  "true",
+  "false",
+  "null",
+  "undefined",
+  // Rust
+  "fn",
+  "let",
+  "mut",
+  "pub",
+  "mod",
+  "use",
+  "struct",
+  "enum",
+  "impl",
+  "trait",
+  "where",
+  "self",
+  "Self",
+  "crate",
+  "match",
+  "loop",
+  "move",
+  "ref",
+  "type",
+  "dyn",
+  "unsafe",
+  // Python
+  "def",
+  "elif",
+  "except",
+  "lambda",
+  "pass",
+  "raise",
+  "with",
+  "nonlocal",
+  "global",
+  "assert",
+  "is",
+  "not",
+  "and",
+  "or",
+  "None",
+  "True",
+  "False",
+  // Go
+  "func",
+  "package",
+  "range",
+  "select",
+  "chan",
+  "go",
+  "defer",
+  "map",
+  "interface",
+  "fallthrough",
+  "goto",
+]);
+
+const IDENTIFIER_RE = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+
+/**
+ * Extract the word under the click from the event's composedPath.
+ * Uses composedPath() to cross shadow DOM boundaries (for @pierre/diffs).
+ */
+function getWordAtClick(event: PointerEvent): string | null {
+  const path = event.composedPath();
+
+  // Walk the composed path to find the innermost <span> with text
+  for (const el of path) {
+    if (!(el instanceof HTMLElement)) continue;
+    if (el.tagName !== "SPAN") continue;
+
+    const text = el.textContent?.trim();
+    if (text && IDENTIFIER_RE.test(text) && !KEYWORDS.has(text)) {
+      return text;
+    }
+  }
+
+  return null;
+}
+
+export interface UseGoToDefinitionResult {
+  handleGoToDefinition: (event: PointerEvent) => void;
+  definitions: SymbolDefinition[];
+  pickerOpen: boolean;
+  closePicker: () => void;
+  navigateToDefinition: (def: SymbolDefinition) => void;
+  loading: boolean;
+}
+
+export function useGoToDefinition(): UseGoToDefinitionResult {
+  const [definitions, setDefinitions] = useState<SymbolDefinition[]>([]);
+  const [pickerOpen, setPickerOpen] = useState(false);
+  const [loading, setLoading] = useState(false);
+
+  const repoPath = useReviewStore((s) => s.repoPath);
+  const navigateToBrowse = useReviewStore((s) => s.navigateToBrowse);
+
+  const navigateToDefinition = useCallback(
+    (def: SymbolDefinition) => {
+      setPickerOpen(false);
+      navigateToBrowse(def.filePath);
+
+      // Set scrollToLine to highlight the definition
+      useReviewStore.setState({
+        scrollToLine: {
+          filePath: def.filePath,
+          lineNumber: def.startLine,
+        },
+      });
+    },
+    [navigateToBrowse],
+  );
+
+  const handleGoToDefinition = useCallback(
+    async (event: PointerEvent) => {
+      if (!repoPath) return;
+
+      const symbolName = getWordAtClick(event);
+      if (!symbolName) return;
+
+      setLoading(true);
+
+      try {
+        const results = await getApiClient().findSymbolDefinitions(
+          repoPath,
+          symbolName,
+        );
+
+        if (results.length === 0) {
+          // No definitions found — no-op
+          return;
+        }
+
+        if (results.length === 1) {
+          navigateToDefinition(results[0]);
+        } else {
+          setDefinitions(results);
+          setPickerOpen(true);
+        }
+      } catch (err) {
+        console.error("[useGoToDefinition] Error:", err);
+      } finally {
+        setLoading(false);
+      }
+    },
+    [repoPath, navigateToDefinition],
+  );
+
+  const closePicker = useCallback(() => {
+    setPickerOpen(false);
+  }, []);
+
+  return {
+    handleGoToDefinition,
+    definitions,
+    pickerOpen,
+    closePicker,
+    navigateToDefinition,
+    loading,
+  };
+}
diff --git a/src/types/index.ts b/src/types/index.ts
index 3f6435b4..c35fcb63 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -411,6 +411,14 @@ export interface FileSymbolDiff {
   hasGrammar: boolean;
 }
 
+export interface SymbolDefinition {
+  filePath: string;
+  name: string;
+  kind: SymbolKind;
+  startLine: number;
+  endLine: number;
+}
+
 // API operation types
 
 export interface HunkInput {