Skip to content
clarifydocPublic

About

No description, website, or topics provided.

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Repository files navigation

ClarifyDoc

Extract a structured, versioned map of any codebase — frontend route → API endpoint → database — straight from source, no AI required.

ClarifyDoc parses a repo (or a folder of repos) with tree-sitter / regex extractors and produces per-file JSON plus a project-wide summary: routes, call traces, data access, an entity-relationship model, dependency and blast-radius graphs, and an interactive HTML report. Everything it extracts is content-hashed so you can tell exactly what changed between runs.

For AI agents, clarifydoc mcp serves the same map over the Model Context Protocol. Claude Code, Cursor, Copilot, Codex and other MCP clients can then ask who calls this endpoint?, which tables does this screen write? or what breaks if I change this file?, and get short answers with path:line references instead of reading whole files. Connecting it takes one line, for example claude mcp add clarifydoc -- npx -y clarifydoc mcp — see MCP server for every tool and client.

Install: npm install -g clarifydoc, or npx clarifydoc without installing — on npm. Documentation: CLI reference — every command and option · Reading the output — what each file holds, how it is encoded, and how to query it.

Why

The goal is to answer questions like "which screen calls this endpoint, and which table does that endpoint write to?" — across a monolith or multiple repositories — without reading the code by hand. ClarifyDoc builds the chain:

Screen / Route  →  handler / service  →  API call / ORM query  →  Entity / Table
   (UI tab)         (Call Traces)         (Data Access)            (Data Model)

What it looks like

A tour of the ClarifyDoc report on an open-source web 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

The report clarifydoc analyze --html writes, on an open-source web 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.

Install

npm install -g clarifydoc   # or run it without installing: npx clarifydoc analyze ./my-app --html

From a checkout:

npm install
npm run setup
npm run build

npm run setup builds the Pascal, Kotlin, Swift, Dart and Scala tree-sitter grammars, the only five whose packages ship C sources instead of a usable WASM — it needs Docker running (for emscripten) and takes about a minute. Skipping it leaves Pascal/Delphi and Kotlin parsing broken, and Swift, Dart and Scala read by their regex patterns only. .npmrc sets ignore-scripts, since the grammar packages' native node-gyp builds are never loaded by the WASM parser.

npm run build produces dist/cli.js, which is what the clarifydoc bin points at — it must exist before any of the invocations below.

Run with npx

No install or clone is needed at all:

npx clarifydoc analyze ./my-app --html   # always the latest published version
npx clarifydoc@0.12.1 analyze ./my-app   # pin a version (recommended in CI)
npx --yes clarifydoc report ./.clarifydoc/my-app   # --yes skips the install prompt in CI

When working against a local checkout, point npx at the clone instead — it resolves the package from the folder and runs the same bin:

# from inside the repo root
npx . analyze ./my-app --html

# from anywhere, using the path to the clone
npx /path/to/clarifydoc analyze ./my-app --html

The published package carries every grammar as WASM in dist/grammars/ (copied there by the build) and depends only on four pure-JS packages — the grammar packages are devDependencies — so installing it runs no install script, compiles nothing and needs no Docker. npm publish lints, builds and refuses a package missing a grammar first (prepublishOnly; run npm run setup before it), and npm run smoke:tarball -- <file.tgz> installs a packed tarball into an empty directory and checks that every grammar loads and the MCP server answers.

For a persistent clarifydoc command on your PATH during development, use a link instead of npx:

npm link        # once, inside the repo root
clarifydoc analyze ./my-app --html

Every clarifydoc <command> example in this README works with any of these forms — just replace clarifydoc with npx clarifydoc, npx ., or the linked command.

Usage

Analyze a project

clarifydoc analyze <path> [options]

Output is written to <output>/<project-name>/ (default .clarifydoc/<project-name>/, with <output> resolved against the current directory). What each file in it holds is described in Reading the output.

When that directory is inside the project, ClarifyDoc writes a .gitignore containing * into it, so the analysis ignores itself — nothing appears in git status and your own .gitignore is never touched. Empty that file to commit the analysis instead, so teammates and CI agents get the map without scanning; it is only written when absent. .clarifydoc/ is also excluded from discovery, so a scan never eats its own output.

Option Description Default
-o, --output <dir> Output directory .clarifydoc
--include <globs...> Analyze only files matching these patterns (replaces the default set) all supported
--exclude <globs...> Additional file patterns to exclude —
--max-files <n> Max files to analyze unlimited
--pretty / --no-pretty Pretty-print JSON --pretty
--verbose Show per-step progress false
--dry-run List files without analyzing false
--no-lsp Disable LSP-based symbol resolution LSP on
--lsp-timeout <ms> LSP server startup timeout —
--incremental Reuse cached analysis for unchanged files (mtime + SHA-256) false
--no-git-history Skip git churn/hotspot collection history on
--stable-output Fixed timestamp + relative root, for byte-identical committed analyses false
--html Generate + open an HTML report afterwards false
--osv Check each installed package version (from its lockfile, or an exact declared version) against OSV and record known advisories — the analysis's only network call off
--sarif <file> Also write the findings as SARIF 2.1.0 — for GitHub code scanning: security (one rule per category, tagged with its CWEs), request-contract mismatches, API calls that reach no route (a refused method is an error, and the message names the route that does exist), imports a team rule or the layer order forbids, performance findings (a warning where a request pays for them) and dead code (notes) —
--progress json Progress for a program: one JSON event per line on stderr — {"event":"stage","stage":"analyze","filesTotal":120}, {"event":"files","done":60,"total":120}, {"event":"step","stage":"advanced","label":"Finding unreachable code"}, {"event":"done","ms":5300,"files":118} — instead of the status line. Stage ids: discover, detect, analyze, link, lsp, advanced, packages, write —
--junit <file> / --codequality <file> The same findings as a JUnit XML report (one test case per rule) or a GitLab Code Quality report —
--fail-on <gate> Exit with code 2 when a finding matches — the CI gate. A level (error, warning, note), finding categories (security, contract, route-miss, architecture, performance, dead-code, or a rule id such as sql-injection), or both: --fail-on contract,route-miss, --fail-on security,error —
--baseline <sarif-or-dir> The base's findings — its SARIF, or its analysis directory. Each finding is marked new or unchanged (by a fingerprint that survives moved lines), and --fail-on counts only new ones —
--import-sarif <files...> Join other tools' SARIF (Semgrep, CodeQL, gosec, Bandit…) to the map: each finding on an analyzed file gets the routes that reach it; they stay out of --sarif and the health grade —
--spec <files...> API specs outside the tree — an OpenAPI document the backend publishes — read beside the code (as @spec/<name>), so a frontend-only repository's calls link to the operations they reach and the rest show as gaps. specs in .clarifydoc/config.json adds more —
--coverage <files...> Test coverage reports to join to the map — lcov, Cobertura (and coverage.py's XML), JaCoCo, Clover, Go coverprofile, coverage.py's JSON and its .coverage data file — matched to the analyzed files by path suffix, so a report written in CI joins. Without it, the usual paths are tried at the root and each sub-project (coverage/lcov.info, coverage.xml, target/site/jacoco/jacoco.xml, coverage.out, coverage.json, .coverage, …). Per file and function in testCoverage; a file no test runs gets an uncovered risk reason, and impact lists the changed functions no test runs. A report that keeps which test ran a line — per-test lcov (TN:), coverage json --show-contexts or a .coverage recorded with --cov-context=test (read through node:sqlite, Node 22.13 or later) — also names, per function, the tests that ran it: impact lists those first as measured and runs them auto
--history-secrets Also read every commit's added lines (all branches) for credentials — cloud keys, tokens, private key blocks, a password in a connection URL — reported masked, at the commit that introduced them. One deleted from the tree is still in every clone: clarifydoc_health lists those first, to rotate. Test files and lockfiles are left out off

All options, with examples: CLI reference → analyze.

# Analyze a React app and open the report
clarifydoc analyze ./my-app --html

# Re-run, reusing unchanged files
clarifydoc analyze ./my-app --incremental

# Only TypeScript, capped at 50 files, compact JSON
clarifydoc analyze ./my-app --include "**/*.ts" "**/*.tsx" --max-files 50 --no-pretty

Other commands

clarifydoc impact <path>               # What changed files reach: screens, routes, entities, tests to run
clarifydoc diff <base> <head>          # What changed in the API surface (and the import cycles introduced) between two analyses; --fail-on breaking
clarifydoc lsp-update <analysis-dir>   # Resolve more calls with real language servers (Docker) on an existing analysis
clarifydoc report <analysis-dir>       # (Re)generate the HTML report from project-summary.json
clarifydoc cfg <file> -f <function>    # Draw one function's control flow as Mermaid
clarifydoc seq <path> --route "POST /x" # Draw what a route does, in order, as a Mermaid sequence diagram
clarifydoc cfg <file> --slice <line>   # What can affect the values used at that line (backward slice)
clarifydoc detect <path>               # Print detected languages + frameworks only
clarifydoc lint <outputDir>            # Check an analysis for contradictions in its own facts (exit 1 on any)
clarifydoc schema                      # Print every field of the per-file JSON and project-summary.json
clarifydoc export <path>               # The analysis as ARCHITECTURE.md, DATA-MODEL.md, FLOWS.md, openapi.json, sbom.cdx.json, Mermaid, GraphML, Cypher, CSV, an Obsidian vault (--format obsidian), linked screen specs with user flows and story drafts (--format screens)
clarifydoc facts <path> --check doc.md  # Check the fact IDs a document cites ([R-3fa2c1]) against the analysis
clarifydoc mcp [path]                  # Serve the analysis to an AI agent over MCP (stdio, or --http)
clarifydoc ask routes path=/api/users  # Call one MCP tool from a shell or CI (--list for all)
clarifydoc install --hooks --skills    # Wire ClarifyDoc into agent hosts (MCP entry, hooks, skills)
clarifydoc install --git-hooks         # Refresh the analysis in the background after commit, merge, checkout

lsp-update writes lsp-enhancement.json alongside project-summary.json (--emit-queries <file> writes the definition questions instead, for an editor's language servers to answer; --answers <file> merges those answers without Docker; --scip index.scip takes them from a SCIP index — scip-typescript, scip-java, scip-python, rust-analyzer — that CI already builds, and --lsif dump.lsif from an older pipeline's LSIF dump); report reads the summary and emits report.html. Every command's options are in the CLI reference.

In CI

Pull requests get the API surface diff and the findings they introduce, and fail only on those.

GitHub Actions

on: pull_request
permissions:
  contents: read
  pull-requests: write   # the comment
  security-events: write # code scanning
jobs:
  clarifydoc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: clarifydoc/cli@main
        with:
          fail-on: security,error     # a level and/or finding categories
          fail-on-api: breaking       # removed routes, lost guards, new required fields

The base commit is analyzed once and cached by its SHA. The head starts from that analysis, so only the changed files reparse. One pull-request comment carries the result and is edited on every push. The SARIF goes to code scanning, and the job summary repeats the comment. Inputs: path, fail-on, fail-on-api, base, comment, sarif, args (further analyze options), token. The action installs the CLI of its own version from npm; a ref ahead of the last release builds it from the action's checkout instead.

GitLab CI

include:
  - remote: https://raw.githubusercontent.com/clarifydoc/cli/main/ci/gitlab-ci.yml
variables:
  CLARIFYDOC_FAIL_ON: "contract,route-miss"

The job installs the CLI from npm — CLARIFYDOC_VERSION (default latest) pins it. Findings land in the merge request's Code Quality widget and test report. With CLARIFYDOC_GITLAB_TOKEN set, a note on the merge request carries the same comment.

Anywhere else

ci/run.sh is what both run, and the npm package carries it. Give it CD_CLI (the CLI's dist/cli.js), CD_OUT and CD_BASE_SHA, and it does the same in any CI with git and Node 24. It exits 2 when a gate tripped.

npm install -g clarifydoc@0.12.1
CD_CLI="$(npm root -g)/clarifydoc/dist/cli.js" CD_OUT=.clarifydoc CD_BASE_SHA="$BASE" bash "$(npm root -g)/clarifydoc/ci/run.sh"

Supported languages

ClarifyDoc has two extraction paths. Tree-sitter languages get full AST extraction; regex languages get a lighter convention-driven pass.

Path Languages (extensions and files)
tree-sitter TypeScript, with Vue and Svelte components (.ts, .tsx, .mts, .cts, .vue, .svelte, .astro), JavaScript (.js, .jsx, .mjs, .cjs), C# (.cs, .csx), Python (.py, .pyw), Java (.java), Kotlin (.kt, .kts), Pascal/Delphi (.pas, .pp, .lpr, .dpr, .dpk), DFM/LFM/FMX forms (.dfm, .lfm, .fmx), PHP (.php, .inc), Bash/sh (.sh, .bash), F# (.fs, .fsi, .fsx), R (.r), Julia (.jl), Zig (.zig), OCaml (.ml, .mli)
regex Go (.go), Rust (.rs), Ruby (.rb, .rake, .jbuilder), Swift (.swift), Lua (.lua), Scala, with Play routes (.scala, .sc, conf/routes), Perl (.pl, .pm, .t, .psgi, .cgi), Visual Basic (VB.NET, VB6, VBScript) (.vb, .bas, .cls, .frm, .vbs), SQL (.sql, .ddl, .dml, .psql, .mysql, .tsql, .plsql, .pkb, .pks, .drift), C (.c), C++ (and CUDA) (.h, .cpp, .cc, .cxx, .hpp, .hxx, .hh, .cu, .cuh), Prisma (.prisma), Dart/Flutter (.dart), Elixir (.ex, .exs), Erlang (.erl, .hrl), Objective-C (.m, .mm), Haskell (.hs, .lhs), Clojure (.clj, .cljs, .cljc), Blazor (.razor), HTML (.html, .htm), ERB (.erb), HEEx/EEx (.heex, .eex, .leex), Handlebars (.hbs, .handlebars), Liquid (.liquid), Velocity (.vm), Razor (.cshtml), Go templates (.tmpl, .gohtml), FreeMarker (.ftl, .ftlh), EJS (.ejs), QML (.qml), Qt Designer (.ui), XAML (.xaml, .axaml), JSP (.jsp, .jspx, .jspf, .tag), Spring XML / MyBatis mappers / Android navigation graphs (.xml), JSight (.jsight), Interface Builder storyboards (.storyboard), Terraform (.tf), Protocol Buffers (.proto), Apache Thrift (.thrift), OpenAPI (.yaml, .yml, .json), GraphQL (.graphql, .gql, .graphqls), WSDL (.wsdl), Groovy, with Jenkinsfiles (.groovy, .gvy, .gy, .gsh, Jenkinsfile), PowerShell (.ps1, .psm1), Windows batch (.bat, .cmd), CoffeeScript (.coffee, .litcoffee), Crystal (.cr), Raku (.raku, .rakumod, .rakutest, .p6, .pm6, .pl6, .t6), Racket (.rkt), Scheme (.scm, .ss, .sld, .sls), Common Lisp (.lisp, .lsp, .asd), Haxe (.hx), Mojo (.mojo, .🔥), SCSS (.scss), Sass (.sass), Less (.less), AutoHotkey (.ahk, .ah2), AutoIt (.au3), AppleScript (.applescript), Nim (.nim, .nims), D (.d, .di), V (.v, .vsh), Fortran (.f, .for, .f77, .f90, .f95, .f03, .f08, .fpp), Serverless / AWS SAM (serverless.yml, serverless.yaml, template.yaml, template.yml, function.json), Core Data models (*.xcdatamodel/contents)

A .vue/.svelte SFC is preprocessed to its <script> block; Delphi .dfm uses a dedicated parser.

Multi-project / multi-repo

ClarifyDoc scans for project markers (package.json, *.csproj/*.sln, *.dpr, pom.xml, build.gradle[.kts], Cargo.toml, go.mod, pyproject.toml/requirements.txt, composer.json, Gemfile, Package.swift, pubspec.yaml, …) and groups files into sub-projects, assigning each file to its innermost enclosing project. A repo with a Delphi client next to a .NET service next to a React frontend is analyzed as one graph with three sub-projects — so cross-tier links (frontend → backend → DB) survive even across language and project boundaries.

What it extracts

Per file — <file>.json

Field Description
imports / exports Module specifiers, named/default/namespace/type flags; export kinds
functions / classes Params, return types, decorators, async; methods, properties, inheritance, visibility
calls (per function) Classified internal / cross-file / api-call / database, with confidence
routes API + frontend routes: method, handler, middleware, component target
dataSources Reads: API calls, state, props, context, env vars, DB/ORM queries (with resolved entity), message-queue publish/consume (RabbitMQ, Kafka, amqplib, pika, Spring AMQP, php-amqplib)
dataMutations Writes: setState, dispatch, assignments, ref mutations, DB writes
entityRelations ORM associations between entities (cardinality, foreign key, join table)
subComponents / templateTree Child components used, and the real nested template tree (with loop flags)
interactiveElements / events UI interaction points (onClick/@click, v-model, onSubmit, …) and emitted events
typeReferences Type-position uses of classes/interfaces (extends, params, returns, fields, casts, new)
complexities / securityIssues Per-function cyclomatic complexity; per-file security findings
frameworks / projectId Frameworks this file uses; the sub-project it belongs to

Project summary — project-summary.json

  • subProjects + fileProjects — detected projects and file→project map
  • detectedFrameworks — with confidence and detection source
  • componentGraph / linkGraph — file→file dependencies, weighted by proximity (1 tight / 2 medium / 3 loose)
  • symbolLinks — resolved call→definition traces (resolvedBy: text | lsp, with confidence)
  • routeMap / apiCalls / screens — aggregated routes, outbound HTTP calls, screen trees
  • apiRouteLinks — cross-tier joins: frontend api-call URLs matched to backend routes by HTTP method + structurally normalized path (these are what stitch screen→API→DB traces across sub-projects)
  • entityGraph — ER model (entities/tables/enums + crow's-foot relationships); tables referenced only by raw queries get synthesized inferred entities so query-builder codebases still get a data model
  • dataAccessGraph — file → entity → datastore graph with per-call detail; message queues appear as first-class nodes with publish/consume edges
  • externalPackages — declared-vs-used external dependency inventory across 19 package ecosystems
  • deployment — docker-compose-derived topology: services, externals, and service→service edges inferred from env-var evidence (shared API-key vars, connection strings, URL/issuer vars)
  • migrations — detected ORM/DB migrations (Prisma, TypeORM, Sequelize, Rails, Django, EF Core, GORM, Diesel, Doctrine, Flyway, Alembic)
  • classGraph / blastRadius — class dependency graph and per-file/per-class change impact
  • patterns / duplicates / layerViolations / complexity / securityIssues — code quality
  • healthScore / suggestions — graded health + prioritized actions
  • communities / cohesion / godNodes / surprisingConnections / suggestedQuestions — topology insights
  • confidenceCounts / lspStats — provenance and LSP run stats

On-disk encoding. To avoid spelling every file path and code element dozens of times, the artifact is normalized (schemaVersion: 2) around two registries:

  • files[] is the file registry — a file's page_id is its index in this array. Every section that references a file (componentGraph, linkGraph, routeMap, communities, godNodes, the fileProjects/fileLayerMap keys, the analysis lists, …) stores that integer page_id instead of the path.
  • elements[] is the symbol registry (file::symbol ids) — symbolLinks, complexity, classGraph, blastRadius, dataAccessGraph reference it by index.

Reconstruct the path-based, in-memory shape with denormalizeProject(JSON.parse(raw)) (exported from clarifydoc). It is shape-detecting, so summaries written before this encoding still load. Reading the output lists which field points into which registry, with jq recipes that resolve them.

Interactive report

--html (or clarifydoc report <dir>) emits a single self-contained report.html — the React + D3 viewer bundled into one offline-capable file, with the analysis payload embedded gzip+base64 (roughly 10× smaller than raw JSON). Tabs:

Overview · Screens & UI · Call Traces · Architecture · Data Model · Routes · Dependencies · Health · Blast Radius · Patterns · Security · Complexity · Suggestions · Insights

Tabs hide themselves when there's no data for them. Highlights:

  • Architecture is a C4-style drill-down — System Context → Deployment (docker-compose topology) → Projects → Components → Code — with dagre-layered layout, plus Data Models and Data Access graph modes.
  • Call Traces walks click → handler → service → API route → entity, including transitive data access ("this controller reaches these tables via its callees").
  • Data Model renders entities as full ER tables with crow's-foot relationship edges.

MCP server — for AI agents

clarifydoc mcp serves the analysis over the Model Context Protocol on stdio, so an agent can ask for the code map instead of grepping for it. Every answer comes from the same analysis the HTML report renders, with path:line references it can open.

# In the project: serves it, analyzing once if it has never been analyzed
clarifydoc mcp

# Or name it explicitly, and/or an exact analysis directory
clarifydoc mcp ./my-app --analysis-dir ./my-app/.clarifydoc/my-app

# Claude Code — one entry that works in every project you open
claude mcp add clarifydoc --scope user -- clarifydoc mcp

Or, in a config file (Claude Code, Cursor, Windsurf, …):

{
  "mcpServers": {
    "clarifydoc": {
      "command": "clarifydoc",
      "args": ["mcp"]
    }
  }
}

One server for several local agents at once: clarifydoc mcp --http listens on http://127.0.0.1:3737/mcp (--port, --host) and shares one loaded analysis between them; point a client at that URL. It is loopback-only unless you give it a token — --token-file <path> (first line of a file), CLARIFYDOC_MCP_TOKEN, or --token <t> (visible in the process list, so it warns; precedence in that order) — which clients then send as Authorization: Bearer <t>; binding another host without a token is refused. Sessions expire after 30 idle minutes (CLARIFYDOC_MCP_SESSION_TTL_MS; a client then initializes again), and GET /mcp with Accept: text/event-stream opens a stream that carries notifications/tools/list_changed when the analysis is refreshed. The stdio server accepts newline-delimited JSON and Content-Length framing alike.

Without a global install, the same entry runs it through npx: "command": "npx", "args": ["-y", "clarifydoc", "mcp"] (clarifydoc@0.12.1 to pin the version). The first start downloads the package, about 9 MB.

With no path, the server serves the project containing the client's working directory — walking up to the nearest .git or manifest, so it maps the whole project even when launched in a subdirectory — and reads <root>/.clarifydoc/<name>, where clarifydoc analyze and the VS Code extension both write. That is why the config needs no paths and never goes stale.

If the project has never been analyzed, the server runs one analysis itself so the agent is useful immediately — unless the folder holds no source it reads, or more than 25,000 files (CLARIFYDOC_MCP_COLD_START_MAX_FILES), when it refuses with the folders that hold the most so the agent can ask which part to map. An advisory lock in the analysis directory means only one process ever writes it: a second run waits for the first instead of interleaving with it.

Tool Answers
clarifydoc_status What has been mapped, how stale it is, how much of each dimension exists
clarifydoc_search Find a route / screen / symbol / entity / file by name — one list, ranked, terms matched independently
clarifydoc_routes API + frontend routes, their handlers, their frontend callers, what they reach; gaps=true for calls that reach no route, routes nothing calls, and request bodies that disagree with their route
clarifydoc_contract One endpoint's request shape, parameter bindings and auth, as an OpenAPI-like operation
clarifydoc_services Sub-project → sub-project dependencies (HTTP and messaging) with their endpoints
clarifydoc_screens Screens/pages, their routes, the endpoints they call, the dialogs they open
clarifydoc_file Everything about one file: functions, complexity, data access, callers, findings, the decisions that name it; flagged when the file changed since the analysis
clarifydoc_trace Callers/callees of a symbol, N hops, plus the data effects it reaches; to= for the path between two symbols
clarifydoc_extract One function's source and the functions it calls, cut to a token budget; with package=, an installed package's exported API at the installed version
clarifydoc_rename_plan What renaming a function or class touches: the definition and every caller as exact file:line:col spans, the route lines that register it, the imports and exports naming it; refused when any link is inferred or ambiguous, or a route line does not spell its name. Writes nothing
clarifydoc_blast_radius What breaks if a file changes — dependents, screens/routes/entities reached
clarifydoc_data_model Entities/tables, columns, relations, and the functions that read/write them
clarifydoc_data_flows Route/screen → data effect rows (e.g. which endpoints reach a DB write)
clarifydoc_health Score plus security, layer violations, complexity, duplicates, hotspots, dead code, refactor pressure
clarifydoc_architecture Folder dependencies with instability, communities, hub files, import cycles, surprising links, files that change together
clarifydoc_context_docs Decision records (ADRs), architecture/glossary documents, schema dumps and WHY:/DECISION: comments — listed, searched, read, or those naming a file — each flagged when files it names changed after it; for one file (or function), also the reasons its plain comments and commit bodies state, labelled as such; declare more under context in .clarifydoc/config.json
clarifydoc_explain One route, screen, function or file packed into a token budget: what it is (route handler, data access, …, from the facts), contract and callers, what it reaches, source, the routes sharing its tables, blast radius
clarifydoc_impact Impact of the current git diff: screens, routes, entities, tests to run; the changed functions and their callers, signature breaks, owners and reviewers, files usually changed with it; with proposed (a file's new content) the same for an edit not made yet
clarifydoc_control_flow One function's control flow as Mermaid, or the backward slice at a line: the statements that can affect the values used there
clarifydoc_sequence What a route or function does, in order, as a Mermaid sequence diagram: calls, data access, HTTP hops to other tiers (clarifydoc seq)
clarifydoc_diff The API surface against a git ref (default HEAD): routes, parameters, request bodies, guards, versions, links and data reached, each breaking or risky (clarifydoc diff --base). Writes the ref's analysis under the analysis directory; refused with --no-auto-analyze
clarifydoc_export One whole-project document or diagram — ARCHITECTURE.md, DATA-MODEL.md, FLOWS.md, Mermaid, GraphML, Cypher, CSV (clarifydoc export); no format lists them
clarifydoc_facts The analysis's facts under stable IDs to cite in a document, or a check of the IDs a text cites (clarifydoc facts)
clarifydoc_analyze Re-run the analysis (incremental); report=true also writes report.html. With clarifydoc_diff, the only tool that writes anything

clarifydoc_status lint=true adds clarifydoc lint's contradictions, and the resources clarifydoc://analysis/schema and clarifydoc://project/detect carry what clarifydoc schema and clarifydoc detect --json print.

Flags: --analysis-dir <dir> to read an exact analysis directory, --no-auto-analyze to forbid re-analysis on request (the first analysis still runs), --no-cold-start to forbid even that, plus the analyze filters (--include, --exclude, --max-files, --lsp, --no-git-history) for the scans it does run. --tools core offers only status, search, explain, trace, file, extract, impact and analyze — under half the up-front cost of the full set, for a host with many servers — or name the tools, comma-separated.

Long answers are cut at about 20,000 tokens (CLARIFYDOC_MCP_MAX_TOKENS) with a note on how to ask for less, and a "next page" offset carries the analysis it counts in, so a page asked for after a re-run says the rows may have moved. clarifydoc://session/usage lists the session's calls in order with their answer sizes and times; CLARIFYDOC_MCP_LOG=<file> appends each call, and the session's totals at the end, to a local JSONL file.

Inside VS Code the extension publishes this server for you, per workspace folder, and ClarifyDoc: Set Up MCP for an AI Agent… writes the config for Claude Code, Cursor or Windsurf — pointed at a launcher that survives extension updates. See clarifydoc/vscode.

Wiring it into an agent host

clarifydoc install [path] writes the MCP server entry for one or more clients — --client claude-code (the default, .mcp.json), cursor (.cursor/mcp.json), vscode (.vscode/mcp.json), gemini (.gemini/settings.json), zed (.zed/settings.json), opencode (opencode.jsonc or opencode.json), kilo (kilo.jsonc, kilo.json or .kilo/), and the user-level files of windsurf, codex, claude-desktop, cline and copilot (Copilot CLI's ~/.copilot/mcp-config.json), which start ClarifyDoc by absolute path since the apps reading them may not have the shell's PATH — merged into what is there. A file with comments or trailing commas is edited in place, only the ClarifyDoc entry changing; one that cannot be edited safely is left as it is, and the entry to add by hand is printed instead. --hooks adds the hooks of the clients named: Claude Code's to .claude/settings.json, Codex's (PreToolUse on Bash, so its shell searches get the context) to ~/.codex/hooks.json or config.toml, and GitHub Copilot's — copilot or vscode, whose agent mode reads the same hooks — to ~/.copilot/hooks/clarifydoc.json (PostToolUse after searches: Copilot's pre-tool hooks can only allow or deny); --skills writes .claude/skills/clarifydoc-* from the MCP workflow prompts; --guidance adds or updates a marked ClarifyDoc section of AGENTS.md (or the file named), with what this project's analysis says an agent should know first. --print shows it all instead. --plugin <dir> writes an agent plugin there instead — the MCP entry, the same skills, and a read-only clarifydoc-explorer subagent that answers from the map — laid out for Claude Code (.claude-plugin/), and for Codex and Copilot CLI (the Agent Plugins 1.0 plugin.json and mcp.json) in the same directory.

The hooks run clarifydoc hook <event>, which reads the host's JSON payload on stdin and answers with additionalContext from the last analysis, or with nothing:

Event When What the agent is told
pre-search before Grep/Glob, or a grep/rg in the shell what the map knows about the name being searched for, and where
post-search after a search (Copilot, --dialect copilot) the same, beside the search's results
post-edit after Edit/Write who depends on the file just changed, and what to run before finishing
post-git after a shell git commit, checkout, switch, merge, pull or rebase nothing: starts one background incremental refresh with the options the analysis was made with — its recorded LSP, git-history and --feature settings (coalesced while one runs; never without an existing analysis)
session-start a new session what the map covers and how fresh it is

A hook never blocks a tool call and stays silent on any error; only post-git starts an analysis, detached.

Detection details

Frameworks

Web / app: React, React Router (incl. framework mode), Remix, Next.js, Expo Router, Vue, Vue Router, Nuxt, Svelte, SvelteKit, Angular, Express, NestJS, Fastify, FastAPI, Django, Flask, ASP.NET, Blazor, Spring Boot/Web, Ktor, Android, CodeIgniter, Flutter, Pinia, Vuex, Redux, React Query.

Message queues (surface as publish/consume data sources and queue nodes in the data-access graph): RabbitMQ (RabbitMQ.Client, amqplib, pika, php-amqplib, Spring AMQP), Kafka (kafkajs, Spring Kafka).

ORMs / query builders (surface as kind="database" data sources + entity graph):

Ecosystem ORMs
.NET / C# Entity Framework Core, EF 6, Dapper, NHibernate, raw ADO.NET
JS / TS Prisma, TypeORM, Sequelize, Drizzle, MikroORM, Mongoose, Knex, Objection.js
Python SQLAlchemy, Django ORM, Tortoise, Peewee
Java / Kotlin Hibernate, Spring Data JPA, MyBatis, jOOQ, Exposed
Ruby Active Record, Sequel
PHP Doctrine, Eloquent, CodeIgniter Query Builder
Go GORM, sqlx, Ent
Rust Diesel, SeaORM, SQLx
Dart Firestore, sqflite, Supabase
Raw SQL .sql / .ddl files

Detection reads package.json, .csproj PackageReference, go.mod, Cargo.toml, composer.json, Gemfile, pom.xml, build.gradle[.kts], requirements.txt, pyproject.toml, pubspec.yaml.

Routes

Express/Fastify (app.get("/path", h)), decorators/annotations (@Get(), @RequestMapping, @app.route), React Router (<Route path=… />, including nested-route prefix composition), Vue Router config objects, Next.js, Nuxt, SvelteKit, Expo Router and Remix / React Router flat routes file-based routing (also when the app sits in a sub-folder), React Router 7 app/routes.ts configs (route/index/layout/prefix), Spring (@GetMapping/@PostMapping), Ktor DSL, ASP.NET attributes, Blazor @page, CodeIgniter convention routing (controller file + public method → URL), Dart shelf_router + Flutter GoRouter, and plain multi-page HTML sites (each page becomes a frontend route with its links and forms).

SQL / DDL

.sql files are parsed into the same model: CREATE TABLE/VIEW/INDEX/SEQUENCE/TYPE → classes (typed columns), CREATE PROCEDURE/FUNCTION/TRIGGER → functions, DML/EXEC/CALL → data sources, FOREIGN KEY … REFERENCES → entity-graph edges. Dialects (best effort): PostgreSQL, MySQL, T-SQL, Oracle PL/SQL, SQLite; bracketed, double-quoted and backtick identifiers all recognized.

Programmatic API

import { analyze } from "clarifydoc";

const result = await analyze({
  projectRoot: "./my-app",
  outputDir: ".clarifydoc/my-app",
  pretty: true,
  incremental: true,
});
// per-file FileAnalysis JSON + project-summary.json written to outputDir

Key exports (see src/index.ts):

export { analyze } from "./core/analyzer.js";
export { discoverFiles } from "./core/file-discovery.js";
export { detectFrameworks, gatherProjectInfo } from "./core/framework-detector.js";
export { generateHtmlReport } from "./core/html-report.js";
export { parseSource, parseFile, runQuery } from "./parsers/parser-manager.js";
export type * from "./types/analysis.js";

Project configuration

Optional, committed with the code: .clarifydoc/config.json (next to .clarifydoc/ignore). Everything in it has a default; a missing file changes nothing, and a bad value is reported as a warning and ignored rather than failing the run.

{
  "$comment": "Why we changed these: legacy module is being strangled, tolerate more churn.",
  "layers": [
    { "layer": "data",     "patterns": ["src/Persistence/**", "**/*Repository.cs"] },
    { "layer": "services", "patterns": ["src/Application/**"] },
    { "layer": "ui",       "patterns": ["src/Web/**", "frontend/src/**"] }
  ],
  "exempt":    ["tools/**", "prototypes/**"],
  "generated": ["**/*.generated.*", "src/api/gen/**"],
  "rules": [
    { "name": "billing stays out of payroll", "from": "features/billing/**", "to": "features/payroll/**", "except": ["**/shared/**"] },
    { "name": "domain is pure", "from": "src/Domain/**", "to": "src/Infrastructure/**", "severity": "warn" },
    { "name": "features stay apart", "each": "src/features/*" },
    { "name": "features use shared only", "each": "src/features/*", "allowOnly": ["src/shared/**", "src/api/**"] },
    { "name": "no cycles between modules", "each": "src/modules/*", "noCycles": true }
  ],
  "refactorPressure": {
    "weights":  { "complexity": 0.25, "size": 0.1, "responsibility": 0.2, "coupling": 0.2, "churn": 0.25 },
    "ceilings": { "maxCognitive": 50, "loc": 800, "concerns": 4, "fanIn": 15, "fanOut": 15, "commits": 30 },
    "bands":    { "observe": 25, "suggest": 45, "strong": 60, "urgent": 75 },
    "gates":    { "godClassLoc": 500, "godClassCognitive": 120, "concernOverload": 4, "hubFanIn": 10, "hubFanOut": 10 }
  }
}

layers assigns architecture layers by glob (ui, components, services, data, utils, config), checked in order before the built-in path heuristics — the way to fix a layer the heuristics get wrong for your repo (an adapters/ folder that is infrastructure here and UI glue there). exempt marks trees outside the layered application (tooling, scripts, prototypes) so they are never a layer-violation source or target; tests are always exempt. generated marks generated code by glob; it is excluded from every quality signal (patterns, duplicates, violations, refactor pressure, the health grade), extending the automatic detection of generated barrel trees. Globs use the ignore-file dialect (*, **, ?) and match the posix project-relative path. Anchoring follows gitignore: a pattern carrying a / (/dist, src/db/**) is fixed to the project root, while a slash-less one (dist, *.generated.ts) also matches a bare file name anywhere.

rules are your own import rules: a file matching from must not import a file matching to (one glob or a list on each side; except lifts the rule for the files it names on either end; severity is error unless it says warn). Instead of to, a rule can say allowOnly — the only project files from may import — or noCycles: true — no import cycle among its files. each makes every directory a one-* pattern names its own element (src/features/*: src/features/billing, src/features/payroll, …): from then defaults to every file inside an element, imports within one element never break the rule, noCycles is judged between elements, and a rule with none of to, allowOnly and noCycles keeps the elements apart. Each breach is reported among the layer violations with the rule's name — the Health tab and clarifydoc_health category layers — and a cycle names the elements it runs through.

refactorPressure tunes the composite refactor pressure score (project-summary.json → refactorPressure, MCP clarifydoc_health category pressure): each file's cognitive complexity, size, mixed concerns, coupling and git churn are normalized against the ceilings, combined with the weights, and cut into bands. gates fire regardless of the score. Every row lists the drivers behind it and a confidence equal to the share of signal that was available, so a run without git history says so instead of scoring lower.

extract tells the analysis what your own wrappers mean, without writing a plugin: an in-house HTTP client, a route registrar, a database helper.

{
  "extract": {
    "httpCalls": [{ "call": "apiGet", "method": "GET" }, { "call": "http.send", "methodArg": 0, "urlArg": 1 }],
    "routes": [{ "call": "registerRoute", "methodArg": 0, "pathArg": 1 }],
    "db": [{ "call": "db.exec", "sqlArg": 0 }, { "call": "ledger.write", "tableArg": 0, "access": "write" }]
  }
}

Each call site whose argument is a literal becomes an API call (linked to the route that serves it), a route, or a database access (the table read from the SQL, or named), exactly as for a framework a plugin knows. urlArg and pathArg default to the first argument; a db entry needs tableArg or sqlArg. An access the config declares counts even when the call resolves into your own code.

specs lists API specs outside the tree, relative to the project root, that the code's calls are checked against — the same as --spec: { "specs": ["../backend/openapi.yaml"] }.

security turns a security rule off or changes its severity, by its id — the ruleId every finding carries (clarifydoc/sql-injection; the clarifydoc/ prefix may be left out):

{ "security": { "rules": { "todo-fixme": "off", "debug-statement": "low", "weak-crypto": "high" } } }

On one line, clarifydoc-ignore silences a finding; followed by rule ids (// clarifydoc-ignore eval-exec) it silences only those. clarifydoc-ignore-next-line [rules…] does the same for the line below, and nosec / NOSONAR silence every rule. Words after the marker that are not rule ids are a comment, not a list.

Default ignores

Always excluded:

node_modules, dist, build, out, .git, bin, obj,
__pycache__, .venv, venv, vendor, target, Pods,
*.min.js, *.bundle.js, *.d.ts

Beyond those, a .clarifydocignore at the project root or a .clarifydoc/ignore next to the analysis excludes further paths in gitignore syntax — *, **, ?, [abc], # comments, and ! to re-include. A pattern carrying a / is anchored to the directory the ignore file sits in, so /dist drops the build directory at the root and leaves src/dist/ alone; a slash-less pattern such as vendor matches that name at any depth. The last matching pattern decides, and unlike git a file can be re-included even when its parent directory was excluded, so src/** followed by !src/important.ts keeps that one file.

Files whose names look like credentials (.env, key/secret-like names) are skipped and reported under skippedSensitive.

How accurate is it?

ClarifyDoc is measured on real repositories checked out at pinned commits: it analyzes them, serves the result over the MCP server and scores it against labels written by hand from the source — never against ClarifyDoc's own output. The repositories pair Rails + Vue, ASP.NET + Angular, Django + Angular, FastAPI + Nuxt, Go + Vue, Express + React, and FastAPI on its own.

Over nine pinned repositories, as of extractor 1.588.0:

Cross-tier links (frontend call → backend route), sampled calls on seven repos precision 0.994, recall 0.983
Data access (file → table) F1 1.000
Route paths, as a caller would request them F1 0.990
Route declaration sites found F1 0.990
Search (Mean Reciprocal Rank) 1.000
Answering through the map vs. reading the files 65% fewer tokens

Bad numbers get published too: a corpus picked to flatter the tool measures nothing. The first run scored route paths at 0.000 on FastAPI and missed every DELETE call in a demo app's frontend.

Versioning by content hash

Every analyzed file is tracked in manifest.json by SHA-256 of its contents plus an EXTRACTOR_VERSION stamp. This makes change-tracking explicit:

  • --incremental reuses cached per-file JSON for files whose hash is unchanged (mtime fast-path, hash slow-path — survives branch switches and sync tools that bump mtime).
  • A re-run with no file, option or git state changed rebuilds nothing; one in which only documentation (.md, .rst, .adoc) changed re-checks doc drift on the last analysis and keeps the rest.
  • Bumping EXTRACTOR_VERSION invalidates the whole cache, so a fixed extractor never leaves stale JSON behind.
  • Per-file output carries analyzedAt; the project summary records framework/LSP provenance and per-link confidence (EXTRACTED / INFERRED / AMBIGUOUS).

License

MIT — see LICENSE. Security reports: SECURITY.md.

About

No description, website, or topics provided.

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages