Cost tracking plugin
Generic, provider-agnostic cost tracking for the Crystal Lattice platform.
Cost-aware providers emit the cost_tracking capability tag and stamp a
provider-defined cost bucket into request metadata. This plugin records one
row per request into a SQLite store, feeds the chat status bar a store-backed
session total, and exposes report and reset actions.
Components
CostTrackingExtension(provider extension,required_tags: ["cost_tracking"]): records one row per request and stamps the store-backed session total into message metadata (cost_session_total,cost_session_total_formatted,cost_session_requests).CostTrackingAppPlugin(application plugin): session actions Show cost report and Reset cost tracking.
Store
Default path: cost-tracking/cost-tracking.sqlite3 under the Crystal data
directory (CRYSTAL_DATA_DIR, default ~/.crystal); override with the
cost_tracking_db_path config key (extension config, or
application.cost_tracking.db_path for the application plugin).
Tables:
cost_requests— one row per request:time,bucket,session_id,working_directory,model,response_id(unique — re-finalize/rebuild paths cannot duplicate rows), token counts (input_tokens,cached_tokens,cache_write_tokens,output_tokens,reasoning_tokens),estimated_cost,actual_cost, and per-item cost columns (input_cost,cached_cost,cache_write_cost,output_cost) filled from the provider'susage_cost_breakdownwhen available. Databases created before the per-item columns existed are migrated in place on first open.cost_resets— reset markers (time,bucket).
Cost columns: actual_cost holds a cost reported by the provider (for
example usage.cost); estimated_cost holds the provider's estimate when no
actual cost is available. Totals prefer the actual cost and fall back to the
estimated cost.
All writes are best-effort: failures are swallowed and never break the request pipeline.
Summary CSV
A growing cost-tracking-summary.csv is appended beside the SQLite store.
One row is appended per freshly recorded request, plus one marker row per
reset. Columns:
time— same timestamp as the store row (or the reset marker time).bucket— the provider-defined cost bucket.working_directory/session_id/model— the request's project (workspace), session, and model.cost— the per-request cost (actual when the provider reported one, otherwise the estimate).session_total_cost— rolling total for the (working_directory, session_id) pair; factual history, not affected by resets (matches the footer semantics).bucket_total_cost— rolling total for the bucket since its most recent reset marker (matches the report semantics); reset marker rows carry0.0here with the request columns empty.
Rows are only appended for freshly inserted store rows — duplicate response ids (re-finalize/rebuild paths) never append. CSV writes are best-effort and never break the request pipeline or the reset action.
Buckets
The bucket base can be altered by config (cost_bucket), but the final
bucket is always defined by the provider that emits the capability tag:
openai_responses:<base>-chatgptfor the ChatGPT backend,<base>-apifor the OpenAI API (default baseopenai-responses).reference-openai-compatible-provider:<base>-<endpoint-host-slug>(default baseopenai-compatible), e.g.openai-compatible-api-fireworks-ai.
Footer total and cost breakdown
The extension contributes status_bar UI elements for the current
workspace + session id, aggregated from the store on every request. Session
totals are factual history and are not affected by reset markers.
The total footer is always contributed and unchanged:
Total: {{data}} rendering metadata.cost_session_total_formatted.
The breakdown items are separate fields with separate UI elements. The
total_usage_breakdown config key ("Total usage breakdown") selects which
elements are contributed:
none(default): only the total footer.totals: total, then one element per item —input:,cached input:,cache write:,output:— thenrequests:.averages: total, thenrequests:,average:, then one element per item average —input:,cached input:,cache write:,output:.
Elements are emitted in that order and the platform renders status bar
elements in list order; each element carries an exists condition, so
items without recorded data simply do not render (a provider that reports
only a total cost shows just the total, requests, and average).
The choice is exposed as a config UI element (type: select, key
total_usage_breakdown, label "Total usage breakdown") like the duration
plugin's "Show duration" setting; the core extracts config elements from
the status bar flow, and the element stays editable even when
show_cost_status_total gates the status bar off.
Both variants are always stored in message metadata as separate raw and formatted fields, regardless of the config choice (the choice only controls display):
cost_session_total(_formatted),cost_session_requests,cost_session_requests_formatted,cost_session_average_cost(_formatted)- per item (
input,cached,cache_write,output):cost_session_<item>_cost(_formatted)andcost_session_<item>_cost_avg(_formatted)
Per-item costs come from the provider's usage_cost_breakdown metadata:
openai_responses computes them from the pricing snapshot or the manual
ChatGPT table (with estimated cached tokens), and the reference provider
from token_rates (including an optional cache_write rate; cache-write
cost is skipped when the endpoint does not report cache-write tokens or
no rate is configured).
Actions
- Show cost report: reset-aware totals per bucket and overall, with
request counts and each bucket's last reset time, plus the top 10
sessions and top 5 projects by cost over the same reset-aware window
(working directories resolved to project names via
projects.jsonunder the Crystal data directory, falling back to the raw path). - Last 7 days by project (always shown when the window has data): one
row per local calendar day covering today and the six preceding days,
zero-filled; columns are the day total, the top 3 projects by cost over
the window (resolved names), and an optional
Restcolumn aggregating the remaining projects when more than 3 have data. - Last 7 days by bucket: same table shape with the top cost buckets
in the columns, shown only when more than one bucket has data in the
window (with a single active bucket it would just repeat the Total
column). Both daily tables use the same reset-aware request set and
cost preference (
actual_costoverestimated_cost) as the rest of the report, and are also returned programmatically asdaily_projects/daily_buckets({day: {key: cost}}). - Reset cost tracking: appends a reset marker for one bucket (form
dialog with a
buckettext field). Subsequent report totals for that bucket cover only records recorded after the marker; recorded history is preserved.
Configuration
Extension config keys:
track_costs(boolean, defaulttrue): record cost rows.cost_tracking_db_path(string, optional): store path override.show_cost_status_total(boolean, defaulttrue): contribute the status-bar session total.total_usage_breakdown(string, default"none", label "Total usage breakdown"): which breakdown status-bar elements to contribute —"none","totals", or"averages".track_cost_tracking_summary_csv(boolean, defaulttrue): append the summary CSV rows.cost_tracking_summary_csv_path(string, optional): summary CSV path override (defaults tocost-tracking-summary.csvbeside the store).
Application plugin config (application.cost_tracking):
db_path(string, optional): store path override for the report/reset actions when the session config does not carry one.