Skip to content
broom

Keep your projects clean.

A fast, lightweight CLI toolkit for auditing, maintaining, and inspecting JavaScript and TypeScript projects.

npm install -g @kebabmario/broom
Get startedGitHub (opens in a new tab)
~/projects/next-app

broom doctor


  broom doctor

  Project         fixture-next-app 1.0.0
  Framework       Next.js 15.1.0
  Package manager unknown
  Node.js         24.22.1
  TypeScript      yes
  Git             main

  ! Lockfiles              No lockfile found; installs are not reproducible
  ! Installed              node_modules not found; run "npm install"
  ✗ Imported packages      1 imported package(s) not declared in package.json
      axios — app/page.tsx
  ! Duplicate declarations 1 package(s) in both dependencies and devDependencies
  · npm scripts            No "test" script
  ✗ .gitignore             Environment file(s) not ignored by git: .env
      fix: Append node_modules/, .env and .env*.local to .gitignore (--fix)
  · Git                    on main, clean
  ! Environment variables  2 referenced but not defined (API_URL, SECRET_TOKEN)
  ✓ 4 checks passed (--verbose to list)

  2 failed, 4 warnings, 4 passed

Real output from Broom 0.1.0, run against the Next.js fixture in its test suite.

  • Parsed, not grepped

    Source is analyzed with Babel. Comments and strings never count as usage.

  • Offline

    Broom never sends anything over the network.

  • Asks first

    Nothing is deleted and no process is stopped without confirmation.

  • Secret-safe

    Values in your .env files are never printed.

Seven commands. Each answers one question about your project, and none of them change anything without asking.

  1. 01broom env

    Which variables does the code read that no env file defines?

    Every statically identifiable process.env and import.meta.env reference is compared with every .env* file. Broom reports missing, undocumented, duplicate and unused variables, and server-only variables read in client code.

    • --fix
    • --yes
    Reference
    Fig. 1broom env
    VariableFinding
    API_URLmissing
    SECRET_TOKENmissing
    SECRET_TOKENclient exposure
    API_KEYduplicate
    STALE_FLAGunused
  2. 02broom clean

    Which files does nothing reference anymore?

    Imports, CSS url(), JSX attributes, Markdown links, tsconfig paths and dynamic import patterns all count. Each candidate gets a confidence level, and --dry-run shows exactly what would go before anything does.

    • --dry-run
    • --confidence
    • --fix
    Reference
    Fig. 2broom clean --dry-run, excerpt
    FileConfidence
    components/OldButton.tsxhigh63 B
    src/icons/unused-icon.svghigh512 B
    src/lib/unused-helper.tshigh32 B
    src/styles/legacy.csshigh24 B
    public/images/banner-old.webpmedium4 KB
    public/logo-old.svgmedium59 B
    src/locales/en.jsonlow18 B

    4 files, 631 B would be deleted at high confidence. No files were changed.

  3. 03broom ports

    What is already running on port 3000?

    Lists processes on the usual development ports and marks the ones started from this project. With --kill, Broom re-scans and checks the process start time first, so a reused PID is never signalled.

    • --port
    • --all
    • --kill
    Reference
    Fig. 3broom ports
    PortPIDProcess
    30004148nodethis project
    51734148nodethis project
    517498623Python

    Free 3001 4000 4173 8000 8080 8787

  4. 04broom recap

    What changed this week?

    Reads local git history and writes Markdown: grouped by date, as a standup per author, or as a Conventional Commit changelog. No network and no AI; it restates subjects, hashes, authors and dates.

    • --days
    • --format
    • --output
    Reference
    Fig. 4broom recap --format changelog

    Changelog

    2026-11-11 to 2026-11-18 · 6 commits · main

    Breaking changes

    clean: re-check files before deleting f6a4d2d

    Features

    add --format standup to recap 9e9416d

    Fixes

    env: ignore runtime-provided variables b41750e

    Performance

    cache tsconfig path resolution 169518f

  5. 05broom doctor

    Is this project healthy?

    Checks package.json, Node.js against engines, lockfiles, installed modules, imports, .gitignore, git, environment variables, and Next.js or Vite setup. --fix offers only safe fixes, each confirmed first.

    • --verbose
    • --fix
    Reference
    Fig. 5broom doctor, excerpt
    ✗Imported packagesaxios imported but not declared
    ✗.gitignore.env is not ignored by git
    !LockfilesNo lockfile; installs are not reproducible
    !Duplicate declarations1 package in both dependencies and devDependencies
    ·npm scriptsNo "test" script
    ✓4 checks passed--verbose to list

    2 failed, 4 warnings, 4 passed · exit code 3

  6. 06broom deps

    Do the dependencies match what the code uses?

    Declared dependencies are compared with imports, npm scripts and tool configuration, per workspace package. Confirmed findings have direct evidence; potential ones are labeled for review. Broom never uninstalls anything.

    • --json
    • --verbose
    Reference
    Fig. 6broom deps

    Confirmed

    • axios not declared
    • zod declared twice

    Potential

    • lodash possibly unused
    • left-pad possibly unused

    Loaded implicitly: @types/react, eslint-config-next, react, react-dom, typescript

  7. 07broom stats

    What is this codebase made of?

    Files, directories, extensions and languages by real byte size. Generated directories and ignored files are left out, symlinks are never followed and hard links are counted once.

    • --top
    • --verbose
    Reference
    Fig. 7broom stats

    26 files in 10 directories, 9.1 KB

    Language share by bytes
    TSX51.4%5 files
    JSON32.8%4 files
    CSS7.8%4 files
    TypeScript5.7%2 files
    JavaScript2.4%1 file

How it works. No setup required.

  1. 01

    Install Broom

    npm install -g @kebabmario/broom
  2. 02

    Open a project

    cd my-next-app
  3. 03

    Run a command

    broom doctor
  4. 04

    Review the results

    echo $? # 3 = issues found

Built for terminals, scripts and CI. Same flags and exit codes in every command.

Cross-platform
macOS, Linux and Windows. Paths are normalized internally; port discovery uses each platform's own tools.
Lightweight
A single compiled entry point with seven small runtime dependencies. Subprocesses never run through a shell.
JSON output
--json prints exactly one JSON document on stdout. Progress and warnings go to stderr.
Quiet and verbose
-q keeps only essential output. --verbose adds reasons, locations and diagnostics.
Dry runs
broom clean --dry-run shows exactly what cleanup would delete, and changes nothing.
Configurable
Optional broom.config.json or a "broom" key in package.json. Unknown keys are rejected.

Exit codes

Broom exit codes
0Success, nothing to report
1Execution error
2Invalid arguments or configuration
3The audit found issues
What counts as an issue

JSON document

{
  "ok": true,
  "command": "env",
  "version": "0.1.0",
  "root": "/abs/path",
  "data": { … }
}

Install Broom. Then run broom doctor in any project.

Node.js
^22.18.0 || >=24.11.0
broom recap
git on PATH
broom ports
lsof or ss; PowerShell or netstat on Windows
npm install -g @kebabmario/broom

Installs the broom command globally.

Installation guide