mirror of https://github.com/AgentSeal/codeburn.git synced 2026-05-17 03:56:45 +00:00

Add Crush provider plus per-provider icon column in README (#286 )

Closes #278.

Adds Charmbracelet Crush as a lazy-loaded provider:
- src/providers/crush.ts: walks ~/.local/share/crush/projects.json
  (XDG_DATA_HOME and CRUSH_GLOBAL_DATA aware), opens each project's
  crush.db read-only, queries root sessions where parent_session_id
  IS NULL. Emits one ParsedProviderCall per session with real
  prompt_tokens, completion_tokens, cost (dollars), and the
  dominant model resolved from messages.model.
- src/providers/index.ts: register crush alongside cursor, goose,
  opencode, antigravity, cursor-agent in the lazy import path.
- tests/providers/crush.test.ts: 10 fixture-based tests covering
  discovery, parsing, missing-registry, malformed JSON, missing db,
  child session exclusion, dominant model selection, dedup, and
  array-shaped legacy registry.

Schema source: charmbracelet/crush@v0.66.1
internal/db/migrations/20250424200609_initial.sql, verified by
spawning a research agent against upstream. The schema *comments*
in that migration claim millisecond timestamps but every actual
INSERT/UPDATE uses strftime('%s', 'now') which returns Unix
seconds; the parser treats values as seconds. Tokscale's
parser (junhoyeo/tokscale#346) gets this wrong and is off by
1000x, plus its parser misses the prompt_tokens/completion_tokens
columns that exist in Crush's schema. Our integration uses both,
so Crush sessions get real per-model attribution.

Menubar:
- mac/Sources/CodeBurnMenubar/AppStore.swift: add .crush case to
  ProviderFilter and its cliArg switch.
- mac/Sources/CodeBurnMenubar/Views/AgentTabStrip.swift: add
  Crush color to the per-tab color extension. The visibleFilters
  computed property already filters by detected providers, so the
  Crush tab appears automatically when a user has Crush data.

README:
- Replace the provider table with an icon-led layout. Icons live
  under assets/providers/<name>.<ext>. 14 icons sourced from
  junhoyeo/tokscale (MIT) under nominative fair use, 4 sourced
  separately: codex (OpenAI org avatar), cursor-agent (reuses the
  Cursor icon), kiro (kiro.dev favicon, ico->png via sips), omp
  (can1357/oh-my-pi icon.svg, MIT). Attribution line added.
- Add Crush row.

Docs:
- docs/providers/crush.md: full per-provider doc with verified
  schema excerpt, the seconds-vs-milliseconds quirk, and a
  "when fixing a bug here" checklist.
- docs/architecture.md: provider count 17 -> 18, test count
  41 -> 42, and crush in the lazy list.
- docs/providers/README.md: add Crush row to the lazy index.
- CONTRIBUTING.md: bump test count to 568 (was 558).

All 568 tests pass locally; swift build clean.

2026-05-09 20:47:56 -07:00

4.8 KiB

Raw Permalink Blame History

Contributing to CodeBurn

Thanks for your interest. This document covers what you need to know to send a working pull request.

Prerequisites

Node.js 22.20 or newer (engines.node in package.json).
npm 10 or newer (ships with recent Node).
macOS or Linux for full provider coverage. Windows works for most providers but Cursor / Antigravity development is easier on macOS.
Optional: Swift 6 toolchain if you are touching the macOS menubar (mac/).
Optional: GNOME 45 or newer if you are touching the GNOME extension (gnome/).

Setup

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

There is no separate build step required to run the dev CLI. npm run dev runs tsx against src/cli.ts directly.

Common Commands

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

To test a specific suite, pass a path:

npm test -- tests/providers/codex.test.ts

What to Read Before Editing

docs/architecture.md for the high-level codebase map.
docs/providers/<name>.md for the provider you intend to change.
RELEASING.md if you are touching version bumps or the release pipeline.
SECURITY.md for the disclosure policy.

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 (litellm bundle)

See docs/architecture.md for a fuller map.

Coding Conventions

TypeScript strict mode is on. Do not introduce any without a comment explaining why.
Avoid bracket-assign (obj[key] = value) on parsed user input in hot paths inside src/providers/ and src/parser.ts. There is a Semgrep rule (.semgrep/rules/no-bracket-assign-hot-paths.yml) enforced in CI that will fail your PR if you do. Use a Map or an explicit allowlist instead.
Provider parsers must be deterministic given the same input. If you read the system clock or the filesystem outside the documented session paths, add a fixture-based test.
New providers go through src/providers/index.ts. Lazy-load anything that pulls a heavy native dependency (sqlite, protobuf) so users without that provider are not slowed down.

Tests

Each new provider should ship with a fixture-based test under tests/providers/. The five providers without test files today (claude, gemini, goose, qwen, antigravity) are a known gap; new code should not add to that list.
Each new optimize detector in src/optimize.ts needs at least one positive and one negative case in tests/optimize.test.ts.
If your change affects the menubar JSON contract, update tests/menubar-json.test.ts.

Commit Message Format

Short imperative subject, optional body. Examples from git log:

Enhance GNOME extension with scrollable UI, dark mode, charts, and performance fixes
Add table column headers, oneshot placeholder, currency picker dropdown

No AI Co-Author Trailers

The .github/workflows/block-claude-coauthor.yml workflow rejects any PR whose commits contain a Co-authored-by: ... claude ... or ... anthropic ... trailer. You may use AI tools to help write code, but strip the co-author line before pushing.

If a flagged PR rejects on this check, the workflow prints the exact rebase command to fix it.

Pull Requests

Fork or branch from main.
Push your branch and open a PR against main.
The firstlook workflow will auto-assess the PR. The semgrep CI workflow runs the hot-path bracket-assign guard. The block-claude-coauthor workflow scans commits.
A maintainer reviews. For non-trivial changes, expect requests for tests.
Squash-merge is the default. Keep the PR title short and accurate; the description carries the context.

Reporting Bugs

File issues at https://github.com/getagentseal/codeburn/issues. Useful details:

Output of codeburn --version.
Provider involved and rough size of your session history (du -sh ~/.codex/sessions, etc.).
Output of the failing command with DEBUG=1 if applicable.
For parsing bugs: a redacted JSONL or SQLite snippet that reproduces the issue.

Security Issues

Do not file security issues in the public tracker. See SECURITY.md for the disclosure process.

License

CodeBurn is MIT-licensed. By contributing, you agree your contributions are licensed under the same terms.

4.8 KiB Raw Permalink Blame History