repo-lens/README.md

repo-lens

repo-lens is a planned 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: early bootstrap stage. The repository contains a native C++ CLI skeleton and inherited build/test scaffolding, but navigation functionality is not yet implemented. The command-line executable is named repo.

The skeleton defines find, map, and around tool types. Argument parsing, usage output, and tool implementations remain TODOs; around is not dispatched yet. The existing test is a sample assertion, not a navigation test. C++ functions use trailing return types, and the tool interface requires checked [[nodiscard]] results and noexcept execution.

Building the skeleton

Use CMake 4.0 or newer, Ninja, and a C++20 compiler. 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 the existing GoogleTest sample test 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. Building successfully does not make the stub commands functional. 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.

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.

Directional CLI

These examples illustrate possible workflows. They are neither implemented nor a final command set:

repo map cloth
repo find ClothWorld
repo bookmarks
repo bookmark CLOTH_SOLVE
repo around src/Physics/Cloth/ClothWorld.cpp:417
repo history ClothWorld.cpp
repo diff
repo changed

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.