greedy-token

Русский · Why (ELI5) · Full guide

A router next to Cursor / Claude / Continue: it asks “do you need a model at all?” before opening an expensive agent chat.

find / check / docs lookup  →  free tools & scripts
sort-of-AI bulk work        →  local LLM (Ollama, …)
wiring / design             →  expensive agent chat

No fine-tuning. No shipping your data for training. It “learns” by adding readable scripts/routes from telemetry — reviewable and revertible.

What this is / isn’t

Headline ★ $82 / ★ $820 below = illustrative CLI/pipeline mix vs naive agent, not measured MCP-chat savings.

Automated tests dashboard — live metrics + Allure 3 preview

Link	What
Dashboard	pytest + MCP contracts
Awesome	drill-down by epic
CI	run + gh-pages

Money + time: which path should I use?

Illustrative USD / month and wall-clock per call for a mid-intensity CLI / pipeline / crystallize mix vs sending every class of work to a cloud / frontier chat ($130 / eng · $1,300 / ×10). Green columns = that scenario’s delta; ★ TOTAL (★ $82 / ★ $820) is a headline for that mix, not a claim about MCP Agent chat bills.

In a Cursor MCP session the host model is already running — tool footers (time_saved_ms, spent/saved) compare tool work to a naive agent turn, not “MCP removed the LLM.” Prefer CLI/pipeline --execute/hooks when you want 0 frontier tokens for a step.

First matching tier wins. Per-call times are estimates (time_saved_ms in footer / report, v0.11+).

Start

pip install "greedy-token[mcp]"
mkdir -p .cursor/rules
cp examples/cursor/mcp.json .cursor/mcp.json
cp examples/cursor/rules/greedy-token.mdc .cursor/rules/greedy-token.mdc

Settings → MCP → greedy-token → Enable → Refresh → new Agent chat.

find baseUrl in configurator-option-presets.html

Expect free rg and a spent vs saved footer.

Full setup: Cursor · Claude · Continue

Monorepo scripts: greedy-token init --routes-from examples/routes/workspace-routes.yaml (workspace overlay; portable bundled defaults stay generic).

MCP tools

Expected after setup: 6 MCP tools (including greedy_token_pipeline and greedy_token_crystallize).

CLI commands

Global: --no-log disables telemetry for one invocation.

Pipeline execute: MCP greedy_token_pipeline and CLI greedy-token pipeline are dry-run by default. Pass execute=true (MCP) or --execute (CLI) to run allowlisted steps.

Auto-execute (read-only or stdout-only): tool-tier rg / jq, plus pipeline steps in PIPELINE_AUTO_RUN (src/greedy_token/pipeline.py) — check-meta-sync, configurator-boolean-audit, audit-skill, classify-file, search, read-hits, rag.

Route command trust boundary: workspace read_only: true is metadata, not authorization. greedy-token run --execute accepts only internally built rg/jq argv, registered read-only wrappers, or a workspace-relative .py/.sh path approved in the user-local, workspace-bound trust manifest:

greedy-token trust add scripts/my-read-only-check.py --note "reviewed: stdout only"
greedy-token trust verify

SHA-256 and file identity are rechecked immediately before each approved launch. Edits, symlink/path replacement, deleted/recreated files, absolute or outside-workspace paths, python -c, shell -c, and trust-like fields from URL/file presets fail closed. POSIX binds the verified descriptor through /dev/fd; Windows retains a narrow verify-to-open window, and concurrent same-inode writes are not snapshotted. The old trusted_script_paths config key is deprecated dry-run metadata and grants no privilege. Subprocesses receive a validated argv list with shell=False. See the trust manifest and TOCTOU contract.

Routing benchmark

bench/routing_corpus.yaml is a held-out/adversarial classification gate, separate from bench/route_examples.yaml. It reports exact-match accuracy, confusion matrix, per-target precision/recall, family/language accuracy, and a mandatory zero false-cheap rate.

Lexical retrieval benchmark

bench/retrieval_corpus.jsonl labels expected chunk IDs for RU/EN, each domain, and exact, identifier, morphology, and paraphrase cases. python bench/retrieval_benchmark.py --root /path/to/workspace reports Recall@1/3/5, MRR, locale/domain/case-type breakdowns, and cold-index versus warm-query latency.

Retrieval is local lexical BM25/FTS: SQLite FTS5 with the unicode61 tokenizer, Unicode NFKC + casefold normalization, and no embeddings or network calls. Only docs/rag/manifest.jsonl entries are eligible. The persistent index is content-hash invalidated and stored under the user cache directory ($GREEDY_TOKEN_CACHE_DIR, $XDG_CACHE_HOME, or ~/.cache), outside the workspace. SQLite builds without FTS5 use the compatibility overlap scorer; formatted hits name the engine and BM25 score.

bench/evidence_corpus.v1.yaml and its SHA-256 lock add the separate public end-to-end evidence layer: frozen synthetic RU/EN fixtures, task-specific file/line, exit-code, chunk-ID and escalation oracles, temporary workspaces, and comparisons for direct rg/script, greedy CLI, greedy MCP stdio, and an agent baseline. The deterministic agent is labelled contract_stub; a real host baseline is manual. The JSON scorecard reports routing and task success separately, executor/retrieval/escalation success, attempts, p50/p95, and authoritative billing only. Cursor cost remains unknown when billing data is unavailable; failed work never counts as saved. See benchmark contract.

Confidence calibration

An absent override is not evidence of correctness. The legacy telemetry is therefore named override/hold confidence and appears only as a behavioural signal.

Router confidence calibrates only from explicit route_outcome events whose outcome is success or failure. Calibration is independent by route, tier, and language; the most-specific segment with ≥ 20 events (CALIBRATION_MIN_EVENTS) wins, then tier → language → global. Sparse data uses the score formula and is visibly labelled formula (uncalibrated; explicit outcome n=…). Score buckets remain [0, 2), [2, 4), [4, 6), [6, 8), and [8, +).

Outcome confidence calibration (explicit success/failure; min n=20):
  segment           bucket           n  predicted  observed  status
  tier:python       [2, 4)          25        75%       80%  calibrated

Repeated work → crystallize into a script → next time 0 LLM. Details: guide · roadmap

License: MIT · v0.16.0