Keep your projects clean.
A fast, lightweight CLI toolkit for auditing, maintaining, and inspecting JavaScript and TypeScript projects.
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 passedReal 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.
01broom env
Which variables does the code read that no env file defines?
Every statically identifiable
process.envandimport.meta.envreference is compared with every.env*file. Broom reports missing, undocumented, duplicate and unused variables, and server-only variables read in client code.- --fix
- --yes
Fig. 1broom env Variable Finding API_URL missing SECRET_TOKEN missing SECRET_TOKEN client exposure API_KEY duplicate STALE_FLAG unused 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-runshows exactly what would go before anything does.- --dry-run
- --confidence
- --fix
Fig. 2broom clean --dry-run, excerpt File Confidence components/OldButton.tsx high 63 B src/icons/unused-icon.svg high 512 B src/lib/unused-helper.ts high 32 B src/styles/legacy.css high 24 B public/images/banner-old.webp medium 4 KB public/logo-old.svg medium 59 B src/locales/en.json low 18 B 4 files, 631 B would be deleted at high confidence. No files were changed.
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
Fig. 3broom ports Port PID Process 3000 4148 node this project 5173 4148 node this project 5174 98623 Python Free 3001 4000 4173 8000 8080 8787
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
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
05broom doctor
Is this project healthy?
Checks
package.json, Node.js againstengines, lockfiles, installed modules, imports,.gitignore, git, environment variables, and Next.js or Vite setup.--fixoffers only safe fixes, each confirmed first.- --verbose
- --fix
Fig. 5broom doctor, excerpt ✗ Imported packages axios imported but not declared ✗ .gitignore .env is not ignored by git ! Lockfiles No lockfile; installs are not reproducible ! Duplicate declarations 1 package in both dependencies and devDependencies · npm scripts No "test" script ✓ 4 checks passed --verbose to list 2 failed, 4 warnings, 4 passed · exit code 3
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
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
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
Fig. 7broom stats 26 files in 10 directories, 9.1 KB
Language share by bytes TSX 51.4% 5 files JSON 32.8% 4 files CSS 7.8% 4 files TypeScript 5.7% 2 files JavaScript 2.4% 1 file
How it works. No setup required.
- 01
Install Broom
npm install -g @kebabmario/broom - 02
Open a project
cd my-next-app - 03
Run a command
broom doctor - 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
--jsonprints exactly one JSON document on stdout. Progress and warnings go to stderr.- Quiet and verbose
-qkeeps only essential output.--verboseadds reasons, locations and diagnostics.- Dry runs
broom clean --dry-runshows exactly what cleanup would delete, and changes nothing.- Configurable
- Optional
broom.config.jsonor a"broom"key inpackage.json. Unknown keys are rejected.
Exit codes
| 0 | Success, nothing to report |
|---|---|
| 1 | Execution error |
| 2 | Invalid arguments or configuration |
| 3 | The audit found issues |
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/broomInstalls the broom command globally.