{"id":51748655,"url":"https://github.com/hurttlocker/token-lean","last_synced_at":"2026-07-18T22:10:50.641Z","repository":{"id":370799852,"uuid":"1295987174","full_name":"hurttlocker/token-lean","owner":"hurttlocker","description":"The decisions-only orchestration discipline for AI agent fleets. One markdown skill, any model — Claude Code, Codex, Cursor, anything that reads markdown.","archived":false,"fork":false,"pushed_at":"2026-07-11T02:34:35.000Z","size":16,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-11T04:13:50.076Z","etag":null,"topics":["agent-skills","ai-agents","claude-code","codex","context-engineering","orchestration","prompt-caching"],"latest_commit_sha":null,"homepage":"https://o8.run","language":"Shell","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/hurttlocker.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-10T02:57:11.000Z","updated_at":"2026-07-11T02:34:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hurttlocker/token-lean","commit_stats":null,"previous_names":["hurttlocker/token-lean"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/hurttlocker/token-lean","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hurttlocker%2Ftoken-lean","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hurttlocker%2Ftoken-lean/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hurttlocker%2Ftoken-lean/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hurttlocker%2Ftoken-lean/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hurttlocker","download_url":"https://codeload.github.com/hurttlocker/token-lean/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hurttlocker%2Ftoken-lean/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35632664,"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-18T02:00:07.223Z","response_time":61,"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":["agent-skills","ai-agents","claude-code","codex","context-engineering","orchestration","prompt-caching"],"created_at":"2026-07-18T22:10:50.041Z","updated_at":"2026-07-18T22:10:50.629Z","avatar_url":"https://github.com/hurttlocker.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# token-lean\n\n**The decisions-only orchestration discipline for AI agent fleets.**\n\nNot a tool. Not a binary. Not another MCP server. One markdown file your agent reads — and your orchestrator stops burning its context window on work that cheaper contexts should be doing.\n\nWorks with any model and any harness: Claude Code, Codex CLI, Cursor, Gemini CLI, opencode, your own agent loop. If it can read markdown, it can run token-lean.\n\n## The problem\n\nIf you run agents seriously, your **orchestrator's context window is the most expensive surface in the session** — and the default behavior of every capable model is to fill it with bulk: reading 40 files \"to understand,\" absorbing full test logs, re-sending repo context every turn, polling workers mid-flight. The session gets slower, dumber, and more expensive at the same time, because judgment drowns in pages.\n\nThe fix isn't a smarter model. Frontier models make it *worse* — they do scout-work and worker-work inline *because they can*. The fix is a discipline.\n\n## The rule\n\n\u003e **Never generate bulk, never absorb bulk.** Cheaper contexts produce candidates; the orchestrator ratifies, edits, or adjudicates on compact artifacts.\n\nEverything else in the skill derives from that one rule: a delegation ladder (scout → worker → builder → panel), eight concrete practices, and the failure modes to kill on sight.\n\n## The ladder — roles, not model names\n\n| Tier | Role |\n|---|---|\n| **Scout** | Lookups, directory surveys, git history, log summaries — synthesis in, never file dumps |\n| **Worker** | Mechanical edits, well-specced implementation, tests, first-pass reviews |\n| **Builder** | Multi-file features, hard debugging, judgment mid-flight |\n| **Panel** | Independent proposers + an adjudicator, when one model's answer isn't trustworthy |\n\nModel names rotate monthly; the ladder shape doesn't. Anthropic's Haiku / Sonnet / Opus-and-Fable, OpenAI's GPT-5.6 luna / terra / sol, Google's Flash / Pro, and open-weight equivalents all slot into the same rows — and **effort dials count as rungs**: the same model at low effort and at xhigh are two different tiers. Fill the table once for your stack and follow it.\n\n## The eight practices\n\n1. **Scout before you read** — \u003e3 file reads to answer a question means you should have sent a scout.\n2. **1KB hand-backs** — a transcript instead of a report means you briefed it wrong.\n3. **One big brief beats twenty steers** — mid-flight steering re-meters your whole window every turn.\n4. **Stable prefix, append-only deltas** — prompt caching makes an unchanged prefix ~10x cheaper.\n5. **Pre-digest inbound bulk** — with a hard exception for security/auth/schema/payment diffs, which you read raw.\n6. **Effort discipline** — effort past sufficiency is spend, not quality.\n7. **Verify through agents, report facts** — and never let a builder grade its own work.\n8. **Legislate, don't repeat** — the third explanation belongs in a rules file, forever.\n\nFull text with the reasoning behind each: [`skills/token-lean/SKILL.md`](skills/token-lean/SKILL.md).\n\n## Install\n\n**Claude Code — as a skill (30 seconds):**\n\n```bash\nmkdir -p ~/.claude/skills/token-lean\ncurl -fsSL https://raw.githubusercontent.com/hurttlocker/token-lean/main/skills/token-lean/SKILL.md \\\n  -o ~/.claude/skills/token-lean/SKILL.md\n```\n\nThen invoke `/token-lean` at the start of any substantial session, or just say \"keep it lean.\"\n\n**Claude Code — as a plugin (recommended — the ladder comes installed):**\n\n```\n/plugin marketplace add hurttlocker/token-lean\n/plugin install token-lean@token-lean\n```\n\nThe plugin ships more than the skill text. You get the ladder as **real dispatchable agents** — `scout` (Haiku, read-only, 1KB-synthesis contract), `worker` (Sonnet, brief-in / report-out), `adjudicator` (panel judge) — plus a **tripwire hook** that nudges the orchestrator after 4 consecutive file reads (practice #1, mechanized instead of honor-system), and a [primitive-by-primitive mapping](skills/token-lean/references/claude-code.md) of every rung and practice to Claude Code's Agent/Workflow machinery. The skill-only install is the discipline; the plugin is the discipline with the equipment already racked.\n\n**Codex CLI — quick path:** paste the contents of `skills/token-lean/SKILL.md` (below the frontmatter) into your `AGENTS.md`.\n\n**Codex CLI — native equipment (recommended):**\n\n```bash\nmkdir -p ~/.agents/skills/token-lean ~/.codex\ncp -R skills/token-lean/. ~/.agents/skills/token-lean/\ncp codex/profiles/*.config.toml ~/.codex/\n```\n\nRestart Codex, load the discipline on demand with `$token-lean` or `/skills`, then dispatch the ladder with `codex exec -p scout \"...\"`, `-p worker`, or `-p builder`. Current Codex uses one `$CODEX_HOME/\u003cname\u003e.config.toml` file per profile; inline `[profiles.\u003cname\u003e]` blocks are legacy. See the [Codex CLI primitive mapping](skills/token-lean/references/codex-cli.md) for panels, effort rungs, compact hand-backs, and pre-digestion.\n\n**Cursor:** same content into `.cursorrules` or a project rule.\n\n**Anything else:** it's plain markdown. Put it wherever your agent reads standing instructions.\n\n## Why it works\n\nTwo economics, one behavior change. First: delegation moves token burn from your most expensive context to your cheapest — a scout burning 50k tokens to hand back a 1KB synthesis is strictly better than the orchestrator absorbing those 50k tokens itself, because the orchestrator's window is metered on *every subsequent turn*. Second: prompt caching prices an unchanged context prefix at roughly a tenth of a cold read — so a stable, append-only window isn't just tidier, it's compounding savings on every turn of a long session.\n\nThe side effect nobody expects: sessions get *smarter*, not just cheaper. An orchestrator that only holds decisions, briefs, and compact reports stays coherent hundreds of turns past the point where a bulk-absorbing session has drowned its own judgment.\n\n## Provenance\n\nThis discipline was written by a frontier model — Anthropic's Fable 5 — documenting the shape of its own practice so any orchestrator could run it, then generalized here for every model family: run it on Fable 5, GPT-5.6 sol, Opus, Gemini, Grok, or open-weights — the orchestrator changes, the discipline doesn't. It's the day-to-day operating discipline behind [**o8**](https://o8.run), the governance layer for autonomous engineering teams. token-lean is the efficiency half of running an agent fleet; o8 is the governance half — approvals, audit, and organizational memory across every AI runtime.\n\n## License\n\nMIT — see [LICENSE](LICENSE). Issues and PRs welcome; response not guaranteed (the maintainer's fleet reviews PRs through o8, which is the point).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhurttlocker%2Ftoken-lean","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhurttlocker%2Ftoken-lean","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhurttlocker%2Ftoken-lean/lists"}