greedy-token

Русская версия: README-RU.md

You work in Cursor — greedy-token sits next to the agent (CLI + MCP) so everyday tasks don’t always open a full agent chat.

It routes each task to the cheapest matching tier (tool → python → ollama → rag → cursor; first pattern match wins). Pipeline chains multiple tiers in one call. Escalation to Cursor agent chat only when no cheaper route matches. Each response includes a Token economy footer vs a naive full-context chat.

In Cursor:  your task  →  greedy-token (MCP/CLI)
                 ↓
     route (one tier per task):
       tool → python → ollama → rag → cursor
       first matching route in routes.yaml wins; ollama tier skipped if server down
                 ↓
     pipeline (optional, multi-step):
       e.g. check-meta-sync then audit-skill …
       composes tool / python / ollama / rag steps — not a separate tier
                 ↓
     escalation: Cursor agent chat when no cheaper route matches

What it does

Tier order: TIER_ORDER in router.py / routes.yaml — first pattern match wins within the walk tool → python → ollama → rag → cursor. Not every tier runs on every task. Ollama tier is skipped when the server is down.

Scope & roadmap

Today the happy path is Cursor + Ollama + monorepo. CLI and MCP are IDE-agnostic; paid APIs and alternate local runtimes are not wired yet.

Full matrix (✅ / ❌ / 🔜) + acceptance criteria + GitHub issues: docs/ROADMAP.md · docs/ROADMAP-RU.md

Install

Python 3.12+ (CI and PyPI builds use 3.12).

pip install greedy-token
# with Cursor MCP server:
pip install "greedy-token[mcp]"
# editable (monorepo):
cd projects/greedy-token-home/dev && ./scripts/install.sh

export GREEDY_TOKEN_ROOT=/path/to/workspace   # optional; auto-detect when markers exist

Cursor integration (recommended)

Full guide (any workspace / PyPI): docs/cursor-setup.md · docs/cursor-setup-RU.md

Starter kit in this repo (copy into your project):

pip install "greedy-token[mcp]"
mkdir -p .cursor/rules
# from a greedy-token clone, or paste from the docs:
cp examples/cursor/mcp.json .cursor/mcp.json
cp examples/cursor/rules/token-economy.mdc .cursor/rules/token-economy.mdc

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

Expected: 5 MCP tools (including greedy_token_pipeline).

MCP tools

Every tool response ends with a Token economy block — show it to the user.

Pipeline (multi-step)

pipeline: meta-audit configurator-boolean

or:

pipeline: check-meta-sync then audit-skill configurator-boolean

Named recipes (pipeline --list):

Footer includes per-step savings table:

Per-step savings (if each step were a separate naive Cursor chat):
   #  step                   executor     ms   spent  baseline     saved  billing
   1  check-meta-sync        python       83       0     9,487     9,487  local script
   2  audit-skill            ollama     2698   2,507     9,499     6,992  local Ollama

Saved by executor (sum of per-step savings):
  python (script)              steps=1  spent ~0      saved ~9,487
  ollama (local LLM)           steps=1  spent ~2,507  saved ~6,992

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.

Testing

Requires Python 3.12+ (same as CI). GitHub Actions runs pytest + Allure 3 (quality gate, GitHub Pages report; optional TestOps upload when repo vars are set). Line and branch coverage on src/greedy_token/ must stay at 100% (branch = true, fail_under = 100).

CI ethalon: .github/_ethalon/ (action pins in gha-actions.yaml) → runnable .github/workflows/. Same pattern as monorepo tests-java/.github/_ethalon/. Sync: ./scripts/sync-github-workflows.sh; CI runs ./scripts/check-github-workflows-sync.sh before pytest.

cd projects/greedy-token-home/dev && ./scripts/install.sh
source .venv/bin/activate
cd ../greedy-token
python -m coverage run -m pytest tests/ -v --alluredir=build/allure-results
python -m coverage report --include='src/greedy_token/*'
npx --yes allure@3.13.0 quality-gate build/allure-results --config allurerc.mjs
npx --yes allure@3.13.0 generate build/allure-results --config allurerc.mjs -o build/allure-report

Coverage: branch = true and fail_under = 100 on src/greedy_token/ (see [tool.coverage.run] / [tool.coverage.report] in pyproject.toml). CI runs coverage run + coverage report on every push/PR.

Pyramid slices: layer per module in tests/pyramid_layers.py → Allure label layer + pytest marker (-m unit|component|integration|e2e). CI matrix job pyramid runs each slice separately.

Optional integration tests (real monorepo files) run when the checkout includes stacks/java-spring/; set GREEDY_TOKEN_ROOT to override the workspace root.

TestOps: project 5276 on allure.autotests.cloud. CI uploads when repo secret ALLURE_TOKEN is set (ALLURE_PROJECT_ID defaults to 5276, override via repo variable). Pyramid layers (unit / component / integration) are set via Allure label layer in tests/pyramid_layers.py — same keys as Java @Layer and TestOps mappings. Human-readable names use @allure.title / @allure.feature / @allure.story / @allure.epic on each test, and @allure.parent_suite / @allure.suite on each module (pytestmark) for TestOps folder names — JUnit @DisplayName / @Feature equivalent.

Examples

# Search (0 LLM tokens)
greedy-token run "find baseUrl in configurator-option-presets.html" --execute

# RAG lookup
greedy-token rag "baseUrl -D flag"

# Ollama tier
greedy-token route "audit skill configurator-boolean"

# Pipeline dry-run
greedy-token pipeline "pipeline: meta-audit configurator-boolean"

# Pipeline execute (python + ollama)
greedy-token pipeline "check-meta-sync then audit-skill configurator-boolean" --execute

# Savings report
greedy-token report --since 7d

Token economy footer

Single-tool responses include:

• This call — executor, spent, billing (local vs cloud)
• Cursor baseline — rules + task + overhead
• Saved vs naive Cursor chat

Pipeline adds per-step baseline / spent / saved and saved by executor.

Note: MCP executor steps are local/cheap. Agent chat wrapper (rules + your message + reply) still uses Cursor tokens.

Usage telemetry

Log file: ~/.greedy-token/usage.jsonl (disable: GREEDY_TOKEN_LOG=0).

Each event: tier, est_tokens, cursor_baseline, cursor_saved, duration_ms.

Pipeline logs one event per step. When the log exceeds GREEDY_TOKEN_LOG_MAX_BYTES (default 5 MiB), it rotates to usage.jsonl.1, .2, …; report reads the active log and archives.

Environment

Ollama config

Priority (low → high): defaults → ~/.greedy-token/config.yaml → $GREEDY_TOKEN_ROOT/.greedy-token.yaml → OLLAMA_* env.

greedy-token config init
greedy-token config init --model llama3.2 --url http://192.168.1.10:11434
greedy-token config
eval "$(greedy-token config --export)"

Routing config

--execute safety

Auto-execute (read-only or stdout-only): rg, jq, check-meta-sync, pipeline steps in allowlist.

Rsync / migrate / batch-inventory — dry-run only unless run manually.

License

MIT