{"id":51507053,"url":"https://github.com/svasenkov/greedy-token","last_synced_at":"2026-07-08T01:04:10.131Z","repository":{"id":369343520,"uuid":"1289438684","full_name":"svasenkov/greedy-token","owner":"svasenkov","description":"Route dev tasks through tool → python → ollama → RAG before escalating to Cursor","archived":false,"fork":false,"pushed_at":"2026-07-04T19:21:36.000Z","size":38,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-04T21:05:15.967Z","etag":null,"topics":["cli","cursor","llm","ollama","rag","token-optimization"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/svasenkov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-04T18:49:13.000Z","updated_at":"2026-07-04T19:21:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/svasenkov/greedy-token","commit_stats":null,"previous_names":["svasenkov/greedy-token"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/svasenkov/greedy-token","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svasenkov%2Fgreedy-token","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svasenkov%2Fgreedy-token/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svasenkov%2Fgreedy-token/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svasenkov%2Fgreedy-token/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/svasenkov","download_url":"https://codeload.github.com/svasenkov/greedy-token/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svasenkov%2Fgreedy-token/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35247771,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cursor","llm","ollama","rag","token-optimization"],"created_at":"2026-07-08T01:04:09.554Z","updated_at":"2026-07-08T01:04:10.122Z","avatar_url":"https://github.com/svasenkov.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# greedy-token\n\nRoute dev tasks through **tool → python → ollama → rag → cursor** before burning agent context.\n\n**Русская версия:** [README-RU.md](README-RU.md)\n\n```\nYour task  →  greedy-token  →  rg | scripts | Ollama | docs/rag | pipeline | Cursor\n```\n\n## What it does\n\n| Layer | When | LLM cost |\n|-------|------|----------|\n| **tool** (rg) | find / grep / search | ~0 |\n| **python** | scripts, meta-sync, gen-env | ~0 |\n| **ollama** | bulk classify, skill audit | local only |\n| **rag** | lookup in `docs/rag/` | small read |\n| **cursor** | wiring, refactor, architecture | full agent chat |\n\n**Tier order:** first match wins. Ollama is skipped when unavailable.\n\n## Scope \u0026 roadmap\n\nToday the happy path is **Cursor + Ollama + monorepo**. CLI and MCP are IDE-agnostic; paid APIs and alternate local runtimes are **not** wired yet.\n\n**Full matrix (✅ / ❌ / 🔜) + acceptance criteria + GitHub issues:** [docs/ROADMAP.md](docs/ROADMAP.md) · [docs/ROADMAP-RU.md](docs/ROADMAP-RU.md)\n\n| Area | ✅ today | 🔜 v0.5+ |\n|------|----------|----------|\n| Executors | `tool`, `python`, `ollama`, `rag` | `cloud_llm`, `openai_compat` local |\n| Agent host | Cursor MCP + token baseline | Claude Desktop, Continue |\n| Config | `OLLAMA_URL` / `OLLAMA_MODEL` | `local_llm.provider`, `cloud_llm.provider` |\n\n## Install\n\n**Python 3.12+** (CI and PyPI builds use 3.12).\n\n```bash\npip install greedy-token\n# with Cursor MCP server:\npip install \"greedy-token[mcp]\"\n# editable (monorepo):\ncd projects/greedy-token-home/dev \u0026\u0026 ./scripts/install.sh\n```\n\n```bash\nexport GREEDY_TOKEN_ROOT=/path/to/workspace   # auto-detect in zero-design-system\n```\n\n## Cursor integration (recommended)\n\nMonorepo ships ready-made wiring:\n\n| File | Role |\n|------|------|\n| `.cursor/mcp.json` | MCP server config |\n| `.cursor/mcp/greedy-token.sh` | launcher (venv + `rg` path fix) |\n| `.cursor/rules/token-economy.mdc` | agent uses MCP before built-in Grep |\n| `.cursor/hooks.json` | `sessionStart` — token economy hint |\n\n**Setup:** install → **Settings → MCP → greedy-token → Enable → Refresh** → new Agent chat.\n\nExpected: **5 MCP tools** (including `greedy_token_pipeline`).\n\n## MCP tools\n\n| Tool | Purpose |\n|------|---------|\n| `greedy_token_search` | Ripgrep: `query` + optional `path` |\n| `greedy_token_rag` | Search `docs/rag/` chunks |\n| `greedy_token_route` | Recommend tier + token footer |\n| `greedy_token_pipeline` | Multi-step chain (python → ollama → rag) |\n| `greedy_token_usage` | Aggregate savings from `~/.greedy-token/usage.jsonl` |\n\nEvery tool response ends with a **Token economy** block — show it to the user.\n\n### Pipeline (multi-step)\n\n```text\npipeline: meta-audit configurator-boolean\n```\n\nor:\n\n```text\npipeline: check-meta-sync then audit-skill configurator-boolean\n```\n\nNamed recipes (`pipeline --list`):\n\n| Recipe | Steps |\n|--------|-------|\n| `meta-audit` | python → ollama |\n| `meta-rag` | python → rag |\n| `search-rag` | rg → rag |\n\nFooter includes **per-step savings** table:\n\n```text\nPer-step savings (if each step were a separate naive Cursor chat):\n   #  step                   executor     ms   spent  baseline     saved  billing\n   1  check-meta-sync        python       83       0     9,487     9,487  local script\n   2  audit-skill            ollama     2698   2,507     9,499     6,992  local Ollama\n\nSaved by executor (sum of per-step savings):\n  python (script)              steps=1  spent ~0      saved ~9,487\n  ollama (local LLM)           steps=1  spent ~2,507  saved ~6,992\n```\n\n## CLI commands\n\n| Command | Purpose |\n|---------|---------|\n| `greedy-token route \"…\"` | Recommend tier + scoring |\n| `greedy-token estimate \"…\"` | Token-aware estimate + tier scan |\n| `greedy-token run \"…\" [--execute]` | Route + dry-run / read-only execute |\n| `greedy-token pipeline \"…\" [--execute]` | Multi-step pipeline |\n| `greedy-token pipeline --list` | Named pipeline recipes |\n| `greedy-token rag QUERY` | Search `docs/rag/` |\n| `greedy-token scripts --list` | Workspace script wrappers |\n| `greedy-token scripts --run ID [--execute]` | Run wrapper |\n| `greedy-token audit-context` | Rules/skills token audit |\n| `greedy-token tokens PATH…` | Count tokens in paths |\n| `greedy-token compress` | Short prompt (stdin; `--ollama`) |\n| `greedy-token report [--since 7d]` | Usage telemetry aggregate |\n| `greedy-token config [--init] [--export]` | Ollama URL/model settings |\n| `greedy-token-mcp` | Start MCP server (stdio) |\n\nGlobal: `--no-log` disables telemetry for one invocation.\n\n\u003e **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.\n\n## Testing\n\nRequires **Python 3.12+** (same as CI).\n\n```bash\ncd projects/greedy-token-home/dev \u0026\u0026 ./scripts/install.sh\nsource .venv/bin/activate\ncd ../greedy-token\npython -m pytest tests/ -v\n```\n\nOptional integration tests (real monorepo files) run when the checkout includes `stacks/java-spring/`; set `GREEDY_TOKEN_ROOT` to override the workspace root.\n\n## Examples\n\n```bash\n# Search (0 LLM tokens)\ngreedy-token run \"find baseUrl in configurator-option-presets.html\" --execute\n\n# RAG lookup\ngreedy-token rag \"baseUrl -D flag\"\n\n# Ollama tier\ngreedy-token route \"audit skill configurator-boolean\"\n\n# Pipeline dry-run\ngreedy-token pipeline \"pipeline: meta-audit configurator-boolean\"\n\n# Pipeline execute (python + ollama)\ngreedy-token pipeline \"check-meta-sync then audit-skill configurator-boolean\" --execute\n\n# Savings report\ngreedy-token report --since 7d\n```\n\n## Token economy footer\n\nSingle-tool responses include:\n\n- **This call** — executor, spent, billing (local vs cloud)\n- **Cursor baseline** — rules + task + overhead\n- **Saved vs naive Cursor chat**\n\nPipeline adds **per-step** baseline / spent / saved and **saved by executor**.\n\n\u003e **Note:** MCP executor steps are local/cheap. Agent chat wrapper (rules + your message + reply) still uses Cursor tokens.\n\n## Usage telemetry\n\nLog file: `~/.greedy-token/usage.jsonl` (disable: `GREEDY_TOKEN_LOG=0`).\n\nEach event: tier, `est_tokens`, `cursor_baseline`, `cursor_saved`, `duration_ms`.\n\nPipeline 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.\n\n## Environment\n\n| Var | Default |\n|-----|---------|\n| `GREEDY_TOKEN_ROOT` | auto-detect or required |\n| `OLLAMA_URL` | from config or `http://localhost:11434` |\n| `OLLAMA_MODEL` | from config or `qwen2.5-coder:7b-instruct-q4_K_M` |\n| `GREEDY_TOKEN_LOG` | `~/.greedy-token/usage.jsonl` |\n| `GREEDY_TOKEN_LOG_MAX_BYTES` | `5242880` (5 MiB) |\n| `GREEDY_TOKEN_LOG_MAX_FILES` | `5` rotated archives |\n\n## Ollama config\n\nPriority (low → high): defaults → `~/.greedy-token/config.yaml` → `$GREEDY_TOKEN_ROOT/.greedy-token.yaml` → `OLLAMA_*` env.\n\n```bash\ngreedy-token config init\ngreedy-token config init --model llama3.2 --url http://192.168.1.10:11434\ngreedy-token config\neval \"$(greedy-token config --export)\"\n```\n\n## Routing config\n\n| File | Purpose |\n|------|---------|\n| `src/greedy_token/config/routes.yaml` | Task routing patterns |\n| `src/greedy_token/config/pipelines.yaml` | Named pipeline recipes |\n\n## `--execute` safety\n\nAuto-execute (read-only or stdout-only): `rg`, `jq`, `check-meta-sync`, pipeline steps in allowlist.\n\nRsync / migrate / batch-inventory — dry-run only unless run manually.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsvasenkov%2Fgreedy-token","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsvasenkov%2Fgreedy-token","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsvasenkov%2Fgreedy-token/lists"}