codesweep

English | 日本語

Run lint, format, typecheck, test, and other code quality commands in one go. Configure each project with a YAML file.

Why codesweep?

Task runners like concurrently and npm-run-all2 are great at running commands in parallel, but multi-stage pipelines — apply fixes first, then verify everything in parallel — quickly turn into hard-to-read one-liners in package.json. codesweep lets you declare the whole pipeline in one YAML file, mixing sequential and parallel stages freely, and run it with a single command.

It is built for "run all quality checks in one go" moments: post-task checks for AI coding agents, pre-commit hooks, and CI. Commands in a stage fail through — one failure doesn't cancel the other checks — so you see every error in a single run.

In short: if you need build caching and dependency graphs, reach for wireit; if you just want to run a couple of commands in parallel, concurrently alone is enough; if you want a declarative, multi-stage quality-check pipeline, codesweep is for you.

Requirements

• Node.js >= 22 (or Bun >= 1)

Install

# npm
npm install @tzwzx/codesweep

# bun
bun add @tzwzx/codesweep

# pnpm
pnpm add @tzwzx/codesweep

After install, the codesweep binary is available via npx @tzwzx/codesweep, bunx @tzwzx/codesweep, or ./node_modules/.bin/codesweep.

CLI usage

codesweep <command> [options]

• init — Create a starter codesweep.yml in the current directory. Reserved as a subcommand; see note below.
• mode — Any mode defined in codesweep.yml (for example check or fix).
• --config / -c <path> — Path to the config file (default: ./codesweep.yml).
• --quiet / -q — Print only what failed. See Quiet mode.
• --help / -h — Show help.

Examples:

codesweep init
codesweep check
codesweep fix
codesweep check --config ./packages/app/codesweep.yml
codesweep check --quiet

Exit code 0 on success, 1 on failure. Elapsed time is printed when the run finishes.

Quiet mode

--quiet buffers what each command prints and shows only the ones that failed. A run where everything passes produces no output at all — the exit code carries the result.

codesweep check           # every tool's progress, summaries and exit lines
codesweep check --quiet   # (nothing)

This is aimed at CI, where a green build should not bury the next reader in thousands of lines of "no issues found". It also means a noisy analyzer costs nothing while it passes, so you can keep it in the pipeline without drowning the log.

When something does fail, each failing command is printed with its full output:

❌ Command failed: npm run typecheck
src/app.ts(12,7): error TS2322: Type 'string' is not assignable to type 'number'.

❌ codesweep check failed (8.21s)

Every command still runs to completion, so one run surfaces every error at once — quiet mode changes what is printed, never what is executed.

A dedicated CI mode pairs well with it:

check:
  - parallel:
      - npm run lint
      - npm run typecheck

check-ci:
  - parallel:
      - npm run lint
      - npm run typecheck
      - npm run test

codesweep check-ci --quiet

Library usage

codesweep can also be called programmatically: import { codesweep } from "@tzwzx/codesweep" and await codesweep("check") (optionally passing a config path as the second argument, and { quiet: true } as the third).

Config: codesweep.yml

Run init to generate a starter codesweep.yml in the current directory (fails if the file already exists). This also works without installing first:

npx @tzwzx/codesweep init

# or with bun
bunx @tzwzx/codesweep init

This creates:

# codesweep configuration
# https://github.com/tzwzx/codesweep

check:
  - parallel: # Stage 1: run checks in parallel
      - npm run lint
      - npm run typecheck
      - npm test

fix:
  - sequential: # Stage 1: apply auto-fixes
      - npm run fix
  - parallel: # Stage 2: verify after fixing
      - npm run typecheck
      - npm test

Define one or more modes. Each mode is an ordered list of stages. Each stage is either parallel or sequential, and holds a non-empty array of shell command strings. Mode names are arbitrary — note: "init" is reserved as a subcommand and cannot be used as a mode name.

Behavior

• Stages run one after another (stage 2 starts after stage 1 finishes).
• Within a stage, parallel runs commands concurrently; sequential runs them in order.
• Fail-through: If one command in a stage fails, other commands in that stage still run; the stage then fails as a whole.

Validation rules

• The config must be a non-empty object.
• Each mode’s value must be an array of stages.
• Each stage must have exactly one of parallel or sequential (not both).
• Command lists must be non-empty arrays of non-empty strings.

Development

bun install
bun run build   # outputs to dist/
bun run dev     # tsc --watch

Changelog

See CHANGELOG.md.

License

MIT — see LICENSE.