The ferryman who minimizes the fare instead of demanding toll. An ultra-lightweight, resilient OpenRouter API price tracker, volatility detector, and token cost optimizer for Hermes Agent and automated LLM workflows.
Status: pre-1.0. Public interfaces may change between minor versions until the project has real-user and third-party feedback.
In Greek mythology, Charon is the grim ferryman who demands an obol coin toll to carry souls across the rivers Styx and Acheron. In modern agentic AI systems, every prompt expansion, reasoning chain, and tool history represents an accumulating token toll.
Anticharon is the counter-agent: the vigilant watcher that monitors OpenRouter model pricing, computes cache-aware, three-price (advertised / effective / policy) blended costs, detects unexpected price spikes or promotional drops, and ensures your agents always cross the token river for the lowest possible toll.
- Cache-Aware Blended Pricing: Calculates realistic cost per 1M tokens based on your agent's actual uncached-prompt / cached-prompt / completion token mix (calibrated default: 23.26% uncached / 76.45% cached / 0.29% output), never a cache-blind prompt-vs-completion split.
- Backed by 114 Billion Tokens of Empirical Science: Why do pricing calculators assume a 50/50 token mix? Autonomous agents (Hermes, Claude Code, Cursor, Codex) don't chat—they work. They consume massive contexts (system prompts, workspace trees, code snippets, git logs) and output concise tool calls and surgical diffs. We validated our default calibration against University of Washington's research paper "TraceLab: Characterizing Coding Agent Workloads for LLM Serving" (live demo, GitHub). Across 114.2 billion input tokens and 391.8 million output tokens (a 291.5 to 1 ratio), the academic dataset recorded 99.66% input / 0.34% output—differing from Anticharon's operational baseline by only 0.05% (-0.0005). We did the heavy lifting so you and your agents get real-world mathematical accuracy out of the box!
- Eliminates AI Cost Anxiety & Slop: When you know true blended costs, price hikes don't terrify you, and promotional windows don't deceive you. Developers and agents can deploy frontier models responsibly within a sensible personal budget.
- TUI ASCII Price Spectrum Chart: Instant visual ASCII bar chart in every run showing relative pricing distribution from
▲ Cheaperto▼ More Expensive, badging🏆 [BEST]and★ [DEFAULT]. - Catalog Search & Filter (
anticharon model discover): Filter OpenRouter's entire catalog (~417+ models) by keyword substring match, output modality (--modality text), promotional / free flags (--promo), and price threshold expressions (--filter "price < 10") — plain criteria matching, sorted cheapest-first. No AI ranking, curation, or recommendations. - Model Shortlist Management (
anticharon model add / remove / list): Manage your configuration right from the terminal with live catalog slug validation and--dry-runsafety. - One-Command Calibration (
anticharon calibrate): Directly ingest CSV log exports from OpenRouter to automatically calculate and save your exact three-component mix — uncached prompt, cached prompt, and completion — for better life quality. Remember: Y.M.M.V. (Your Mix May Vary). - Moving Average & Volatility Detection: Tracks 3-day and 7-day moving averages (
MA_3d,MA_7d) to trigger instantPRICE_SPIKE,PRICE_DROP, andBEST_OPTION_CHANGEDalerts. No Scientific Analysis here just simple moving averages and threshold based logic. - Real 30-Day Backfill: A granular per-model daily store (
effective_prices.json) backfills 30 days of history on first tracking a model from OpenRouter's listed endpoint prices blended with your calibration (standard service tiers only) — never fabricated flat padding — and is the only input to analytics.history.csvis a derived one-line-per-model export for convenience. - Resilient & Safe: 10-second API timeouts with graceful fallback to local cache when offline or rate-limited.
- Built-in Self-Test (
anticharon test): Instant pre-flight checks validating runtime environment, dependencies, math calculations, and network access. - Fast, Zero-Bloat Distribution: Managed with
uv, runnable as a standalone CLI or directly installed from Git.
Most pricing calculators deceive developers by advertising cheap input prices while hiding exorbitant completion rates—or scaring them away from frontier models by quoting $15/1M output prices as if agents output as much as they read.
Real-world coding agents exhibit extreme input dominance:
| Metric | UW TraceLab Dataset (114.6B Tokens) | Anticharon Calibrated Baseline | Difference |
|---|---|---|---|
Input (weight_prompt) |
0.9966 (99.66%) |
0.9971 (99.71%) |
-0.0005 (-0.05%) |
Output (weight_completion) |
0.0034 (0.34%) |
0.0029 (0.29%) |
+0.0005 (+0.05%) |
| Input-to-Output Ratio | 291.5 : 1 | 339.5 : 1 | Extreme Input Dominance |
Source: University of Washington SyFi Lab — TraceLab (Sep 2025 – Jul 2026).
The Takeaway: Anticharon arrives out of the box pre-tuned to empirical reality, while giving you anticharon calibrate whenever you want to calibrate against your personal logs in 1 second.
Install and run anticharon directly without manually cloning the repository:
# Using uv tool (recommended)
uv tool install git+https://github.com/parisneto/anticharon.git
# Or via uv pip in an active environment
uv pip install git+https://github.com/parisneto/anticharon.gitgit clone https://github.com/parisneto/anticharon.git
cd anticharon
# Initialize virtual environment and dependencies
uv sync# Standard run: auto-detects Hermes models, fetches OpenRouter, updates history, prints report & ASCII price chart
uv run anticharon run
# Check: local read of persisted prices and alerts; never fetches
uv run anticharon check
# Explicit Hermes config path or standalone mode without Hermes
uv run anticharon run --hermes-config /path/to/hermes/config.yaml
uv run anticharon run --no-hermes
# Output structured JSON (ideal for Hermes or script piping)
uv run anticharon run --jsonWhen deployed alongside Hermes Agent (e.g. in a remote VM or local agent environment), Anticharon automatically detects Hermes's active model (default:) and OpenRouter fallback models:
# Explicitly import Hermes models into Anticharon shortlist (read-only on Hermes)
uv run anticharon model import-hermes # or: uv run anticharon model sync
# Preview model import without modifying shortlist.json
uv run anticharon model import-hermes --dry-run
# Custom Hermes config path
uv run anticharon model import-hermes --hermes-config /custom/path/to/config.yaml# Filter models by family / name (substring match)
uv run anticharon model discover "gemini"
# Filter for promotional and free (:free, $0.00) models
uv run anticharon model discover --promo
# Multi-criteria filtering (provider, modality, price threshold expressions)
uv run anticharon model discover "qwen" --modality text --max-price 0.50
uv run anticharon model discover --promo --filter "openai" --filter "anthropic"
uv run anticharon model discover --filter "gemini" --filter "price < 0.20"# List current shortlist
uv run anticharon model list
# Add a model with live catalog validation (or preview with --dry-run)
uv run anticharon model add "google/gemini-3.7-flash"
uv run anticharon model add "google/gemini-3.7-flash" --dry-run
# Remove a model from shortlist
uv run anticharon model remove "minimax/minimax-m2.7"uv run anticharon test- Go to OpenRouter: Sidebar Logs (
https://openrouter.ai/logs) - Select your timeframe on the top right (e.g. Past 1 Month)
- Click the 3 dots menu → Export to download the CSV file.
- Run Anticharon:
# Ingest log and automatically update your shortlist.json config
uv run anticharon calibrate path/to/openrouter_activity.csv
# Or inspect the calculated ratio without modifying configuration
uv run anticharon calibrate path/to/openrouter_activity.csv --dry-runAnticharon looks for configuration in:
- Environment variable
ANTICHARON_CONFIG(if set) ~/.hermes/price_tracker/shortlist.json- Local
./config/shortlist.json(fallback)
{
"shortlist": [
{ "model": "deepseek/deepseek-v4-flash-0731", "source": "manual" },
{ "model": "deepseek/deepseek-v4-flash-0423", "source": "manual" },
{ "model": "qwen/qwen3.7-flash", "source": "manual" },
{ "model": "openai/gpt-5.6-luna", "source": "manual" },
{ "model": "google/gemini-3.1-flash-lite", "source": "manual" },
{ "model": "minimax/minimax-m2.7", "source": "manual" },
{ "model": "google/gemini-2.5-flash-lite", "source": "manual" }
],
"weight_uncached_prompt": 0.2326,
"weight_cached_prompt": 0.7645,
"weight_completion": 0.0029,
"spike_threshold_pct": 20.0,
"min_tracking_days_for_profile": 14
}Run Anticharon daily via cron to alert Hermes or generate reports:
# Run daily at 08:00 UTC and save JSON output
0 8 * * * anticharon run --json > ~/.hermes/price_tracker/latest_prices.jsonAnticharon natively exposes an MCP server over stdio for Hermes Agent, Claude Desktop, and any standard MCP client.
check_prices: Local read of persisted prices and alerts; never fetches.run_prices: The only fetch-and-persist operation; writes price history and alerts. It saves by default;dry_run=truepreviews a write.get_model_history: Local 30-day trajectories, CV%, and recommendations.discover_models: Live multi-criteria OpenRouter catalog search.add_model,remove_model,list_models,self_test: Manage the local shortlist or run diagnostics through MCP.calibrate_token_weights,calibrate_fast: Calibrate from a server-local CSV or host-derived weights. Writes save by default and retain a.bak.import_hermes_models: One-way, read-only-on-Hermes import into Anticharon's shortlist;dry_run=truepreviews the write.check_updates,run_update: User-initiated release check and experimental update operation.run_updatemay require a host restart.
The five MCP prompts are also available on the CLI: anticharon prompt lists them, and anticharon prompt <name> --arg KEY=VALUE renders one.
Tip
🔒 Hermes Ingestion: import_hermes_models is strictly one-way and read-only on Hermes Agent (~/.hermes/config.yaml). It never touches or mutates your Hermes configuration. The write applies only to Anticharon's shortlist; use dry_run=true to preview.
anticharon://llms.txt: Machine-readable Agent-to-Agent briefing.anticharon://history.csv: Derived one-line-per-model price export (convenience only).anticharon://effective_prices.json: Local dated price observations (read-only;{}when absent).anticharon://shortlist.json: Active configuration and calibrated weights.anticharon://calibration-details: Token weight definitions, derivation guidance, and local CSV fallback.
cost_spike_triage: Guided triage when a price hike or expired promotional window occurs.model_migration_advisor: Guided migration when an active model is flagged asSUNSETTING.family_upgrade_discover: Discovers newer generation sibling models in the same provider family.daily_cost_briefing: Generates a 3-bullet executive briefing of price movements and alerts.budget_optimization_audit: Audits your shortlist to identify cost outliers and optimize fallback ordering.
During live MCP Inspector validation across 30 days of price data:
google/gemini-3.7-flash: Price jumped from$0.379to$0.759(+100.0%). Anticharon flagged it as📈 PROMO_ENDEDand⚠️ SUNSETTING.- Automatic Sibling Alternative: Anticharon detected that
google/gemini-3.8-flashwas available at the exact same price ($0.75881/1M), delivering an actionable recommendation:"Introductory promo ended (+100.0%). Sibling google/gemini-3.8-flash active at same/lower price ($0.759). Migrate to google/gemini-3.8-flash."
- Outcome: Your agent receives pre-digested intelligence to switch to the newer model version instead of blindly running legacy models at doubled prices.
Install Anticharon first with one persistent mode:
uv tool install git+https://github.com/parisneto/anticharon.git
# or
pip install git+https://github.com/parisneto/anticharon.gitUse check_updates to inspect the installed version. Use experimental
run_update only with explicit user intent; a host restart can still be
required. For a source checkout, contributors may use uv run --directory $HOME/src/anticharon anticharon mcp.
mcp_servers:
anticharon:
command: "~/.local/bin/anticharon"
args: ["mcp"]{
"mcpServers": {
"anticharon": {
"command": "$HOME/.local/bin/anticharon",
"args": ["mcp"]
}
}
}{
"mcpServers": {
"anticharon": {
"command": "$HOME/.local/bin/anticharon",
"args": ["mcp"]
}
}
}Hermes expands ~ in its configuration. Expansion of $HOME in other host
configuration files remains pending the E-2 host-install verification; replace
it with the resolved path to your installed anticharon binary if needed.
Tool responses include an in-band _hints dictionary declaring key definitions:
data_source:"live_api"or"cached_history"api_offline_fallback: Explicit boolean declaring HTTP cache fallback. Note: This has no relation to Hermes modelfallback_providers.
You can visually test and debug all Anticharon MCP tools, resources, and prompts using the official Model Context Protocol Inspector:
# Launch with the helper script:
./scripts/inspect_mcp.sh
# Or directly via npx:
npx @modelcontextprotocol/inspector uv --directory . run anticharon mcpMIT License. Copyright (c) 2026 Páris Piedade Neto. Connect on LinkedIn.
Anticharon is built for the agentic developer community. Contributions, suggestions, and model discovery profiles are welcome!
- Found a bug or price discrepancy? Open an Issue.
- Want to add a feature or provider filter? Fork the repo, create a branch, and submit a Pull Request.
- Code Standards: Anticharon follows spec-driven development, deterministic
pytest-based testing, and plain Markdown math. Always runuv run pytestbefore submitting a PR.

