Skip to content
clarifydocPublic

About

Our vscode extension

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

ClarifyDoc for VS Code

▶ Open a live report — no install · No telemetry · no sign-in · no LLM · What leaves your machine

Which screen calls this endpoint, and which table does it write? ClarifyDoc answers that for any codebase, straight from the source, without leaving your editor.

Open a repo you didn't write and ClarifyDoc traces the chains the app actually runs: button click → handler → HTTP call → backend route → service → database table. It follows them across languages, tiers and repos, then puts the answers where you work: in the editor, in an interactive report, and in your AI agent.

A tour of the ClarifyDoc report on the RealWorld Conduit app: the architecture, the data model, screens and their handlers, a call traced from the UI through PUT /user to the User table, and blast radius

Screen   Checkout · "Place order" click           CheckoutPage.vue
Handler  onSubmit() → orderService.create()       CheckoutPage.vue
API      POST /api/orders                         OrdersController.cs
DI       IOrderService → OrderService             Program.cs
Entity   Orders · INSERT (+ OrderLines)           OrderService.cs

One trace, simplified. Every hop links to its file and line.

Get started in a minute

  1. Install the extension — from the Marketplace, or from Open VSX for Cursor, Windsurf and VSCodium.
  2. Run ClarifyDoc: Analyze Workspace from the Command Palette or the ClarifyDoc sidebar.
  3. The interactive report opens beside your code, and CodeLens, hovers and the Problems panel fill in.

No account, no Node.js install, no configuration. The analyzer ships inside the extension.

What do you want to know?

Find your question. The row says where the answer is: in the editor, in the report, or in what your AI agent calls.

You want to know In the editor In the report Your agent calls
New to the codebase
Where is the backend for this fetch / axios call? F12 on the call's URL Call Traces clarifydoc_routes
Which screens call this endpoint? Shift+F12 on the route, or its CodeLens Routes clarifydoc_routes
Which tables does this screen read and write? Right-click → Screens & UI for This File Screens & UI, Data Flows clarifydoc_data_flows
What does this function do, step by step? Click its complexity lens: Show Control Flow clarifydoc_extract
How is the system put together? Create Architecture Diagram Architecture, Data Model clarifydoc_architecture
Changing or reviewing code
What breaks if I change this file? Right-click → Blast Radius for This File Blast Radius clarifydoc_blast_radius
What does my diff reach: screens, routes, tables, tests? The ClarifyDoc Impact view in Source Control clarifydoc_impact
Does this branch break the API? Compare API Surface with the Base clarifydoc_diff
Which lines does no test run? Toggle Coverage Overlay (reads your coverage report)
Owning, auditing or modernizing a system
Which calls reach no route, and which routes does nothing call? Hover on the call Routes clarifydoc_routes with gaps
What is dead, risky or too complex? The Problems panel Health, Complexity clarifydoc_health
What is in it, for an audit: routes, tables, packages, findings? Export Security Findings as SARIF Routes, Data Model, Dependencies clarifydoc_export

What you get

Follow a click all the way to the database

Screens & UI and Call Traces link each screen, button and handler to the API it calls, the backend route that answers, and the table it reads or writes. Frontend HTTP calls are matched to backend routes by method and path, even when the two live in different repos or languages. Calls through dependency injection resolve to the class the container actually builds (MS DI, Spring, NestJS, Laravel, FastAPI Depends and more), not just to the interface.

Know what breaks before you change it

Blast Radius lists every file a change reaches, with the most tightly coupled first. The ClarifyDoc Impact view in Source Control turns your uncommitted diff into the screens, routes, entities and tests it affects, with a risk level and the docs that name what you changed, and keeps it current as you work, so you can check before you open the PR. A caller the editor already reports an error at is marked, so the ones your change has broken stand out from the ones still to check. Compare with a branch and Compare API Surface lists what the branch changes in the API itself — a route removed or moved, a guard lost, a request body that now requires a field, a call that no longer reaches its route — breaking first.

Answers in the editor, where you're reading

  • From a call to its route, and back. Go to Definition (F12) on an API call's URL opens the backend route that serves it, in whichever language and project it lives. Find References (Shift+F12) on a route lists the calls that reach it.
  • CodeLens above every function: callers, callees, complexity and Traces. Click to jump. Classes get a references lens; routes show method + path → handler, then who calls them, from which screens, and what they read and write (1 caller · 2 screens · writes Order).
  • Hover cards with complexity, callers/callees and findings; on a call, the route it reaches (or why it reaches none); on a route, the path to its data.
  • Call and type hierarchies across tiers: a controller action's incoming calls are the frontend functions that call its route. Used where no language extension provides a hierarchy.
  • Go to Symbol in Workspace (Ctrl+T) finds routes by URL, screens by name or route, and entities by name.
  • Show Control Flow: click the complexity lens to see the function drawn as a flowchart. Click a node to jump to its line.
  • Neighbourhood in the ClarifyDoc sidebar: the open file's functions, the calls between them, what calls in and what they call out to, and the routes it serves or calls, redrawn as you switch files, with the function under the cursor outlined. Click a node to open it.
  • Problems panel: security findings (with their CWE and the routes that reach them), overly complex functions and layer violations, at their exact lines, with quick fixes. They follow their line while you edit. Dead code can be shown as faded text too.
  • Right-click any file → ClarifyDoc to open its screens, traces or blast radius in the report.
  • Go to…: fuzzy-jump to any route, screen, issue or hotspot.

See the whole system

The report has twelve tabs: Screens & UI, Call Traces, Architecture (with a Data Access mode), Data Model (ER diagram), Routes, Data Flows, Health, Blast Radius, Complexity, Insights, Dependencies and Overview. Click a file or symbol in the report and the source opens beside it. The report is one self-contained report.html, so you can open it in a browser or send it to someone who doesn't have VS Code.

Create Architecture Diagram draws the system from the analysis in one command — no model, no prompt, so the same code draws the same diagram — and saves it as Mermaid, Markdown or SVG to commit beside the code. A route's CodeLens draws what it does as a sequence diagram.

Find what's dead, risky or tangled

Health grades the project and lists security issues, complexity hotspots, patterns, suggestions and dead code: files that no entry point reaches, and exports that nothing imports. The dead-code check is tuned for precision, so a file that might still be used is left off the list.

Give your AI agent the real map

Copilot's agent mode picks up the analysis automatically over MCP, with no setup. For Claude Code, Cursor, Windsurf, Gemini CLI, Codex or Claude Desktop, one command writes the config. Your agent can then ask which routes exist, who calls a function, what a change breaks and which table an endpoint writes, and gets answers with path:line references instead of guessing from a few open files. One more command adds a short section to AGENTS.md (or a Copilot instructions file or Cursor rule, when the project has those instead) telling the agent when to use these tools instead of searching text, and Ask an AI Agent… starts a ready-made workflow (before changing an endpoint, explain a screen's data, review your branch) from where your cursor is. Details below.

Why you can rely on it

  • Deterministic. The map comes from tree-sitter parsing and pattern-based static analysis. No LLM is involved, so the same code always gives the same map.
  • Local. Nothing is uploaded and nothing is sent to a model. No account, no telemetry.
  • Honest about uncertainty. Every cross-file link is tagged extracted, inferred or ambiguous, so you know which ones to double-check.
  • Fast on re-runs. Files are tracked by content hash and only changed files are re-analyzed. Turn on Analyze on save to keep the map current while you work.
  • Hands off your source. The analyzer only reads your files and writes to a single self-ignoring .clarifydoc/ folder.
  • MIT licensed.

Languages and frameworks

50+ languages, mixed freely in one workspace, with the templates, schemas, API

contracts and deployment files around them. A Delphi client, a .NET service and a React frontend are analyzed as one graph — and so is a folder holding several repositories, whose calls are joined across them.

Area Languages
Web TypeScript, JavaScript, React, Vue, Svelte, Angular, CoffeeScript, HTML, SCSS / Sass / Less
JVM Java, Kotlin, Scala, Groovy, JSP, Spring XML
.NET C#, F#, VB.NET, Blazor, XAML
Backend & scripting Python, PHP, Ruby, Go, Rust, Perl, Raku, Lua, Elixir, Erlang, Crystal, Haxe
Functional Haskell, OCaml, Clojure, Racket, Scheme, Common Lisp
Native C, C++, CUDA, Objective-C, Swift, Zig, Nim, D, V, Qt (QML, .ui)
Mobile Dart / Flutter, Expo Router, React Navigation, Jetpack Compose, Room, SwiftUI, SwiftData / Core Data, storyboards
Science & numeric R, Julia, Fortran, Mojo
Legacy & shell Delphi / Pascal (incl. DFM forms), VB6, VBScript, PowerShell, Bash, Windows batch
Desktop automation AutoHotkey, AutoIt, AppleScript
Data & API contracts SQL, Prisma, OpenAPI, GraphQL, Protocol Buffers, WSDL, JSight
Deployment Docker Compose, Dockerfiles, Kubernetes, Helm, Argo CD / Flux, Terraform, Serverless / AWS SAM, AWS CDK, CI pipelines

Routes come from Express, NestJS, Next.js, ASP.NET, Spring, Django, FastAPI, Flask, Laravel, Rails, Gin, Actix, Axum and others. Tables come from ORMs such as EF Core, Hibernate / JPA, TypeORM, Sequelize, Mongoose, Prisma, SQLAlchemy, Django ORM, Eloquent, Doctrine, ActiveRecord, GORM and Diesel, as well as from plain SQL.


How it runs

The analyzer is bundled inside the extension and runs in an isolated child process:

  • No external analyzer. No global install, no npx download, no dependency on a repo checkout. The CLI and all its tree-sitter WASM grammars ship in the VSIX.
  • No Node.js required. It uses node from your PATH if present, otherwise falls back to VS Code's own runtime, so it works out of the box.
  • Your source files are never modified. The analyzer only reads them. What it writes goes to one directory, .clarifydoc/ in the project (see below).
  • Remote & trust aware. It runs on the remote/WSL/Codespaces host, requires a trusted workspace to analyze, and declines virtual workspaces.

Where the analysis lives

<project>/.clarifydoc/<name>/ holds project-summary.json, report.html and the per-file JSON. That location is deliberate: it is exactly where clarifydoc analyze writes and where clarifydoc mcp looks, so any AI agent opened on your project finds the map with no configuration, and a CLI run shares one copy — and one incremental cache — with this extension.

It stays out of your way:

  • Invisible to git. The analyzer drops a .gitignore containing * inside that directory, so it ignores itself. Nothing shows up in git status, and your own .gitignore is never touched. (Want to commit the map so teammates and CI agents get it without scanning? Empty that file — it is only written when absent.)
  • Invisible to search. VS Code's search and Quick Open honour ignore files, so the report never turns up in results.
  • Never analyzed. .clarifydoc/ is excluded from discovery, so a scan cannot eat its own output.

Prefer the project tree completely untouched? Set clarifydoc.storage to global and everything goes to the extension's private storage (<globalStorage>/analyses/…) instead. That also happens automatically when the workspace is read-only.

Excluding code from the map

Put a .clarifydoc/ignore file next to the analysis and list what to leave out, in ordinary gitignore syntax — patterns relative to the project root, ! to re-include, # for comments:

# Vendored third-party source: Delphi has no package manager, so component
# libraries live in the tree — their demos and tests are not this project.
/Library/mORMot-master/*

# …but keep our own patched fork.
!/Library/mORMot-master/OurFork/**

Ignored files are not analyzed at all: they contribute no symbols, screens, data sources or tables, and the directory is also skipped by framework and sub-project detection — so vendored code stops diluting the report, the health score and the MCP answers.

A .clarifydocignore at the project root works too; both files are inherited from parent directories, and .clarifydoc/ignore is read second in each directory so it has the final say.

The quickest way in: right-click a folder in the Explorer → Ignore Folder in ClarifyDoc. It appends the folder (anchored, /path/to/folder/) to the workspace's .clarifydocignore, which you can commit so the CLI and your team skip it too. An ignored folder is not even walked, so a large tree of clones, stored data or generated files stops slowing every analysis.

AI agents (MCP)

The extension publishes the workspace analysis as a Model Context Protocol server, so Copilot's agent mode can ask ClarifyDoc for routes, call traces, blast radius, the data model and the impact of the current diff — grounded in parsed code, with path:line references — instead of inferring it from a few open files.

  • Zero configuration in this editor. One server per workspace folder, pointed at the analysis this extension already produced.

  • One command for other agents. Run ClarifyDoc: Set Up MCP for an AI Agent… and pick Claude Code, Cursor, Windsurf, Gemini CLI, Codex or Claude Desktop — it writes that agent's config for you, merging into whatever is already there. (Copy MCP Server Config still puts the snippet on your clipboard for anything else.)

  • Configs that keep working. They point at a launcher in the extension's storage whose path never changes, not at the version-stamped extension directory — so an extension update cannot silently break your agent. It also carries the Node runtime, so the agent needs no Node install of its own.

  • Nothing to point at a path. Because the analysis lives in the project, the entry is just a command:

    { "mcpServers": { "clarifydoc": { "command": "<globalStorage>/bin/clarifydoc-mcp" } } }

    The server serves whichever project its working directory sits in, walking up to the project root — so one user-level entry covers every repo you open.

  • Read-only by default, but never a dead end. Agents read the latest analysis and cannot re-scan unless you turn on clarifydoc.mcp.allowAnalyze. A project with no analysis at all is analyzed once, on demand, so an agent is useful immediately; a directory lock keeps that run from colliding with one started here or from the CLI. Turn the whole thing off with clarifydoc.mcp.enabled.

23 tools, all read-only but two (`clarifydoc_analyze` and `clarifydoc_diff`,

which write only to .clarifydoc/): clarifydoc_status, clarifydoc_search, clarifydoc_routes, clarifydoc_contract, clarifydoc_services, clarifydoc_screens, clarifydoc_file, clarifydoc_trace, clarifydoc_extract, clarifydoc_blast_radius, clarifydoc_data_model, clarifydoc_data_flows, clarifydoc_health, clarifydoc_architecture, clarifydoc_context_docs, clarifydoc_impact, clarifydoc_control_flow, clarifydoc_sequence, clarifydoc_diff, clarifydoc_export, clarifydoc_facts, clarifydoc_analyze, clarifydoc_explain.

Commands

All under the ClarifyDoc category in the Command Palette:

Command What it does
Analyze Workspace Analyze a folder (incremental by default)
Analyze Workspace (Full Re-scan) Ignore the incremental cache
Open Report Show the interactive report (editor or browser)
Open Report in Browser Force the external browser
Screens & UI / Call Traces / Blast Radius for This File Right-click jump, file preselected
Show in Architecture / Show Routes Right-click jump to that tab
Show Control Flow Draw the function under the cursor as a flowchart
Create Architecture Diagram Draw the system as a diagram to save and commit (Mermaid, Markdown, SVG)
Show a Route as a Sequence Diagram What a route does, in order: calls, data, hops to other services
Show in a Graph The selected files with their functions, calls in and out, and the routes they serve or call
Go to… Quick-pick a route / screen / issue / hotspot and jump to it
Detect Languages & Frameworks Quick detection only
Impact of Current Git Changes as Markdown Diff → affected screens/routes/entities, as a document (the Source Control view shows it live)
Compare Impact With… The impact of everything since a branch or tag you pick, not just uncommitted changes
Copy Impact for Agent The impact, function by function, ready to paste to an agent
Compare API Surface with the Base What the branch changes in routes, guards and bodies — breaking first
Resolve Calls with the Editor's Language Servers Run layer 2 now through the language extensions you have (no Docker)
Toggle Coverage Overlay Mark the lines no test runs, from your coverage report
Export Security Findings as SARIF Write the findings as SARIF 2.1.0, without re-analyzing
Ask an AI Agent… Start an agent workflow, filled in from where your cursor is
Tell AI Agents When to Use ClarifyDoc (AGENTS.md) Add or update the guidance section, after showing a diff
Set Up MCP for an AI Agent… Write the MCP config for Claude Code / Cursor / Windsurf / Gemini CLI / Codex / Claude Desktop
Copy MCP Server Config Put the MCP config on the clipboard for any other agent
Show Output Log Reveal the ClarifyDoc output channel
Bookmark This View / Open Bookmark Save a report view and come back to it
Report an Issue Open an issue prefilled with versions, settings and what the analysis could not see
Help: What ClarifyDoc Does What you get, every right-click menu (with a button that runs each entry) and what each button in the report does. Also in the Analysis view's … menu, and ? on the report's title bar

Settings

Setting Default Description
clarifydoc.storage workspace workspace (.clarifydoc/ in the project, self-ignoring) or global (extension storage)
clarifydoc.diagnostics.enabled true Show findings in the Problems panel
clarifydoc.diagnostics.include security, complexity, layers Categories; add deadCode for unused exports and unreachable files as faded text
clarifydoc.diagnostics.complexityThreshold 15 Flag functions at/above this complexity
clarifydoc.codeLens.enabled true CodeLens above functions, classes and routes
clarifydoc.hover.enabled true ClarifyDoc hover cards
clarifydoc.crossTier.enabled true Go to Definition from API calls to routes, Find References on routes, and the route CodeLens/hover
clarifydoc.incremental true Reuse cache for unchanged files
clarifydoc.enableLsp false Layer-2 LSP enhancement (needs Docker)
clarifydoc.editorLsp.enabled true Layer 2 through the editor's own language servers after each analysis (no Docker)
clarifydoc.editorLsp.maxQueries 2000 Definition questions per pass over the editor's language servers
clarifydoc.lspTimeout 0 LSP startup timeout (ms; 0 = analyzer default)
clarifydoc.gitHistory true Collect git churn / hotspots
clarifydoc.maxFiles 0 Cap files analyzed (0 = unlimited)
clarifydoc.includeGlobs [] Extra include globs
clarifydoc.excludeGlobs [] Extra exclude globs
clarifydoc.openReportAfterAnalyze true Auto-open the report after analysis
clarifydoc.reportLocation editor editor (webview) or browser
clarifydoc.analyzeOnSave auto Re-analyze shortly after source files change on disk — saves, branch switches, generated files. Runs quietly; an open report is refreshed. auto is on where the folder's last analysis took 5 s or less (a second after a save on a small one); on / off force it
clarifydoc.mcp.enabled true Publish the analysis to AI agents over MCP
clarifydoc.mcp.allowAnalyze false Let an agent trigger a re-analysis
clarifydoc.nodePath (auto) Node.js executable to run the analyzer
clarifydoc.cliPath (bundled) Advanced: override the bundled analyzer

Support

License

MIT

About

Our vscode extension

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages