02

Getting started

Installing and running the extension and the CLI for the first time

2 min read5 sections

Requirements

RequirementWhy
Git on your PATHEvery analysis runs git log, git diff, git cat-file.
A folder that is a Git repository with at least one commitAttribution is based on commits. Without them the analysis stops with an error.
VS Code ≥ 1.90 (extension)Declared in engines.vscode.
Node.js ≥ 20 (CLI)Declared in engines.node.
A trusted workspace (extension)The extension runs Git commands, so it is disabled in Restricted Mode.

Option A — the VS Code extension

Install

  • From the Marketplace: search for CleanLens (id cleanlens.cleanlens), or
  • from a local build: npm run package then Extensions → … → Install from VSIX.

First run

  1. Open the project folder (the repository root) in VS Code.
  2. Run CleanLens: Initialize Project from the Command Palette (Cmd/Ctrl+Shift+P).
    • CleanLens suggests a preset from the files in the root: manage.py → Django; pyproject.toml / requirements.txt / setup.py → Python; otherwise JavaScript.
    • Pick a preset, review the preview, click Create.
    • This writes .clean-code-tracker.json in the root and opens it. It never overwrites an existing file.
  3. Review the rules (see 06 — Rules reference).
  4. Run CleanLens: Run Analysis (or the ▶ button on the CleanLens sidebar). A progress notification shows each stage; you can cancel it.
  5. The dashboard opens automatically. The sidebar's Dashboard, Developers and Violations views fill in, and every violation is underlined in the editor.

While you code

Live diagnostics are on by default: every open JS/TS/Python file is re-checked 400 ms after you stop typing, using the file-level rules. See 12 — VS Code extension.

Option B — the CLI

Build and run from this repository

bash
npm install
npm run build
node dist/cli.js /path/to/repo

Once installed as a package

bash
cleanlens                       # analyze the current directory
cleanlens ./my-project --violations
cleanlens --markdown > report.md
cleanlens --json > report.json
cleanlens --preset django --fail-on high

The CLI reads the same .clean-code-tracker.json as the extension. --preset ignores that file and uses a built-in preset instead. See 13 — CLI for every option.

Reading your first report

A text report looks like this (values are illustrative):

text
Developers: 3
Analyzed files: 84
Analyzed commits: 500
Total violations: 212
Unattributed: 0

Alice
  Clean Code Score: 78/100
    duplication 88 · structure 70 · hygiene 82
  Analyzed Lines: 12,400
  Confidence: Highly reliable
  Contribution: 61%
  New Violations: 64
  Fixed Violations: 21
  ...

How to read it:

  • Score is quality: higher is cleaner. Contribution is volume. Read them separately.
  • The three sub-scores show where the problems are.
  • Confidence tells you how much code the score is based on. Treat Insufficient and Provisional scores with care.
  • Existing and unattributed counts are informational. They never lower a score.
  • Developers below the ranking threshold appear under "Not ranked".

Next steps