RepoLens for VS Code

Architecture documentation intelligence — right inside your editor.

RepoLens scans your repository and gives you a live view of your system architecture: modules, domains, dependencies, tech stack, and generated documentation — all in your VS Code sidebar.

Features

Architecture Explorer

A dedicated sidebar showing your project's structure at a glance:

• Project overview — file count, module count, API endpoints, pages
• Tech stack — auto-detected frameworks, languages, build tools, test frameworks
• Business domains — modules grouped by inferred domain (Auth, API, UI, etc.)

Module Browser

Browse all modules with file counts and domain tags. Click to navigate directly to the module directory.

Document Viewer

View generated RepoLens documentation grouped by audience:

Files are read from documentation.output_dir (default .repolens). That directory must stay inside the repository. The preview redacts tokens before rendering.

System Map

Visual dependency map of your modules — color-coded by domain. Open as a full webview panel for detailed exploration.

CodeLens Annotations

Inline annotations at the top of each file showing which module and domain it belongs to.

Status Bar

Live status showing module and file counts after scanning. Click to re-scan.

Commands

Generate Documentation and scaffolding do not type into a terminal. The extension starts node with the installed repolens binary and a fixed argument list (shell: false).

--quick skips the interactive wizard. CLI 1.12.4 also scaffolds init in a non-TTY session, which is how the extension runs it. --target may be an absolute directory. There is no flag for the output directory or for scan globs. Those belong in .repolens.yml and must be relative.

The extension itself runs publish and init. Its argument builder still accepts only the CLI 1.12.4 commands and flags: init, doctor, migrate, publish, demo, watch, uninstall, feedback, version, help, and --config, --target, --quick, --non-interactive, --dry-run, --force, --verbose, --help / -h, --version / -v.

repolens version prints the version and exits 0 before flag checks. Other commands exit 2 for an unknown flag or a missing --config / --target value, 1 for a runtime error or an unknown command, and 0 on success. The extension rejects unknown flags before starting the process.

Getting Started

1. Install the extension from the VS Code Marketplace (ext install repolensdox.repolens)
2. Open a project that has a .repolens.yml config (or any project)
3. With RepoLens: Scan on open left at its default, the extension scans when a workspace is open. A .repolens.yml (or .repolens.yaml) plus CLI 1.12.4+ uses the full scanner. Anything else uses the built-in scanner.
4. Click the RepoLens icon in the activity bar to open the sidebar. The status bar item uses the telescope icon and scans again when clicked.

With the RepoLens CLI (recommended)

Install @chappibunny/repolens 1.12.4 or newer in the workspace. The extension loads that package's public entry (loadConfig and scanRepo from src/index.js) and runs the repolens binary. Do not install the unscoped repolens package — it is a different project, and update checks query @chappibunny/repolens.

npm install @chappibunny/repolens@^1.12.4
npx @chappibunny/repolens init --quick

.repolens.yml paths must stay inside the repository. CLI 1.12.4 rejects:

• absolute scan.include patterns, including Windows drive paths
• .. in scan.include
• an absolute documentation.output_dir, or one that escapes the repository with ..

Use a relative glob such as src/**/*.ts and an output directory such as .repolens. The extension checks those values before publish and reports them in the output channel.

Publishers on CLI 1.12.4 are notion, markdown, confluence, and github_wiki. Markdown is what the sidebar reads. Notion, Confluence, and GitHub Wiki run inside publish when that CLI is configured. Their tokens stay in the environment. They are not passed as arguments.

CLI 1.13.0 adds the obsidian publisher. The extension treats that name as valid once 1.13.0 or newer is installed. On 1.12.x the CLI still exits with Unknown publisher: obsidian, and the extension tells you to upgrade or remove it.

On startup the extension asks the npm registry for @chappibunny/repolens (@chappibunny%2frepolens). It does not query the unscoped repolens package. The check is skipped when CI or GITHUB_ACTIONS is set.

Without the CLI

The extension includes a lightweight built-in scanner that works on any project — no additional dependencies required.

Settings

Requirements

• VS Code 1.100.0 or later
• Node.js 18+ (the CLI requires it; 22 is used in CI)
• Optional: @chappibunny/repolens 1.12.4 or newer in the workspace for the full scanner

Security

• System Map and document preview webviews set a Content-Security-Policy (default-src 'none'). Repository text is escaped before it is rendered. The system map script uses a per-render nonce.
• Generate Documentation, and Open Config when it scaffolds a file, start the CLI with node and an argument array. The extension does not send those commands through a shell, and it does not put tokens on the command line.
• CLI output and generated markdown are redacted before they are shown. Publisher credentials stay in the environment the CLI already uses; they are not written into logs.

Publishing

Marketplace publishing is tag-triggered and does not run in pull-request CI. CI runs vsce package only.

1. Create an Azure DevOps Personal Access Token with the Marketplace (Manage) scope.
2. In this GitHub repository, open Settings → Secrets and variables → Actions, and add the token as VSCE_PAT.
3. Do not commit the token, print it, or put it in the workflow file. The publish workflow reads ${{ secrets.VSCE_PAT }}.
4. Push a tag that matches v* (for example v0.2.0) to run .github/workflows/publish.yml.

That workflow installs with npm ci, lints, tests, and publishes with @vscode/vsce 4 (vsce publish). It does not run on pull requests. Pull-request CI runs vsce package and does not publish.

Marketplace id: repolensdox.repolens (listing). Earlier versions (up to 0.1.0) were published as CHAPIBUNNY.repolens-architecture; uninstall that one and install this listing.

Development

npm ci
npm run lint
npm test
npm run compile
npm run package:dry-run

npm test covers flag and path rules, secret redaction, webview content security policy, scan-result normalization, and a scan of this repo with the installed CLI. Node.js 22 is what CI uses. A fresh npm install on npm 10 can fail while resolving Vitest 4.1 optional peers. CI uses npm ci against the lockfile.

Links

• RepoLens CLI — the core tool
• npm package
• Issues

License

MIT