repo-lens

repo-lens is a lightweight, agent-agnostic repository navigation and context tool. It is infrastructure that coding agents can use, not an autonomous coding agent.

Coding agents often spend expensive model context rediscovering where code lives and reading irrelevant source. repo-lens aims to perform cheap, deterministic repository queries locally and return compact, bounded results, leaving the model more room to reason about the requested change.

Status: first functional version. The native C++20 executable is named repo and implements three bounded navigation commands:

repo map process
repo find RepoLensToolFind
repo around src/main.cpp:30
repo around src/main.cpp:30 --before 10 --after 10

Run from anywhere inside a Git repository; the nearest ancestor containing .git is the root. Relative source paths are resolved from that root; absolute paths (including Windows drive letters) also work. repo and repo --help show usage.

• map queries docs/PROJECTMAP.md case-insensitively, preferring heading matches over body matches. Sections end at the next heading. Output is limited to 3 sections, 120 lines, and 16 KiB, with an explicit truncation notice.
• find requires ripgrep (rg) on PATH. It searches a non-empty, single-line literal, respects normal ignore rules, sorts paths, displays up to 20 occurrence locations, and counts all occurrences (including repeated matches on one line). It streams results without retaining the full search output. No semantic labels are inferred.
• around shows 30 lines before and after the requested line, clamped to the file. Optional counts range from 0 to 1000. Output identifies the file, target, and actual range; malformed locations, missing files, and out-of-range lines fail clearly.

No-result searches succeed. Usage/file/process errors return non-zero; ripgrep failures preserve its exit code. Subprocesses execute directly without a shell, streaming stdout and reporting up to 4096 bytes of stderr (spooled to a temporary file).

Building

Use CMake 4.0 or newer, Ninja, and a C++20 compiler. C++ exceptions are disabled; recoverable failures use explicit status returns. Presets use separate build directories under .build/<preset> and provide matching configure, build, and test commands:

cmake --list-presets
cmake --preset msvc-debug
cmake --build --preset msvc-debug
ctest --preset msvc-debug

After editing code, repeat the build and test steps; reconfigure when changing options or presets. To work in Visual Studio, open the repository folder and select a preset. Ninja does not generate a solution for cmake --open. Manual configuration with a Visual Studio generator still supports that command, using a separate build directory.

Configuration generates compile_commands.json in the build directory, for example .build/msvc-debug/compile_commands.json. Export is enabled by default for manual builds too. CMake supports this with Ninja and Makefile generators; Visual Studio solution generators do not produce it. In Visual Studio, use Open Folder with a Ninja preset when you need the compilation database.

Choose a preset for your host and compiler:

Host	Debug	Release
Linux, GCC	gcc-debug	gcc-release
Linux, Clang	clang-debug	clang-release
macOS, AppleClang	appleclang-debug	appleclang-release
Windows, MSVC	msvc-debug	msvc-release

Each compiler also has a <compiler>-sanitizers Debug preset, with matching build/test presets. It enables AddressSanitizer on MSVC and AddressSanitizer plus UndefinedBehaviorSanitizer on GCC/Clang, with undefined-behavior findings terminating the process. Configuration checks that the combination compiles and links. The executable and test target are instrumented; MSVC also instruments GoogleTest to keep STL annotations consistent. Run sanitizer tests in the same compiler developer environment used for building, so the runtime is available.

Warnings remain local to project targets. ENABLE_WARNINGS_AS_ERRORS=OFF disables their error policy; CMake's --compile-no-warning-as-error configure option also overrides it. MSVC sanitizer builds use target properties for debug information and runtime checks, leaving directory-level compiler flags unchanged.

On Windows, run these commands from an x64 Native Tools Command Prompt or Developer PowerShell for Visual Studio, with Ninja on PATH. On Linux, install the chosen compiler and Ninja; on macOS, install Xcode Command Line Tools and Ninja. Toolchain files in cmake/toolchains/ select native compilers; these presets do not cross-compile to another operating system. Local paths and overrides belong in an untracked CMakeUserPresets.json or configure arguments.

The default build includes navigation unit and integration tests and may download its build dependencies. For an application-only build without downloads, configure with -DENABLE_TESTS=OFF and skip the test step. Sanitizers are opt-in with -DENABLE_SANITIZERS=ON; static analysis and warnings retain their existing configuration options. Manual configuration with cmake -S . -B build/manual remains supported; set -DCMAKE_BUILD_TYPE=Debug for single-configuration generators.

GoogleTest is pinned to v1.18.0 and managed by CMake's built-in FetchContent. To reuse a local checkout without downloading it, configure with -DFETCHCONTENT_SOURCE_DIR_GOOGLETEST=/absolute/path/to/googletest.

CI installs CMake 4.x and runs Debug, Release, and sanitizer presets for Linux GCC/Clang, macOS AppleClang, and Windows MSVC. The inherited static-analysis helper configures Visual Studio generators; the Ninja presets do not currently run clang-tidy or Microsoft code analysis.

Installing

Build Release, then install into a directory you own (Developer PowerShell on Windows):

cmake --preset msvc-release
cmake --build --preset msvc-release
ctest --preset msvc-release
cmake --install .build/msvc-release --prefix "$env:LOCALAPPDATA/repo-lens"

This installs bin/repo.exe. Add %LOCALAPPDATA%\repo-lens\bin to your user PATH, or call the installed executable by its full path. The install does not bundle ripgrep or modify PATH; find still needs rg available.

For a Visual Studio solution build, use cmake --build build/vs --config Release followed by cmake --install build/vs --config Release --prefix "$env:LOCALAPPDATA/repo-lens". On Linux/macOS, use the matching Release preset and install its build directory with a suitable --prefix, for example "$HOME/.local".

Agent skill setup

The reusable repo-lens skill teaches agents the map -> find -> around workflow. Copy it into a target repository using this layout:

your-repository/
├── AGENTS.md
└── .agents/
    └── skills/
        └── repo-lens/
            └── SKILL.md

Codex automatically discovers .agents/skills/ directories from its current working directory up to the repository root. Personal skills can live in ~/.agents/skills/. An AGENTS.md pointer is not required for Codex discovery. See the official skill discovery documentation.

There is no universal discovery folder across all agents. The shared skill format is a named folder containing SKILL.md with name and description frontmatter; discovery paths depend on the agent. Claude uses .claude/skills/<skill-name>/SKILL.md; see the migration documentation.

For agents that follow AGENTS.md but do not scan .agents/skills/, add an explicit pointer:

- Before navigating source, read and follow `.agents/skills/repo-lens/SKILL.md`.

Alternatively, keep the file at docs/repolens/SKILL.md and point to that path in AGENTS.md; this provides repository guidance rather than automatic skill discovery. The skill supplies instructions only: repo and rg still need to be available on PATH. CMake installation currently installs the executable, not the skill.

Navigation philosophy

search -> narrow -> inspect -> expand only when necessary

Prefer symbol lookup when available for a known symbol, textual search for known text, and sparse semantic bookmarks for architectural concepts without a suitable symbol. Inspect a bounded source range or containing symbol, then expand into callers, callees, references, tests, or related code only when needed. Read whole files when justified.

The tool should primarily orchestrate proven tools such as ripgrep (rg) and Git. Later, ast-grep or optional Clang/clangd/LSP information may improve navigation. Richer tooling should enhance simpler mechanisms; repo-lens must remain useful without parsers, language servers, semantic indexes, or network access.

Results should have explicit context limits. A query with hundreds of matches should return a compact summary with total and shown counts instead of dumping every match. Semantic labels such as definitions or calls should appear only when supported by reliable evidence, not inferred with false precision from plain text matches.

Semantic bookmarks may identify stable architectural locations in source that ordinary symbols cannot express. They should be sparse and avoid duplicating easily searchable symbols; lookup should lead to a bounded source excerpt.

Two # @ai-bookmark comments currently mark build invariants: the optional test dependency boundary and MSVC sanitizer annotation alignment. Their paths are listed in the project map. Locate them with ripgrep for now; bookmark commands remain directional.

Future direction

Bookmarks, Git history/diff queries, symbol lookup, AST/clangd/LSP integration, telemetry, configuration files, and semantic search remain deferred. Only map, find, and around are implemented. The milestone measures whether route -> narrow -> inspect reduces context use; it adds no measurement infrastructure.

Scope and development

Favour simple composable commands, human-readable output, agent-agnostic interfaces, progressive disclosure, and low maintenance cost. Source code and Git remain the canonical sources of truth; there will be no separate AI changelog or persistent agent history. Decision documents should preserve otherwise hard-to-recover rationale or invariants rather than duplicate source.

Embeddings, vector databases, semantic RAG infrastructure, persistent AI memory, agent-specific SDKs, MCP dependencies, core language-server dependencies, and large repository metadata systems are deliberately out of scope unless measurements later demonstrate a real need.

Development will be incremental and benchmarked. The objective is context consumed per acceptable engineering result, not minimum token usage alone. Useful measurements include files inspected, source lines or bytes returned, tool calls, irrelevant reads, whole-file reads, build/test attempts and failures, edit/retry cycles, elapsed time, token usage where exposed, and human corrections. Results must also be assessed for correctness, architectural and coding-style fit, unnecessary changes, and human rework. Lightweight command instrumentation may support this later; it is not implemented yet.

See the project map for current repository routes and agent instructions for working expectations.