Understanding code from a selected region

Developers exploring an unfamiliar repository often know which piece of code they are looking at before they know how to describe it in a search query. CodeArchitect lets them open a repository, highlight a region, ask a question, and inspect related references.

The implementation uses that selection to locate a unit of code and prepare context around it. Its central design decision is to organize retrieval around the code’s existing structure, rather than first asking a vector search to identify the region the user already selected.

One fixed tree, several levels of detail

Parsing produces a tree of code regions with character offsets, such as a file, function, or nested expression. These regions are derived from abstract syntax trees (ASTs), which represent the code’s grammatical structure. The granularity control selects how finely to divide the view, using a different cut through the same tree without rebuilding the underlying units.

Each region has two identities. A content hash identifies its exact text so identical code can reuse a basic summary. A separate path identity distinguishes where the region sits in the tree, so contextual explanations can depend on its surroundings. Keeping these identities separate avoids tying reusable summaries to a particular slider setting.

Nodes with many children are balanced with synthetic grouping regions. These let each granularity step add one chunk, but the meaning and breadcrumb traversals skip the synthetic groups: the interface needs predictable steps, while the model should still explain actual code units.

From a highlight to an answer

A highlight normally identifies the smallest region corresponding to a code unit containing the selected range. When a highlight crosses top-level units and would otherwise select the whole file, the viewer separates the overlapping units and initially selects the region at the highlight’s start. This keeps a cross-unit selection from automatically expanding the question to the entire file.

The answer path records the selected region among those explored in the current file. It forms a non-overlapping set of regions covering the file, called a frontier, and combines the selected region’s basic summary with summaries of the other frontier regions and folder context. A new selection can refine this frontier without discarding previously cached basic summaries.

The final prompt includes the selected code, its location breadcrumb, the prepared context, and the question. Follow-up requests for more detail descend into contained code units, using a separate traversal that combines each unit’s summary with context from its enclosing units. This separates the context used to answer the current question from the mechanism used to explain its subparts.

Reference inspection uses parsed identifier matches, classifying definitions, calls, and imports while excluding strings and comments. For files without a supported grammar it falls back to text search. This is name-based navigation, not scope-resolved symbol analysis; unrelated identifiers with the same name can still appear.

Reuse without sharing exploratory context

Basic summaries are content-addressed and persisted on disk. Focused summaries depend on the regions a person has explored, so they stay in that browser session’s memory. Concurrent requests for the same focused context share an in-flight computation instead of repeating the model call.

Context cache keys incorporate the file content and its folder context. Editing the file or changing its folder context produces a new context identity; changing the explored frontier produces a new focused-context key. This separates reusable source summaries from explanations that are only valid for one exploration state.

Oversized units are summarized through bounded windows and then combined. The code supplied to the answer model has a separate 48,000-character limit with an explicit truncation marker. Summary preparation and answer visibility therefore have distinct limits; a prepared summary does not mean the model received every source character.

What advance preparation changed

A dated benchmark compared cold requests with repository summaries prepared in advance. Median context-preparation time fell from 33.2 to 12.9 seconds, a 61.3% reduction across three fixed questions on one 36-file, 9.7K-line repository. An immediate repeat prepared context in 0.81 milliseconds.

Advance preparation itself took a median 18.9 seconds. These figures exclude answer generation and move preparation work ahead of the request rather than eliminating it. The current implementation leaves whole-project eager warming off by default and computes missing summaries on demand; the benchmark compares explicit cache states, not a claim that every upload runs the warmed configuration.

Context-preparation benchmark — Cache states, per-stage measurements, reproducibility details, and the limits of the three-question study.

Research into navigation by purpose

The selection-based workspace addresses a known location in the code. A separate research effort asks whether developer language can supply recognizable categories for finding code by purpose, such as configuration or testing.

The research retained 14 categories from 53 proposed groups and tested them on repository families excluded from discovery. A lower acceptance threshold increased coverage but failed the predefined human-reviewed precision requirements, so the higher threshold was retained. This is evidence about category assignment, not proof that the workspace improves developer understanding.

Category-discovery research and evaluation — The discovery method, retained categories, human review, threshold decision, and study limitations.

Implementation evidence

Tree construction and cuts — Stable region identities, balancing, and selection-to-region mapping.

Context and answer preparation — Frontier context, ancestor traversal, bounded summaries, and prompt assembly.

Cache lifecycle — Durable basic summaries and session-local focused context.

Reference inspection — Parsed identifier matching and the text-search fallback.

Cache-isolation test — Checks that focused context stays out of the durable summary log and is not reused by another session.