SightRead

A code-reading enhancer for the vibe-coding era — from a single block to the whole codebase.
Visual reinforcement so you read faster and better, AI guidance that points out what's worth reading, and route-finding that maps the code path from entry to feature.

English | 简体中文

💭 Why

Those who don't read the code cannot steer the product, cannot control the quality of the project, and cannot learn anything.

You let an agent write the code — but if you never read that code, whatever it writes has nothing to do with you. Idea is cheap, code is even cheaper these days. AI is your tool, not your master. And what still matters these days is your experience of your own adventure.

To be fair, reading or not reading the code is often not really a question — merely a choice of values. This extension offers some visual assistance to those who still want to read code, hoping it helps you read faster and smoother.

Humans are no longer the main producers of code — machines are. Reading code, understanding it and making decisions is today's bottleneck. Facing a wall of code, an LLM can lay out the big structure and framework for you, but it cannot do the close reading for you (reading the detailed code costs the same as reading the LLM's summary of it). SightRead strengthens the human ability to read itself, draping a layer of visual aids over your code (toggleable at any time) — so that, like a musician sight-reading a score, the logical picture surfaces the moment you see the code. And in v1.4.0 I made a decision that betrays this very creed: AI-assisted reading is in. But it is not one of those revolting things that chew the code up and feed it into your mouth — it only, with restraint, tells you what deserves a close read and what you can let go. The core is still: you understand the code.

✨ Features

Orthogonal features, each providing a different kind of visual assistance (see design.md §2):

• 🦴 Skeleton fold — quickly fold and unfold the existing blocks inside a function. When reading a function, fold everything first to see its large structure, then expand the blocks you're interested in and read them closely.
• 🖍️ Highlighter (marks) — for the hard-to-read, tricky blocks: swipe a highlighter mark over them first (⌘K 1–5 drop one of the five colors directly), optionally with a short note saying what the block does. Manual marks and AI guide steps are one model: the same rendering, the same Filter Marks… (hide any color or role everywhere at once), the same edit rule — an edit deletes exactly the marks it touches, the rest shift along. Two color bands to choose from (sightread.palette: vivid / soft), each with separate dark- and light-theme values.
• 🎯 Variable tint — within the context of the enclosing function, outlines the symbol under the cursor, so you can see at a glance where this variable was created and where it is used.
• 🔦 Spotlight — removes the visual noise of other functions and unrelated blocks. Click the 👁 item in the status bar and pick a level.
  1. Function — only the current function; other functions are dimmed
  2. Segment — only the current block; other blocks are dimmed
  3. Segment+Var — the current block plus the related blocks; everything else is dimmed — the mode I use the most.
  4. Off — spotlight off, the default mode.
• 🧩 Auto segmentation — splits a function into a recursive structure by blank lines + keywords, so the Segments panel can show the function's large structure; click a node to jump to that block. Next to each node, a dimmed detail text shows its condensed condition or expression (hover for the full header line). The panel follows your cursor — the segment under it gets selected, and with the spotlight on, unrelated segments dim in the panel just like in the editor.
• 🚪 Entry points — read a file starting from where the outside world calls in, instead of from line one. A CodeLens above each entry declaration reads » entry — 3 external refs; click it to peek those references. Each top-level symbol is classified by where its references live: referenced from another file → entry; referenced only within the file → no lens; no references anywhere → a dimmed suspected entry (framework hooks like activate, route handlers — or dead code). Go to Entry Point… lists every entry of the file on demand, and the Entry Points view (collapsed by default) keeps them on screen for code review — with a Module group listing the ways into the whole directory: every symbol referenced from outside it, plus barrel re-exports.
• 🧭 Trail — a sidebar view that turns your navigation into a call map, while it is open: jump to a definition and the callee appears under the function you came from; jump to a reference and the caller becomes the parent. No project scan — only the structural jumps you actually make are recorded (each one verified against the definition provider), so the structure emerges as you read. Children are ordered by call site and show the line in the caller where they are called (↙ L88, right-click → Go to Call Site to jump there); nodes whose body carries a highlighter mark are tinted in the mark's color, and the view follows your cursor — the node you are inside gets selected. The trail lives in memory only and is discarded when the window closes.
• 🤖 AI-assisted reading — the extension's optional AI layer, with one philosophy: signposts only, never a translation of the code. Three commands, all driving a coding-agent CLI you already have (claude (Claude Code), codex (Codex CLI), opencode, pi, cursor-agent, devin, aider, agy — auto-detected, custom commands configurable), headless; you log in or configure an API key yourself beforehand.
  • SightRead: Interpret Current (AI) — the code at the cursor — a function, a class, or the whole file — gets annotated in place as role-colored steps: where the main body is, what is setup / fallback / special-case handling, and why each core entity exists. The steps are ordinary marks: edit their notes, delete them one by one, filter them by role; the guide hangs under the Markers view.
  • SightRead: Find Logic Routes (AI) — type a reading goal ("how does X work?"); the agent explores the repository read-only and lays a planned route into the Trail view: a dim tree starting at the entry, ★ marking the hops that actually implement the goal, the AI's why-note on hover. The symbol under your cursor rides along in the prompt, so the goal may just say "it" ("who calls it?"). Planned hops light up as you actually read them; real jumps confirm the planned edges. Routes coexist — the goal of the route you are reading shows above the tree.
  • SightRead: Trace Back to Entries (AI) — the reverse: every entry that reaches the code under your cursor, laid out as chains converging on it (★ marks the entries). Route commands need a harness with read-only exploration — builtin for claude / codex / opencode / devin / agy, or a custom profile declaring exploreArgs; raw responses and any dropped hops are logged to the "SightRead" output channel.
• 🗂️ Sidebar — the SightRead activity-bar container holds four views: Segments (the current function's segment tree), Markers (every mark and AI guide in the workspace), Trail (the call structure you have walked, plus AI-planned routes) and Entry Points (the current file's entries plus the module's — collapsed until you review). Together they naturally cover what Outline does — where Outline lists every symbol unfiltered, SightRead shows you the real structure of the code you are actually reading.

⌨️ Commands

All commands live under the SightRead: prefix in the Command Palette. The everyday ones are also in the editor right-click menu (SightRead submenu) and on the sidebar view title bars.

View items carry their own right-click actions: marks — Edit Note and an inline delete; segments — Mark… / Mark with Note… / Fold Inside / Unfold Inside / Remove Markers; trail nodes — Go to Call Site and an inline remove.

⌨️ Default keybindings

One ⌘K chord family (Ctrl+K on Windows/Linux):

Note for Cursor users: Cursor binds bare ⌘K to inline edit, which shadows every ⌘K chord while the editor has focus — rebind Cursor's ⌘K to use these there.

⚙️ Settings

🛠️ Development

npm install
npm run compile     # type-check + lint + bundle
npm run test:unit   # fast pure-logic tests (mocha)
npm test            # full integration tests in a VS Code host

Press F5 in VS Code to launch the Extension Development Host.

• npm run watch — incremental build (esbuild + tsc type-checking in parallel)
• npm run package — production bundle

Architecture (see design.md §四): src/core/ is pure logic (segmentation, marker math, focus algebra — unit-tested, zero vscode imports); src/vs/ is the platform layer, with all decoration rendering flowing through a single compositor.