sidegrade

Purpose

sidegrade solves the problem of opaque costs when using coding agents. It reads the Claude Code, Codex, Hermes, and OpenCode session logs already on your machine, analyzes your actual token usage structure, and then tells you: which model is cheaper while maintaining an equivalent level of intelligence; and which cheaper tier is worth using with a slight downgrade.

Main capabilities

• Reads local coding agent session logs and extracts token counts.
• Scores each candidate model based on the Artificial Analysis Intelligence Index (rounded to the nearest integer).
• Reprices each model according to your actual token mix (output, new input, cache reads, etc.).
• Outputs a report sorted by intelligence level and price, without favoring any provider—a row wins only because that model is the cheapest for that source.
• Supports outputting JSON via npx sidegrade --json , making it easy to let the agent reason about the results itself within a coding agent session.

How to use

No installation, no account, no configuration required. Just run:

npx sidegrade

You can also paste the instruction directly into your coding agent (Claude Code, Codex, Cursor, etc.) and have it run sidegrade and tell you what to do, without a terminal.

After running, a report is generated based on your actual usage. The numbers in the official examples are illustrative only; the actual report reflects your own machine's data.

Supported agents

• Claude Code — reads ~/.claude/projects
• Codex — reads ~/.codex/sessions
• Hermes — reads ~/.hermes/state.db in session_model_usage(read via the system sqlite3; verified with real data and covered by fixture tests; skipped if sqlite3 is unavailable)
• OpenCode — reads ~/.local/share/opencode(reads storage/session/message; matches the v1.18.x message schema and is covered by fixture tests)

Adding other agents only requires writing a small read-only parser in src/parse.js ; PRs are welcome.

Data sources

• Intelligence scores: Artificial Analysis Intelligence Index (https://artificialanalysis.ai），取整后存放在 data/models.json.
• Prices: one file per provider, located in data/providers/, each file noting a link to its public pricing page. Some of the cheapest quotes come from QuickSilver Pro, an OpenAI-compatible gateway.

Privacy and limitations

• 100% local operation, reading token counts only from the agents' own log files.
• No network calls at runtime; prices and intelligence scores are bundled in the package. The only network access is npm / npx fetching sidegrade itself.
• No telemetry, no account, no API key required to run.
• Read-only: your prompts, code, file paths, and completions never leave your machine.
• Zero runtime dependencies; the entire tool is just a few small files that can be read in a few minutes.

When to use it

Suitable for developers using Claude Code, Codex, Hermes, or OpenCode who want to reduce model invocation costs without sacrificing intelligence level, or to evaluate whether it is worth switching to a cheaper model tier. Also suitable for calling directly within a coding agent session, letting the agent give recommendations based on the JSON results.

Provider participation

If you run an inference service, you can add pricing in about 2 minutes: add a file data/providers/<you>.jsonlisting your models and public prices, then submit a PR. CI will verify it automatically. See CONTRIBUTING.md for a template, or submit an issue via the "Add / update a provider" form.