codeburn - Moses Yebei

Abstract

Free, local tool to track AI coding token usage and cost across 37 tools and agents (Claude Code, Cursor, Codex, Gemini and more), by model, project, and task. npx codeburn

The Problem

Developers using AI‑assisted coding tools have no easy way to see how many tokens each model consumes per project, nor the resulting cost. Without visibility they can overspend on expensive models (Claude, Gemini, etc.) or miss opportunities to optimise prompts.

What This Does

codeburn is a local desktop app that proxies calls to 37 supported AI coding agents, records token counts, and aggregates spend by model, project and task. The UI lives in app/renderer/ (React/TSX components such as App.tsx, Sidebar.tsx, Spend.tsx). Core bookkeeping lives in src/ – e.g. src/parser.ts parses provider responses, src/models.ts defines the spend model, and src/providers/ contains per‑agent adapters. The Electron entry points (app/electron/cli.ts, app/electron/main.ts) start the process, load the quota manager (app/electron/quota/), and expose an IPC layer used by the renderer.

How It Is Wired

Execution begins at app/electron/cli.ts (the packaged CLI). It parses command‑line arguments, then creates the Electron main window via app/electron/main.ts. The main process loads the quota manager (app/electron/quota/index.ts) which registers each provider’s token‑tracking hook (e.g. app/electron/quota/claude.ts, codex.ts).

Renderer code (app/renderer/main.tsx) boots React, importing the UI library app/renderer/lib/ (formatters, IPC wrappers). UI actions (e.g. opening the “Spend” view) call ipc.invoke('track-token', payload) which is handled in app/electron/quota/index.ts. That module forwards to the appropriate provider adapter in src/providers/ – each adapter ultimately calls the external AI endpoint and returns the token usage.

All token records are persisted via SQLite (src/sqlite/), accessed by src/main.ts (the high‑level orchestrator) which writes rows to usage tables. The central type hub src/types.ts (imported by 102 other modules) defines the data contracts used throughout the stack.

The import graph shows 476 internal modules with 1 250 edges; src/parser.ts sits in a small cycle with src/providers/index.ts and src/optimize.ts, giving those files a high blast radius. src/main.ts has the highest instability (imports 37 modules, imports none) and acts as the final sink before data is written.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/codeburn
cd codeburn

# Install dependencies (npm is inferred from package.json)
npm ci

# Build the Electron app (vite config present)
npm run build   # script defined in app/package.json

# Run the CLI (entry point)
node ./app/electron/cli.js   # or npx codeburn after global install

Configuration lives in app/electron/quota/ – each provider expects an API key in the environment (e.g. CLAUDE_API_KEY, GEMINI_API_KEY). No explicit config file is shipped; the README points to the README.md for key names.

Real‑World Use

A CI pipeline can wrap npx codeburn around any npm run lint step. After each AI‑generated patch, the tool logs a row like:

{
  "model": "claude-2.1",
  "project": "frontend",
  "tokens": 124,
  "cost_usd": 0.0012
}

Teams can query the SQLite DB to enforce per‑project budgets or to surface the most expensive prompts in a dashboard.

Code Health & Issues

HIGH – Pin GitHub Action versions to commit SHA (.github/workflows/*).
HIGH – CI does not run the test suite (.github/workflows/*).
MEDIUM – No least‑privilege GITHUB_TOKEN permissions (ci.yml).
MEDIUM – Dependabot / Renovate missing (package*.json).
MEDIUM – No dependency‑vulnerability scan in CI.
MEDIUM – Generated build output committed (app/), should be ignored.
MEDIUM – Checkout step keeps token (build-snap.yml); set persist-credentials: false.
LOW – No job timeouts in several workflows (build-snap.yml).
LOW – Repository lacks convention files (.editorconfig, formatter config).

Additional static findings:

HIGH – Oversized files (src/parser.ts, src/models.ts, src/optimize.ts > 3 k lines).
HIGH – Import cycles involving src/parser.ts, src/providers/index.ts, src/optimize.ts.
HIGH – Hub module src/types.ts (102 dependents) makes any change high‑risk.
MEDIUM – High branching density in src/parser.ts and related utilities.

The Bottom Line

codeburn delivers a functional, locally‑run dashboard for AI token accounting, with a clear Electron‑React stack and a well‑scoped SQLite backend. The codebase is usable but suffers from large, tightly‑coupled modules, import cycles, and several CI hygiene gaps that should be addressed before heavy production reliance. Teams that need immediate visibility into AI spend can adopt it, provided they allocate effort to refactor the hub files and tighten the CI pipeline.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

764 files

TypeScript394
TSX79
Swift71
Markdown60
JSON15
YAML11

React

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["tests 203 modules"] g1["src 142 modules"] g2["app 109 modules"] g3["dash 15 modules"] g4["gnome 4 modules"] g5["(root) 2 modules"] g0 -->|452| g1

Module dependencies

The 10 most depended-upon modules of 476, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_src_types["types"] n1_src_providers_types["types"] n2_src_models["models"] n3_src_parser["parser"] n4_app_renderer_lib_types["types"] n5_src_sqlite["sqlite"] n6_src_fs_utils["fs-utils"] n7_src_bash_utils["bash-utils"] n8_src_providers_index["index"] n9_src_session_cache["session-cache"] n3_src_parser --> n6_src_fs_utils n3_src_parser --> n2_src_models n3_src_parser --> n8_src_providers_index n3_src_parser --> n5_src_sqlite n3_src_parser --> n9_src_session_cache n3_src_parser --> n1_src_providers_types n3_src_parser --> n0_src_types n3_src_parser --> n7_src_bash_utils n8_src_providers_index --> n1_src_providers_types n1_src_providers_types --> n0_src_types n9_src_session_cache --> n0_src_types classDef cyc stroke:#ef4444,stroke-width:2px; class n3_src_parser,n8_src_providers_index cyc;

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium5

low2

Pin third-party GitHub Actions to a commit SHAhigh

.github/workflows

softprops/action-gh-release@v3

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Make CI invoke the test suite it hashigh256 occurrences

.github/workflows

256 test files, no test command in the 4 workflows read

A green check that never executed an assertion is worse than no check, because reviewers trust it.

Fix: Add a test step to the existing workflow rather than a new workflow.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/ci.yml

1 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

3 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Remove generated build output from version controlmedium5 occurrences

app

5 generated files committed

The reviewer reads src, production runs dist, and a stale bundle means the fix that was reviewed is not the code that executes.

Fix: Gitignore the output directory and build in CI.

Set persist-credentials: false on checkoutmedium

.github/workflows/build-snap.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/build-snap.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.