# Estimate your cost

> Get a free Synkro cost estimate from your agents' existing session history.

Source: https://docs.synkro.sh/guides/estimate

`synkro estimate` shows your agent usage and estimates what checking that activity
with Synkro would cost. It is free for signed-in accounts, including accounts
without a saved card or balance. You can use session history from before you
installed Synkro.

## Get an estimate

Run this from a project with installed Rule packages:

```sh
synkro estimate
```

Or choose a project:

```sh
synkro estimate --path /work/payments
```

The command reads all available session history retained by Codex and Claude
Code and calculates average daily usage, including inactive days. Codex history includes its
`sessions` and `archived_sessions` directories, with both `.jsonl` and
`.jsonl.zst` files. Copied records and resumed cumulative totals are not counted
again.
It shows one Synkro total in USD and a compact usage table.
It does not run Rule checks or charge your account.

The first run reads your retained history. Later runs reuse local accounting
for unchanged files and read new or changed files. Switching between day, week,
month and year reuses the same history; prices and project Rules are evaluated
again for each estimate. The cache contains usage accounting, not copied prompts
or tool output. It lives under Synkro's state directory in `estimate-cache`;
`estimate_cache_dir` can select another location. Removing it only makes the next
run read the history again.

Choose how far to project that same average:

```sh
synkro estimate --day
synkro estimate --week
synkro estimate --month
synkro estimate --year
```

These flags project 1, 7, 30 and 365 days respectively; they do not filter history
to the last day, week, month or year. The default is `--month`. Choose one flag.

If you have not set up project Rules yet, follow [Quickstart](/quickstart#add-the-project-and-verify-an-action)
and [Rules](/guides/rules). An estimate needs the selected project's installed
packages. It does not download missing packages; run `synkro lock` to resolve
them first.

## Read the estimate

The report leads with your estimated Synkro spend for the chosen period. It also
shows agent API-equivalent spend and Synkro's percentage when both estimates have
complete matching coverage. The **Average usage** table shows tool calls and
combined input/output tokens projected over that same period.
Incomplete amounts or token counts are marked **partial**; partially priced
agent spend is marked **subtotal**. The percentage is omitted when the two
figures cannot be compared. Detailed coverage remains available with `--json`.

Only agents with recorded usage appear in the table. If you have history for
just one, you get one row. If neither has usage, the command says so without
inventing a zero-dollar estimate. Installing an agent without using it does not
add an empty row.

Tables adapt to your terminal width. Set `NO_COLOR=1` for uncolored output;
`--json` includes the detailed coverage, model breakdowns and quote assumptions.
Display precision comes from `estimate_display` in [Settings](/reference/cli#settings):
`decimal_places` for amounts, percentages and observed days, and
`usage_decimal_places` for projected counts. Rounding does not change calculations
or JSON values.

The summary adds the available agent rows into one Synkro total. Both costs use
the same observed history and chosen projection. For example, a $6 Synkro estimate
against $300 of model usage is 2%. Synkro is an additional cost, not a replacement
for your coding agent or a claim that it saved $294.

The daily average is total recorded usage divided by elapsed days from the
earliest retained timestamp through now. Every agent uses that same denominator,
including quiet days and fractional days. Monthly averages are not averaged
together: months with different lengths and activity levels contribute their
actual totals. For example, 59,000 tokens over 59 days is 1,000 tokens per day,
projected as 7,000 per week or 30,000 per month. The output shows the observed
day count; JSON also includes the dates. Deleted history and sessions on other
machines are not included. To use an archive, supply its uncompressed JSONL directory.

Model cost is **API-equivalent**, not your subscription bill. The calculation
prices each recorded model separately and accounts for cached input, cache writes
and supported long-context tiers. When cache-write duration is unreported, it
uses short-lived cache rates. Discounts, speed or region premiums, subscriptions
and extra tool fees are not included. Unknown models and incomplete pricing
evidence stay `null` for those JSON samples; they are never silently priced as a different model.
Known prices still contribute to a **priced subtotal**. Coverage shows how many
usage records and tokens were priced in JSON, so that subtotal is not mistaken for the
cost of your entire history. Missing model prices do not prevent a Synkro quote
from valid tool-call records.

The bundled public rates have source URLs and verification dates in
`estimate_model_prices`. You can override that list through [Settings](/reference/cli#settings).
JSON includes the rate source and date for each model. Rates are not fetched
over the network when you run the command. Public rate references:
[model API pricing](https://developers.openai.com/api/docs/pricing) and
[Claude API pricing](https://platform.claude.com/docs/en/about-claude/pricing).

Actual Synkro charges depend on the actions checked, applicable Rules, retries
and refunds. For recorded charges, use `synkro account usage`.

The selected project's installed Rules are used for every agent in the estimate.
`--path` chooses that Rule package context; it does **not** filter session history
to that repository. To compare Rule packages, rerun with a different project.

Your agent's token count describes its work, not the tokens used for Synkro
checks. The estimate uses observed tool-call sizes and your Rule context, with
its assumptions included in JSON. Input totals include reported cache
usage, and output totals include reported reasoning usage. Those subsets are
not extra tokens to add again.

## Choose a history sample or session directory

```sh
synkro estimate --from 2026-10-01 --to 2026-10-21 --week
synkro estimate --session-root codex=/archive/codex/sessions
synkro estimate --session-root codex=/archive/codex/sessions --session-root claude_code=/archive/claude/projects
```

A date-only `--to` includes that whole day. Dates without an offset use your
configured `events_timezone` (local time by default). See [time formats](/reference/cli#events).
`--from` and `--to` optionally restrict the history used to calculate the average;
they do not change the projection selected by `--day`, `--week`, `--month` or
`--year`. Without these history filters, every flag uses all available history.

By default, Synkro looks in each agent's standard session directory. It also
honors `CODEX_HOME` and `CLAUDE_CONFIG_DIR`. Use one `--session-root HARNESS=PATH`
per agent to select another directory, such as an archive. Repeat the option for
different agents. Names are `codex` and `claude_code`.

## Available session data

| Agent | What the estimate can read |
| --- | --- |
| Codex | Timestamped tool calls and token usage from active and archived JSONL, including compressed `.jsonl.zst` files. |
| Claude Code | Timestamped tool calls and token usage from session JSONL. Repeated streaming messages and copied history are counted once. |

In JSON, `null` means unavailable, not zero. Notes explain missing directories, unsupported
formats or incomplete records. Valid, dated records still contribute to averages
and projections when other records are incomplete. Those results are labeled
**partial observed evidence**, with separate tool and token gaps in JSON. The
terminal summary marks a partial estimate and omits an unsupported percentage. Synkro does not
invent the missing activity or scale it up to fill those gaps. Without installed project Rules, usage can still be shown but
the cost quote is unavailable.

Session files are read without changes, and symbolic links are skipped. If a
scan reaches its file-count or total-byte limit, increase the corresponding
setting or choose a smaller `--session-root` directory. Narrowing dates does not
reduce how many files must be read. The byte budget includes decompressed data.
Oversized records are checked without retaining their contents: known compaction
and tool-output records do not create usage gaps, while missing tool or token
evidence stays marked incomplete. Later records are still read. Known metadata-only
files are not usage sessions. The limits are
configurable with `estimate_max_files`, `estimate_max_bytes`,
`estimate_line_max_bytes` and `estimate_max_record_tokens`; see [Settings](/reference/cli#settings).
`estimate_buffer_max_bytes` controls the bounded parsing buffer and must be at
least `estimate_line_max_bytes`. It does not change which records count as usage.
Cached accounting counts against the same file and decompressed-byte limits.
`estimate_scan_workers` bounds parallel file readers (twelve by default).
Each reader uses `estimate_read_buffer_bytes` for I/O and up to
`estimate_buffer_max_bytes` for a record. These settings change scan throughput,
not the history included or the resulting accounting.

## Use JSON with your agent

```sh
synkro estimate --path /work/payments --json
```

JSON includes `from`, `to`, `observed_days`, `period`, `projection_days`, `semantic_rules`, `policy_note`,
`totals` and a `harnesses` array. Each row includes usage, completeness notes,
model-cost details, `sample_quote`, `daily_average`, `estimated_synkro_usd`,
`agent_api_equivalent_usd` and `synkro_percent_of_agent_cost`.
The same projection and daily-average fields appear in `totals`, along with `harnesses_included`.
`sample_quote.total_microusd` uses millionths of a US dollar; projected cost fields
are already in dollars. `coverage` on each row and the totals distinguishes
`complete`, `partial` and `unavailable` metrics, and reports `priced_records`,
`observed_records`, `priced_tokens` and `observed_tokens`. Totals add available
amounts and retain partial coverage when a contributor is missing. An entirely
unavailable metric remains `null`; missing session directories are not zero usage.

Ask your agent to compare usage across agents or explain the estimate using
those assumptions. To see what Synkro has actually checked, use
[Activity and stats](/guides/stats). To add funds or claim starter credit after
skipping card setup, use [Billing and usage](/guides/billing).