Skip to main content

eurysx

eurysx version

Local-first usage observability for Claude Code, OpenCode, Pi, and Codex.

Eurysx reads local agent history and reports tokens, requests, turns, tool calls, estimated or recorded cost, and pricing provenance. It does not upload usage data or persist prompts, responses, file contents, tool arguments, or tool results.

Eurysx v0.1.1 is a local CLI, not a hosted service.

What the name means

Eurysx is derived from Euryphaessa, an epithet associated with broad-shining light. Its eury root suggests a wide view; s evokes stats or sight, and x marks cross-agent work. It is a compact name for seeing usage across coding harnesses without pretending that their routes, prices, or records are interchangeable.

Our philosophy

eurysx is built around a few principles:

  • Local history is evidence, not telemetry: usage stays on the machine and sensitive session content is neither persisted nor reported.
  • Unknown stays unknown. Eurysx does not invent a price, provider route, or billing mode when the available records cannot support one.
  • Recorded cost wins over policy. Configurations make user intent explicit; they do not rewrite what a harness recorded.
  • One normalized view should preserve provenance. Comparable reports must still show where data and pricing came from.
  • The tool remains a small, local CLI, not a hosted analytics service or an agent-management platform.

Eurysx makes agent usage visible without taking ownership of it.

Install

pip3 install eurysx
eurysx --help

Run

eurysx --version
eurysx
eurysx --agent codex --days 30
eurysx --agent all --month 2026-08
eurysx --agent pi --from 2026-08-01 --to 2026-08-15
eurysx --agent all --days 30 --output reports/usage.json
eurysx --refresh-pricing
eurysx collect --agent codex
eurysx report --agent codex --days 30
eurysx doctor

reports/ is ignored by Git.

eurysx collects current local metadata and then reports it. collect stores metadata only; report reads the local store without collecting. doctor is terminal-only and reports local harness, source, pricing-cache, and configuration health without parsing history, refreshing prices, or deleting retained data. During Act II, the store is data/eurysx.db relative to the current project directory. Set EURYSX_DATA_DIR only to deliberately relocate it.

Period selectors are mutually exclusive: --days N, --weeks N, --from YYYY-MM-DD [--to YYYY-MM-DD], --month YYYY-MM, --quarter YYYY-QN, --year YYYY, and --ytd. Rolling periods include today.

Filter selectors --model, --provider, and --billing-mode narrow the analyzed rows and combine with --agent and the period selectors; bounded period runs also compare against the same-length previous window. See the operational manual for details.

Documentation

The operational manual is the authoritative command, output, configuration, and diagnostics reference. Legacy CLI and output pages redirect there.

This manual is the authoritative contract for the JSONC configuration files.

Configuration manual

Eurysx is checkout-local during Act I. It reads and writes only these paths by default, relative to the directory where you run eurysx:

eurysx/
├── config/pricing.jsonc
├── config/preferences.jsonc
└── cache/

It does not use ~/Library/Application Support, XDG directories, or other system-level application folders. The local configuration and cache are ignored by Git. Create them from the tracked templates:

cp config/pricing.jsonc.sample config/pricing.jsonc
cp config/preferences.jsonc.sample config/preferences.jsonc

Both files are JSONC: comments and trailing commas are allowed. Both are optional. Without them, Eurysx retains recorded usage and marks unresolved cost as unknown. Use EURYSX_CONFIG_DIR and EURYSX_CACHE_DIR only when deliberately relocating those two directories, for example to a removable development volume.

preferences.jsonc: agent and provider policy

preferences.jsonc declares a schema version 3 policy. An agent-level policy applies to every model when the collector has no provider metadata. providers overrides that policy only for an exact recorded provider. A provider policy can add explicit modelIdRules using literal exact or prefix matchers. Exact wins; otherwise the longest matching prefix wins. Invalid or duplicate exact rules warn and use the provider policy. Rules may override provider, billingMode, pricing, and budget; Eurysx never infers an upstream proxy route.

{
  "schemaVersion": 3,
  "agents": {
    "claude-code": {
      "provider": "amazon-bedrock",
      "billingMode": "metered",
      "pricing": {
        "source": "amazon-bedrock",
        "otherSources": ["models-dev", "pi-models-store"]
      }
    },
    "codex": {
      "providers": {
        "openai": { "billingMode": "subscription" },
        "amazon-bedrock": {
          "billingMode": "metered",
          "pricing": { "source": "amazon-bedrock", "otherSources": ["models-dev"] }
        },
        "litellm": {
          "billingMode": "unknown",
          "modelIdRules": [{ "prefix": "local.", "billingMode": "local" }]
        }
      }
    }
  }
}

schemaVersion and agents are the expected top-level fields. schemaVersion is currently informational; Eurysx does not reject the file based on its value. The file itself and each agent entry are optional. Omit an agent entry when you want its usage to remain unclassified. Supported agent keys are claude-code, codex, opencode, and pi; unknown keys are ignored.

Policy field Required? Meaning
provider Optional Effective provider when the collector does not record one. Usually needed for an agent-level metered policy.
billingMode Optional metered, subscription, credit, quota, local, or unknown. Omit it to let a matching provider policy decide; if no policy supplies it, Eurysx uses unknown.
providers Optional Map of exact recorded provider names to policy objects. Provider-policy fields override the agent-level fields.
modelIdRules Optional Provider-scoped list of one-key exact or prefix rules. A matching rule may override provider, billingMode, pricing, and budget.
pricing Optional Pricing lookup policy. For a config-priced metered route, include at least one valid source or otherSources entry.
pricing.source Optional Primary enabled source name from pricing.jsonc.
pricing.otherSources Optional Ordered enabled fallback source names from pricing.jsonc.

subscription, credit, quota, and local report N/A incremental USD. metered resolves pricing. A source name that is missing, disabled, or lacks an exact provider/model price is skipped. Recorded harness cost always wins.

For an agent using more than one provider, omit agent-level billingMode rather than setting it to unknown or an empty value. JSON has no useful blank value here: "billingMode": "" is invalid policy data and is reported as unknown. For example, Codex can classify its recorded OpenAI route as subscription, its recorded Bedrock route as metered, and only LiteLLM model IDs matching an explicit local. rule as local. If a record has no provider, or its provider is absent from providers, its billing mode is unknown unless the agent-level policy defines one. Optional budgets use {"usd": 100, "period": "month"} under an agent or exact provider; invalid budgets disable pacing with a warning. Rule budgets pace independently from their parent provider budget.

Billing modes describe incremental cost, not capability:

Mode Eurysx cost treatment
metered Resolves per-token USD pricing.
subscription, credit, quota, local Reports N/A incremental USD. Eurysx does not allocate fees or convert credits.
unknown Retains usage and reports cost as unknown until you classify it or add pricing.

Recorded harness cost always wins. If a recorded cost conflicts with a non-metered policy, Eurysx keeps the recorded cost and warns.

pricing.jsonc: price sources and manual overrides

pricing.jsonc supplies per-million-token USD prices only for metered usage. It has sources, provider-scoped aliases, and overrides. The file is optional. Configure an enabled source before naming it in pricing.source or pricing.otherSources.

{
  "schemaVersion": 2,
  "sources": {
    "amazon-bedrock": {
      "enabled": true,
      "profile": "your-aws-profile",
      "region": "ap-southeast-1",
      "refreshDays": 7
    }
  },
  "aliases": {
    "amazon-bedrock": {
      "claude-sonnet-4-6": "global.anthropic.claude-sonnet-4-6"
    }
  },
  "overrides": {
    "amazon-bedrock/bedrock.gpt-5.6": {
      "input": 0,
      "output": 0,
      "cacheRead": 0,
      "cacheWrite": 0
    }
  }
}

Supported sources are:

Source Required when enabled Optional Reads from
amazon-bedrock enabled: true, profile, region refreshDays aws pricing get-products for Amazon Bedrock.
pi-models-store enabled: true refreshDays ~/.pi/agent/models-store.json.
models-dev enabled: true, url refreshDays The configured models.dev-compatible URL.

Aliases map collector model names to a source's canonical model ID without changing billing policy. Override keys are provider/model; values are USD per one million tokens. An override requires input and output; cacheRead and cacheWrite are optional and default to zero. Never use a bare model override to price multiple providers.

Resolution order is: recorded cost, explicit override, the route primary source, the route's otherSources in order, then unknown. Eurysx never guesses a number for an unpriced model.

Refreshing and inspecting pricing

Eurysx creates cache/ in the current project directory on every run. Enabled sources cache normalized results in cache/pricing-<source>.json. Use the normal command to use a fresh cache, or force a refresh:

eurysx --refresh-pricing

If refresh fails, Eurysx uses a valid existing cache and reports a warning. If no valid price is available, the associated metered usage remains unknown rather than being reported as free. The cache contains pricing metadata, not prompts or credentials. Do not add API keys or LiteLLM master keys to either configuration file.

Current limits

  • Claude Code's stats cache is aggregate-only. Eurysx excludes it from selected date ranges and reports a scope warning; it remains available for all-time use. Its single row per model is stamped with lastComputedDate, so all-time Claude Code rates spread the whole aggregate over that observed span and its day-by-day activity table stays empty (n/a per-active-day lines) rather than inventing a one-day spike.
  • The supported collectors are Claude Code, OpenCode, Pi, and Codex only.
  • Pricing data is metadata only. Source pricing may be unavailable, in which case the relevant cost remains unknown.
  • Preferences use recorded route metadata or exact user rules. Eurysx does not call LiteLLM or provider APIs for route discovery and never reads credentials.
  • A report with usage entries but no tokens displays priced-token coverage as N/A.
  • Collector fixtures verify known file shapes, not every live harness release.

Development

PYTHONPATH=src python3 -m unittest -v tests/test_eurysx.py
python3 -m py_compile src/eurysx/*.py

Sanitized collector fixtures cover Claude Code, Codex, Pi, and OpenCode. The OpenCode SQL fixture builds a temporary SQLite database during the test rather than committing a binary database file.

Metadata

Release files for eurysx 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for eurysx 0.1.1
File Size Uploaded Provenance Actions
eurysx-0.1.1.tar.gz 59.8 kB With provenance Details for eurysx-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for eurysx 0.1.1
File Interpreter ABI Platform Actions
eurysx-0.1.1-py3-none-any.whl Python 3 none any Details for eurysx-0.1.1-py3-none-any.whl

Total release size: 102.2 kB

Release files / eurysx-0.1.1.tar.gz

Download URL eurysx-0.1.1.tar.gz
Size 59.8 kB
Tags Source
SHA-256 checksum
How to use checksums
61eb58db60de5048d411e0b35aab3dab0ddb374c520afb69a358c8cd9e02fae8
BLAKE2b-256 checksum
How to use checksums
09da901a671975fb56580c44bc0e89e40c528ce4975d48489ae6b80a4b87e012
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 15, 2026.

Transparency log

Release files / eurysx-0.1.1-py3-none-any.whl

Download URL eurysx-0.1.1-py3-none-any.whl
Size 42.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4231219126b1d6cd1d7441e907289c09820250ca859609eaec73067ff085e7b4
BLAKE2b-256 checksum
How to use checksums
51f50ab344ba690b1b12ffadb8f81c8150cbd52ba1967fc93c947818d3128cfa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 15, 2026.

Transparency log

Security for eurysx 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for eurysx-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page