Contributing

Everything you need to send a working pull request.

Prerequisites

Node.js 22.20 or newer
npm 10 or newer
macOS or Linux for full provider coverage
Optional: Swift 6 toolchain for macOS menubar (mac/)
Optional: GNOME 45+ for the GNOME extension (gnome/)

Setup

git clone https://github.com/getagentseal/codeburn
cd codeburn
npm install

Common Commands

Command	What it does
`npm test`	Runs the vitest suite (42 files, 568 tests)
`npm run dev -- status`	Runs CLI in dev mode against real data
`npm run build`	Bundles litellm pricing, then tsup to `dist/cli.js`
`npm run bundle-litellm`	Refreshes litellm pricing snapshot

Project Layout

src/                CLI, parsers, optimize detectors, cache layers
src/providers/      One file per AI tool integration
src/data/           Bundled litellm pricing snapshot
tests/              vitest specs
mac/                Swift menubar app
gnome/              GNOME shell extension
scripts/            Build helpers

Coding Conventions

TypeScript strict mode. No any without a comment explaining why.
No bracket-assign on parsed user input in hot paths - enforced by Semgrep in CI.
Provider parsers must be deterministic. If you read the clock or filesystem outside documented paths, add a fixture-based test.
Lazy-load heavy native dependencies so users without that provider aren't slowed down.

Tests

Each new provider needs a fixture-based test under tests/providers/
Each new optimize detector needs positive and negative cases in tests/optimize.test.ts
Changes to the menubar JSON contract need updates in tests/menubar-json.test.ts

Pull Requests

Fork or branch from main
Push your branch and open a PR
CI runs Semgrep and co-author checks automatically
Squash-merge is the default

Reporting Bugs

File issues at github.com/getagentseal/codeburn/issues. Include codeburn --version, the provider involved, and output with DEBUG=1 if applicable.

Sponsoring

If CodeBurn is useful to you or your team, consider sponsoring development on GitHub.

JSON Output Sponsors & Credits