SubValue

Local, read-only Codex and Claude Code API-equivalent usage analysis. No account, API keys, cloud database, AI calls, uploads, or telemetry.

Install

Requires Node.js 24.13 or newer on Windows, macOS or Linux.

npx @subvalue/cli --dry-run
npx @subvalue/cli

For optional installation from a local package, see Package validation.

Run locally

Requires Node.js 24.13 or newer. Runtime and production build have no external dependencies.

For development, install dependencies with npm ci --ignore-scripts. Run npm run check for formatting, TypeScript, ESLint, build and unit/integration tests, then npm run test:e2e for browser and receipt-export checks. npm run format applies the shared format; CI rejects formatting drift on Windows, Linux and macOS.

npm run build
npm start -- --dry-run
npm start

The CLI scans both providers, stores normalized metadata in the OS application-data directory (%LOCALAPPDATA%/SubValue on Windows, ~/Library/Application Support/SubValue on macOS, $XDG_DATA_HOME/subvalue or ~/.local/share/subvalue on Linux), binds to 127.0.0.1:4731 (an OS-selected loopback port if occupied), and opens the default browser. It never modifies provider files.

npm start -- --no-open
npm start -- --scan-only
npm start -- --verbose
npm run demo

--demo is explicitly labeled fixture data, does not scan local providers, and does not create a usage database. --port selects the local port. --dry-run checks provider-directory metadata only: no session contents, database, or server.

Interface

• Overview: 7D / 30D / Month / Custom, API equivalent, user-declared billing, optional subscription comparison, providers and daily known API value.
• Receipt: local canvas preview and PNG export of the exact same pixels. No projects, paths, requests or sessions in exports.
• Settings: Sources, Billing, USD, Privacy / data. Inactive providers stay here, with optional manual inclusion.

First run offers subscription plans for each provider with imported usage. Choose a plan, a custom USD amount, or No subscription · API independently for Codex and Claude Code. Subscription + API is available as a checkbox. Unconfigured or legacy no-subscription settings default to API as an editable preference; this does not prove how any historical request was billed. Actual API payments remain unknown until entered for a specific period.

Month opens a floating calendar-month picker (including historical months). Previous/next arrows move by one calendar month, seven or thirty days for rolling presets, or the selected custom duration. Month comparisons use the full declared monthly price; the current month is marked In progress. 7D and 30D show API-equivalent usage without subscription comparisons. Custom dates prefill the registered plan and let each provider's actual payments be confirmed for those exact dates, including a period crossing months or a cancelled subscription followed by API usage. No prorating is applied. Complete calendar-month ranges retain their monthly comparisons unless an exact payment total is confirmed. Amounts and API prices are USD; no invented exchange rates. Billing declarations do not overwrite historical records or prove their original billing mode. Settings offers bundled, verified ChatGPT/Claude plan presets and a custom amount. Annual presets retain the exact annual price divided by 12, with per-seat plans labeled.

Source access

Only these session inputs are opened by the scanner:

~/.codex/sessions/**/*.jsonl
~/.codex/archived_sessions/*.jsonl
~/.claude/projects/**/*.jsonl

No credentials, auth files, repositories, attachments, clipboard caches, shell history or browser data. The optional Claude stats cache is deliberately not imported in V1 because its history cannot be allocated safely by request/date. Directories referenced by session metadata are never opened. Project-path values are skipped by the metadata extractor.

Transcripts contain conversation text alongside metadata, so their bytes must be streamed to locate usage fields. A metadata-only JSON extractor decodes approved counters, dates, models and necessary deduplication fields for both providers. Prompt, response, instruction and tool-content values are skipped without constructing their strings or objects. Raw buffers are discarded after each line. No conversation content is persisted, logged, sent to the browser, or exported.

Accuracy and pricing

0, UNKNOWN, NO DATA, and partial history are distinct. Null fields are never filled with zero. Each record carries provenance, schema, quality and metadata-only source identity. Token completeness and pricing coverage are separate; percentage priced describes imported records, not all historical activity.

Codex excludes inherited ordinal prefixes, uses cumulative deltas, suppresses repeated counters, segments counter resets and preserves unallocated totals. Claude deduplicates message/request identities and does not add nested iteration usage. Conflicting duplicates fail closed as incomplete.

The versioned catalog supports mappings with confidence and primary-source provenance, half-open effective intervals, cache reads/writes, Claude cache durations, and long-context bands. Rates and release evidence were checked against OpenAI pricing and Claude pricing on 2026-10-23. OpenAI's optional 12-hour cache-write tariff is recorded from October 20; coding logs without lifetime counters continue to use the default 30-minute API-equivalent estimate, not a reconstructed 12-hour invoice. Historical versions retain the July 30 Luna/Terra reductions, August 21 Sol promotion and October 7 Sonnet 5.5 cache-read reduction. Claude Haiku 5.5 is covered from its October 7 launch, including its 100k request-context bands. Each event uses the tariff effective at its timestamp before period totals are summed. Date-only announcements apply from 00:00 UTC on the announced day, with no unpriced transition day. Historical rates are archived and protected by regression tests for future updates. Sol pricing after the confirmed promotion remains unavailable. See the pricing evidence ledger. Internal/unknown model identifiers are never mapped by resemblance.

Overview and receipt display the sum of priceable events; partial pricing stays visible and unknown model prices are never invented. Value is the displayed API equivalent minus total paid; Value Multiple is API equivalent divided by total paid (subscription plus declared API payments). A missing payment stays unknown; an explicit zero is accepted but cannot be a multiplier denominator. Custom comparisons require confirmed payments when dates do not cover complete calendar months. Partial pricing uses observed values without a certain outcome or break-even date.

Expense controls appear inside every active provider card on Custom. Other views retain controls for mixed billing, or a provider without a subscription while the other active provider has one. Select a plan using the same menu as onboarding, then confirm the actual subscription payment and/or API spend for the displayed dates; mixed mode starts its editable API field at $0. A suggested subscription amount is not a confirmed payment. Confirm for this period stores only that provider's exact civil-date selection. Confirmed subscription and API totals are counted once, even when the selection crosses months. Editing Month stores a monthly override and supersedes an equivalent exact-date declaration for that provider. Payments are not copied to neighboring selections. Settings also provides per-period editing and reset to the default. Saved overrides survive changes to the usual plan, receipt theme changes and relaunch. The scanner and usage records are unchanged.

When an active provider has not supplied its expenses, a labeled comparison uses only providers with known expenses; the overall API-equivalent figure still includes all observed usage. Empty periods show imported history bounds.

Architecture

apps/web/                 local UI + static public landing
packages/core/src/        normalized types, security, scanner, SQLite, summaries
  providers/codex/        Codex adapter
  providers/claude/       Claude adapter
  pricing/                versioned catalog + mapping + calculations
packages/receipt/         shared receipt model and canvas renderer
packages/cli/             executable, loopback HTTP server, packaged assets
tests/                    synthetic parser, pricing, storage and security fixtures
scripts/                  native build + browser validation

Streaming memory is bounded by a 16 MiB line limit. Checkpoints persist byte offsets, typed parser state, file identity and edge fingerprints, never raw trailing text. Unfinished lines are read again on the next scan. Appended files continue from the checkpoint; changed files are replaced transactionally. Missing sources retain cached history with a missing-file flag. Unchanged files require only small fingerprint checks, not a full stream. Provider-input links and junctions are rejected. Checkpoints cannot prove changes made deliberately while preserving metadata and the edge fingerprints; V1 assumes normally written local logs.

Development / validation

See Privacy and data access for the exact fields retained locally and network boundaries.

Usage refreshes incrementally at each normal CLI launch. While the dashboard is open, use Refresh usage on Overview or in Settings. Period controls only filter the imported cache; they do not scan source logs. The local application must still be running.

Agents with a terminal on the user's machine can run the same CLI with Node.js 24.13+ and permission to read the approved usage roots and write SubValue's local metadata directory. Use --scan-only --verbose to update the cache and exit, or --no-open to serve the dashboard without opening a browser. This is CLI interoperability, not a dedicated MCP integration. Only Codex and Claude Code source logs are supported; Hermes or other agents can launch the CLI, but their own usage formats are not imported.

npm test
npm run build
npm ci --ignore-scripts --no-audit --no-fund
npm run typecheck
npm run lint
npm run test:e2e

Only development validation requires npm dependencies. Inter and IBM Plex Mono fonts are bundled under their included OFL licenses, with no CDN requests. The native production builder uses Node's TypeScript stripping and produces JavaScript modules, static CSS and assets; no compiler runs at CLI launch. Type stripping is not a TypeScript typecheck.

Browser validation uses an isolated headless browser with fixture data. Windows uses installed Edge; elsewhere install Playwright Chromium for development. SUBVALUE_PLAYWRIGHT_MODULE can reference an already-installed official Playwright module. No personal browser profile is used.

GitHub Actions validates Windows, Linux, and macOS on both Apple Silicon and Intel. Each runner checks types, lint, build, unit/integration tests, responsive browser pages, receipt PNG export, and the locally packed CLI from a temporary directory outside the checkout. The package requires Node.js 24.13 or newer on each platform.

Static landing output is apps/web/dist, suitable for a static host including Vercel. It contains no local API server or user data. Its preview is marked as an example. The source repository is public at github.com/axelmtn/subvalue.

Package / release

npm run build
npm pack --workspace @subvalue/cli --ignore-scripts --pack-destination artifacts

Package contents are allowlisted to dist/, README, PRE_RELEASE, PRIVACY, and LICENSE. No lifecycle/postinstall scripts or runtime dependencies. Local databases, exports, attachments and test artifacts are ignored by Git and excluded from npm contents.

Manual npm releases use the audited package and do not claim a provenance attestation. The source repository is public. The future release workflow remains disabled until trusted publishing is configured and NPM_PUBLISH_ENABLED=true is set. It uses a protected environment and OIDC rather than a permanent npm token.