greedy-token

Route dev tasks through tool → python → ollama → rag → cursor before burning agent context.

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

Your task  →  greedy-token  →  rg | scripts | Ollama | docs/rag | pipeline | Cursor

What it does

Tier order: first match wins. Ollama is skipped when unavailable.

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   # auto-detect in zero-design-system

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).

The zero-design-system monorepo additionally uses a venv launcher + sessionStart hooks — that path is documented in the monorepo, not required for PyPI users.

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).

cd projects/greedy-token-home/dev && ./scripts/install.sh
source .venv/bin/activate
cd ../greedy-token
python -m pytest tests/ -v

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

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