anticharon

# Anticharon MCP briefing (v0.7.0)

Anticharon monitors OpenRouter model prices and maintains a local shortlist.
This is a pre-1.0 release: public interfaces may change between minor versions
until there is real-user and third-party feedback. Read `messages` in every result
before acting. Before trusting a remembered default model, call `check_prices`
or re-read `anticharon://llms.txt`.

## Install and run

Supported persistent install modes are:

```bash
uv tool install git+https://github.com/parisneto/anticharon.git
# The installed command is normally ~/.local/bin/anticharon.

pip install git+https://github.com/parisneto/anticharon.git
```

For a contributor checkout, run `uv run --directory /path/to/anticharon
anticharon mcp`. After installation, use `check_updates` to inspect the
installed version and `run_update` only with explicit user intent. The latter
is experimental and may require a host restart.

## Operating model

- `run` / `run_prices` is the only fetch-and-persist operation. It writes
  `history.csv`, `effective_prices.json`, and `alerts.json`.
- `check` / `check_prices` and `history` / `get_model_history` are local reads
  that never fetch or recompute stored alerts.
- Analytics come only from the dated daily observations in
  `effective_prices.json` (OpenRouter's listed endpoint prices, standard tiers,
  blended with your calibration; the same definition as the live price);
  backfilled days count immediately. `NEWLY_TRACKED`
  means too few observed days (`observation_count` below
  `min_tracking_days_for_profile`), not a recent install. `change_vs_30d_pct:
  null` means no usable 30-day baseline. Each result carries
  `classification_reason`; each price row carries `price_source`
  (`observation`, `live_quote`, `cached_quote`) and `price_date`.
- A shortlisted slug with no stable catalog identity (a redirect alias such as
  `x/y-latest` listed as `~x/y-latest`, or an unmatched slug) appears in
  `not_tracked` with `status: "NOT_TRACKED"`, `identity`, `code`
  (`REDIRECT_IDENTITY` or `NO_EXACT_MATCH`), and a diagnostic. It has no price
  or history; the slug is never rewritten.
- A model's price is its cheapest standard-tier endpoint (service tiers such as
  `flex`, `fast`, `priority` are excluded); each price row reports the chosen
  endpoint's `endpoint_tag`.
- A write saves by default. Use `dry_run=true` (or CLI `--dry-run`) only to
  preview a write.
- `add_model` validates an exact live catalog slug. `remove_model` refuses
  source-managed entries. Hermes configuration is never modified.

## MCP tools

- `check_prices(model_id)`: Local latest-price and persisted-alert read.
- `run_prices(model_id, dry_run, force, zdr_only)`: Fetches prices and
  persists history and alerts; ZDR output is live-only.
- `get_model_history(model_id, format)`: Local 30-day history and analytics.
- `discover_models(query, promo_only, modality, max_price, limit)`: Searches
  the live OpenRouter catalog.
- `import_hermes_models(hermes_config_path, dry_run)`: Imports Hermes models
  one way into Anticharon; never writes Hermes configuration.
- `add_model(model_id, dry_run, default)`, `remove_model(model_id, dry_run)`,
  and `list_models()`: Manage the local shortlist.
- `calibrate_token_weights(csv_path, dry_run)` and
  `calibrate_fast(weight_uncached_prompt, weight_cached_prompt,
  weight_completion, dry_run)`: Calibrate local token weights; writes retain a
  `.bak` copy.
- `self_test()`: Runs the same diagnostics as `anticharon test`.
- `check_updates()`: User-initiated two-second check against GitHub Releases.
- `run_update(type)`: Experimental reinstall from the default branch, without a version comparison, so the result can be older than the installed version (the payload reports `running_version`); `type` defaults to `install_only`. WARNING: Executes shell commands directly on the host, so call it only with explicit user intent. The running server keeps the old version (and `check_updates` keeps reporting it) until reloaded: Hermes, ask the user to send `/reload-mcp` in chat; other MCP hosts, restart the host or reconnect the MCP server. `restart_host`, `phoenix` and `reload_request` are deprecated and planned for removal in 0.8.0.

## MCP resources

- `anticharon://llms.txt`: This operational briefing and glossary.
- `anticharon://history.csv`: Derived one-line-per-model price export (convenience only).
- `anticharon://effective_prices.json`: Local dated price observations (the
  analytics source); read-only, `{}` when absent, no network.
- `anticharon://shortlist.json`: Active shortlist and token weights.
- `anticharon://calibration-details`: Token-weight derivation and CSV fallback.

## MCP prompts

- `cost_spike_triage`: Investigate a price spike or ended promotion.
- `model_migration_advisor`: Plan a migration from a sunsetting model.
- `family_upgrade_discover`: Compare newer models in a family.
- `daily_cost_briefing`: Prepare a daily prices-and-alerts briefing.
- `budget_optimization_audit`: Review shortlist cost and resilience.

The same prompt registry is available through `anticharon prompt` on the CLI.

## Response envelope

Every MCP tool and CLI `--json` response starts with `status`, `messages`, and
`elapsed_ms`. `messages` is never empty and ends with `COMPLETED`. `error` and
`refused` map to MCP `isError: true` and CLI exit code 1. The documented action
codes are `API_FALLBACK`, `CALIBRATION_INPUT_INVALID`,
`CATALOG_UNAVAILABLE`, `COMPLETED`, `DATA_STALE`, `EXPERIMENTAL`,
`HERMES_DIVERGENT`, `HERMES_INCOMPLETE`, `HERMES_NOT_DETECTED`,
`NO_DEFAULT`, `NO_EXACT_MATCH`, `NOT_MONITORED`, `ONLY_NON_STANDARD_TIERS`, `PREVIEW_ONLY`,
`QUOTE_FROM_CATALOG`,
`PRICE_INVALID`, `PRICE_UNAVAILABLE`, `RESTART_REQUIRED`,
`SELF_TEST_FAILED`, `SHORTLIST_UNCHANGED`, `SHORTLIST_UPDATED`, `SOURCE_MANAGED`,
`UP_TO_DATE`, `UPDATE_AVAILABLE`, `UPDATE_CHECK_FAILED`, `UPDATE_FAILED`,
`UPDATE_INSTALLED`, and `ZDR_LIVE_LIMITED`.