{
  "markdown": "# 🍯 Honey (I Shrunk the AI)\n\n<p align=\"center\">\n  <img src=\"https://media3.giphy.com/media/v1.Y2lkPTc5MGI3NjExbHRsNndobm8wM3F1c3pqNnhxODF6NDY2a2t3YjN5OHFoYmtvZXg0dCZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/JUh0yTz4h931K/giphy.gif\" alt=\"Honey, I shrunk the AI\" width=\"480\">\n</p>\n\n**Write less code and say less about it.** Honey (I Shrunk the AI) by\n[GreenPT](https://github.com/Green-PT) is a\ncross-tool coding skill that cuts AI coding-agent token usage and LLM API costs —\nmaking agents emit less code *and* less prose without losing correctness. It works\nwith **Claude (claude.ai and the API), Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, Windsurf, Cline,\nOpenClaw, oh-my-pi, Kiro, Kilo Code, and Hermes Agent**. Three independent levers, applied reflexively:\n\n1. **Less code** — YAGNI first. Walk a ladder (does it need to exist? → stdlib →\n   language native → existing dependency → one line → minimum block) and stop at\n   the first rung that works. The cheapest line is the one you never write.\n2. **Less prose** — drop the wind-up, the hedging, the narration of code that\n   already speaks for itself. Answer first.\n3. **Denser agent-to-agent handoffs** — when the reader is another agent, not a\n   human, hand it the most token-efficient format it parses losslessly (compact /\n   columnar JSON, or [ESON](eso/SPEC.md)). Cuts handoff size ~in half at zero loss\n   of recovery. Fires only here — never as a user-facing answer.\n\nHoney combines what [Ponytail](https://github.com/DietrichGebert/ponytail)\n(minimal code) and [Caveman](https://github.com/JuliusBrussee/caveman) (terse\nprose) do separately, then goes further:\n\n- **Auto-intensity** — `lite` / `full` / `ultra` chosen reflexively from the\n  request, with no deliberation tax (it never spends reasoning tokens deciding\n  *how* to comply — that would defeat the purpose on reasoning models).\n- **Safety carve-outs** — input validation, error handling, auth, secrets,\n  migrations, deletes, and anything you explicitly asked for are **never**\n  compressed. Lazy ≠ broken.\n- **A skill family, not one prompt** — an always-on core plus on-demand satellites\n  (review, eco, gain, compress) and a *hive* of read-only subagents that return\n  compressed handoffs. See [Skills & subagents](#skills--subagents).\n\n## Why\n\nVolume is cost. In agentic coding sessions, the volume of generated code and\nprose is what runs up the bill — and most of it is waste.\n\nThis repo ships a **reproducible benchmark** ([`bench/`](bench/)) so you don't have\nto take the numbers on faith: 23 tasks across three kinds of work — baseline vs\n[Caveman](https://github.com/JuliusBrussee/caveman) vs\n[Ponytail](https://github.com/DietrichGebert/ponytail) vs Honey — same model, same\nprompts, only the skill changes. Correctness is objective (unit tests, structural /\naccessibility checks, and lossless round-trip recovery for agent handoffs); quality\nis scored by a **4-model cross-family judge panel** (median of Opus 4.8 + Sonnet 4.6\n+ Haiku 4.5 + GPT-5.5) under a **neutral rubric** that says nothing about length, so a\nterse skill gets no thumb on the scale. The figures below are the committed results\n(Claude Opus 4.8, 3 runs each) — run `cd bench && npm run bench` to reproduce.\n\nEvery number is a **paired per-task delta** vs baseline — runs collapse by median,\ntasks pair up, and the figure is the median of those paired deltas with a two-sided\nWilcoxon `p`. Not a ratio of arm totals: that is dominated by whichever task happens\nto be longest, and it is how token-saving tools end up publishing numbers nobody can\nreproduce. Endpoints and the run ladder are pre-registered in\n[`bench/METHODOLOGY.md`](bench/METHODOLOGY.md).\n\nOn **Claude Opus 5** (23 tasks × 3 runs, 207 cells, zero refusals or truncation —\n[`full-opus5-lean`](bench/results/full-opus5-lean/)):\n\n| | Δ LOC | Δ output | Δ cost | Tests |\n|---|------:|---------:|-------:|------:|\n| **Honey** | **−71%** (p<0.001) | **−38%** (p<0.001) | **−24%** (p<0.001) | **100%** |\n\nHoney is the only arm with no failing cell — the no-skill baseline fails four. And the\ncut is **larger on the newer model, not smaller**: −71% LOC on Opus 5 against −39% on\nOpus 4.8. That runs against the 2026 prompting guidance that newer models need less\ninstruction, which we tested directly and rejected — see\n[`METHODOLOGY.md`](bench/METHODOLOGY.md#lean-prompt-ablation).\n\nA single blended number hides the story, because the levers fire differently per\ntask type. Honey on Opus 4.8, where the full competitor set was run — **Δ LOC**\nmeasures Lever 1 directly, **Δ output** measures the tokens (code *and* the prose\naround it):\n\n| Task tier | tasks | Δ LOC | Δ output |\n|-----------|------:|------:|---------:|\n| **Code** | 14 | **−53%** (p=0.002) | **−39%** (p=0.007) |\n| **User-facing** | 7 | −23% (p=0.022) | −7% (p=0.673 — a tie) |\n| **Agent-to-agent** | 2 | — (no code) | −49% (n=2, no p) |\n| whole suite | 23 | **−43%** (p<0.001) | **−29%** (p=0.020) |\n\nAgainst the competitors on the whole suite (judge win/loss/tie by exact sign test):\n\n| Variant | Δ LOC | Δ output | Judge W/L/T | Tests |\n|---------|------:|---------:|------------:|------:|\n| Caveman | −28% (p<0.001) | −22% (p<0.001) | 3/16/2, **p=0.004** | 94% |\n| Ponytail | −33% (p=0.028) | −7% (ns, p=0.267) | 1/19/1, **p<0.001** | 90% |\n| **Honey** | **−43%** (p<0.001) | **−29%** (p=0.020) | 8/11/2, p=0.648 | **100%** |\n\n- **Code** — the deepest cut (−39%) at 100% unit-test pass. Ponytail's mandatory\n  self-check *inflates* trivial code (+60% on Opus, +92% on GPT-5.5).\n- **User-facing** — the carve-out keeps Honey from compressing polish: the output\n  delta here is a **statistical tie**, and Honey holds the only 100% accessibility\n  pass while Ponytail drops to 81% on the structural/a11y checklist.\n- **Agent-to-agent** — under adversarial relay queries (ordinal, nested, absence,\n  cross-field count) Honey is the **only variant that stays 100% lossless** while\n  roughly halving handoff size; Caveman and Ponytail compress harder *and* lose\n  recovery (67% / 50%). Its biggest, cleanest win — on 2 tasks, so no p-value.\n- **Quality is a tie overall** (p=0.648) — fewer tokens at no measurable quality\n  cost, not higher quality. But the whole-suite tie is two opposing effects\n  cancelling: on Opus, Honey **wins user-facing 6/0/1 (p=0.031)** and **loses the\n  code judge 2/11/1 (p=0.022)** — on tasks where every variant passes 100% of the\n  unit tests, so that is a stylistic penalty for terseness, not a correctness one.\n  Neither effect replicates on GPT-5.5 (p=0.375 / p=1.000), so treat the code-judge\n  dip as suggestive, not established. Caveman's judge *mean* also ties baseline\n  exactly — but paired, it loses 16 of 23 tasks (p=0.004). Means hide that; sign\n  tests don't.\n- **The dollar saving is unproven at this sample size.** −21% on Opus is p=0.104 —\n  not significant on 23 tasks. Output volume is down; the bill is not yet a claim.\n\nThe output cut holds on GPT-5.5 (−20%, p=0.004; full two-provider table in\n[`bench/README.md`](bench/README.md#results)), but there **cost comes out +14% (ns)**\nbecause no prompt caching engaged in that arm, so every task paid the skill prompt\nfresh. Honey is the only variant with no test regressions across all three tiers on\nOpus.\n\n### End-to-end agentic measurement (Cline harness)\n\n`npm run bench` makes **one API call** per task — clean for isolating the output lever, but it\nnever exercises an agent loop, tool schemas, or multi-turn context growth, where a real agent's\ntoken bill actually lives. [`bench/src/cline-bench.js`](bench/src/cline-bench.js)\n(`npm run bench:cline`) runs each task *through* the [Cline](https://cline.bot) CLI headless, so\nthe measured tokens are end-to-end agentic — harness prompt and every loop iteration included.\nHoney is injected as a Cline **rule**, recommended as the per-turn-cheap\n[`skills/honey/cline-rule.md`](skills/honey/cline-rule.md) (the operational core; the full\n`SKILL.md` re-sent every turn inflates input). See [`bench/README.md`](bench/README.md#harness-benchmark-cline).\n\n## ESON — Efficient Structured Object Notation\n\nHoney includes [ESON](eso/SPEC.md), a zero-dependency, schema-first format for\nagent handoffs. Repeated record keys are emitted once; declared row counts catch\ntruncated messages; JSON-compatible cells preserve types. ESON is developed in\nits own repo — **[Green-PT/honey-eson](https://github.com/Green-PT/honey-eson)**:\nthe normative spec, JS + Python reference implementations, conformance vectors,\nthe canonical LLM primer, the Honey Wire Profile, and negotiation. Honey vendors\nthe codec in [`eso/`](eso/).\n\nThe reproducible [ESON/TOON/JSON benchmark](bench/eso/RESULTS.md) measures bytes,\ntwo tokenizer estimates, codec speed, and lossless recovery across five agent\nhandoff shapes. Run it with `npm run bench:eso`.\n\n```bash\nprintf '%s' '{\"from\":\"reviewer\",\"findings\":[{\"sev\":\"H\",\"issue\":\"expired token\"}]}' | eson encode\neson decode < handoff.eson\n```\n\n### CCR — for huge, redundant array tool output\n\nESON is lossless, for handoffs where every row matters. **CCR** (Compress-Cache-Retrieve)\nis the lossy-but-recoverable lever for the opposite case: a long uniform array you must\nread but mostly skim — logs, scan results, event streams. It keeps an informative sample\n(endpoints, anomalies/change-points, head/tail), caches the dropped rows locally, and\nleaves a `<<ccr:HASH N_rows_offloaded>>` sentinel. Nothing is lost — `retrieve` restores\nthe original by hash on demand.\n\n```bash\nsome-tool | eson crush          # → sampled view + sentinel; originals cached in .honey-ccr/\neson retrieve <hash>            # → the full original array, verbatim\n```\n\nValidated on a 90-row log (opus-4.8 + gpt-5.5): **−82% tokens**, crushed-only **96%**\nanswer accuracy, **100%** with retrieve — and the lone crushed miss was a refusal, not a\nhallucination. Benches: `npm run bench:ccr` (tokens) and `npm run bench:ccr:comprehension`\n(quality). The `honey-ccr` skill tells the agent when to reach for it.\n\n> **Known limitation (upstream):** Claude Code builds affected by\n> [anthropics/claude-code#68951](https://github.com/anthropics/claude-code/issues/68951)\n> (a regression present since ~2.1.121, still open) ignore a PostToolUse hook's\n> `updatedToolOutput` for the built-in Bash tool. On those versions the entry-time\n> hook runs and stashes the original, but the model still receives the raw\n> uncompressed output — honey warns once at session start when it detects an\n> affected version. Piping explicitly (`some-tool | eson crush`) is unaffected:\n> compression happens before the output leaves the tool. Separately, the hooks\n> need **Node >= 14** on the PATH Claude Code spawns them with — desktop-app\n> sessions inherit the launchd PATH, not your shell profile, so a stale\n> `/usr/local/bin/node` is common; the hook now warns instead of failing silently.\n\n### PX — image-rendered reads for huge dense read-only bulk\n\n**The intuition:** sending a file as text pays per character; sending an image\npays per pixel, no matter how much text is crammed into it. So a \"photo of the\npage\" costs ~5× less than the page itself — and reading it has photo problems:\nthe gist survives, an exact serial number might not.\n\nConcretely: dense text packs ~3 chars per image-token vs ~1 as text. **PX**\nexploits the gap on the *read* path: when the agent must skim something huge it\nwill never edit (vendored code, a large diff, docs), it renders it to PNG pages\nwith [pxpipe](https://github.com/teamchong/pxpipe)'s `export` and `Read`s the\nimages instead of the text.\n\n```bash\nnpx pxpipe-proxy export --json --out \"$TMPDIR\" src/   # → page-*.png + factsheet.txt + token report\n```\n\n**Measured: up to −85% tokens on a single read.** Repo-corpus bench\n(`npm run bench:px`, [results](bench/px/RESULTS.md)): **−79…85%**, −82% average\n(26.4k Claude text tokens → 4.8k image est.); ~−75% all-in per read after the\nfactsheet + report overhead; pxpipe's own end-to-end proxy bill measures −59…70%\nat whole-workload level.\n\n**Comprehension is a Fable story.** The live 4-model panel\n(`node bench/px/comprehension.mjs` — 10 byte-exact questions, text vs render):\n\n| model | text | from render |\n|---|---:|---:|\n| Claude **Fable 5** | 10/10 | **7/10** |\n| Claude Opus 4.8 | 10/10 | 4/10 |\n| Claude Sonnet 4.6 | 10/10 | 4/10 |\n| Claude Haiku 4.5 | 10/10 | 1/10 |\n\nOnly Fable-class models read renders usably — and even Fable is not byte-safe.\n**Lossy on exact strings** — misreads are silent confabulations (Haiku answered a\nseed question with `0x9e3779b9`, a constant that isn't in the file), so the export\nships verbatim precision tokens (paths, SHAs, numbers) as `factsheet.txt` text, and\nthe `honey-px` skill forbids it for files you'll edit, secrets, or non-Fable\nreaders. Over the raw API, prepend the export's `prompt.txt` banner — Fable's\nsafety layer refuses naked dense renders. Complementary to CCR: CCR drops\nredundant rows recoverably; PX keeps everything in view at pixel prices. At\n`/honey ultra` the core skill reaches for PX automatically on qualifying reads\n(big, dense, read-only); at other intensities it stays on-demand via `honey-px`.\nFor the\nfull wire-level version (system prompt, tool docs, history), run the pxpipe proxy\nitself — Honey and pxpipe stack.\n\nPick Honey when you want the best quality-per-token, especially in Claude Code.\n\n## Input precompression — a measured negative result\n\nThe three levers above cut **output**. There's symmetric waste on the **input** side —\nfiller, pleasantries, and repeated sentences in the prompt itself.\n[`hooks/precompress.js`](hooks/precompress.js) is a deterministic, **no-model** compressor\nthat strips them before the prompt reaches the LLM, protecting code, paths, URLs,\ndouble-quoted strings, and numbers **verbatim** (it never touches a token you'd need exact).\n\n```bash\nprintf '%s' 'Hi! Could you please write a function `add(a, b)` that returns their sum? Thanks so much in advance!' | node hooks/precompress-cli.js\n# -> write a function `add(a, b)` that returns their sum? in advance!\n```\n\nIt's safe and lossless (35/35 property checks; on 10 unit-tested tasks the model's output\npasses **100%→100%** from full vs compressed prompts), and on *chatty* prompts it cuts a lot —\n**−16.5% median** on a hand-written verbose corpus.\n\n**But that corpus flatters it.** Measured on **266 real human-typed prompts** from 35 actual\nsessions ([`bench/input/RESULTS.md`](bench/input/RESULTS.md)), the cut is **2.5% total, median\n0%** — 219 of 266 prompts compress to nothing, because real prompts are already terse and carry\nalmost no filler. Deterministic no-model compression can't catch *reworded* restatement (that\nneeds a model), so this is the real ceiling, not a tuning problem.\n\nThe honest conclusion: **the prompt is the wrong target.** Real input volume in agentic coding\nis tool output (CCR's domain) and re-pasted context across turns — not human pleasantries. This\nships as a CLI filter for the chatty-prompt case; it is **not** wired always-on, because on real\ntraffic it would save ~nothing. Kept here as a measured negative result, in the repo's spirit of\nnot overstating. Reproduce: `node bench/input/tokens.mjs`.\n\n## Skills & subagents\n\nHoney is one always-on core plus a family of on-demand tools. The core is a\n*writing style* (it must be the default to pay off); the rest are *actions* you\nreach for at a specific moment.\n\n| Name | Kind | What it does |\n|------|------|--------------|\n| `honey` | core skill (always-on) | the three levers, applied reflexively to every response — plus loop cost discipline for recurring `/loop` runs. `/honey [lite\\|full\\|ultra\\|off]` |\n| `honey-chat` | standalone prompt | Honey for plain chat — the terse-prose core, no tools required. Paste [`skills/honey-chat/SKILL.md`](skills/honey-chat/SKILL.md) into a claude.ai Project's custom instructions, a Style, or an API system prompt (~500 tokens); [`COMPACT.md`](skills/honey-chat/COMPACT.md) (≤1,500 chars) fits ChatGPT/Gemini custom-instruction fields |\n| `honey-design` | satellite skill | for user-facing UI (landing pages, components): keeps the full rendered polish, cuts tokens by writing the design densely (CSS vars, shared classes, `clamp()`) — same pixels, fewer tokens |\n| `honey-review` | satellite skill | review a diff for over-engineering + over-verbosity; terse delete-list |\n| `honey-eco` | satellite skill | this session's CO₂ / $ / tokens saved, from the committed EcoLogits port |\n| `honey-gain` | satellite skill | the committed benchmark scoreboard (reads `bench/results/` at runtime) |\n| `honey-debt` | satellite skill | harvest every `honey:` shortcut marker into a debt ledger, flagging the ones with no revisit trigger — so a deliberate simplification can't quietly go permanent |\n| `honey-compress` | satellite skill | rewrite a re-read memory file (CLAUDE.md, AGENTS.md) tersely to cut *input* tokens; backs up the original |\n| `honey-memory` | satellite skill | create + maintain one committed per-project `PROJECT.md` so agents stop re-discovering the same facts every cold session; stores only stable, not-in-the-code context, kept honest by living in git |\n| `honey-ccr` | satellite skill | crush huge redundant array tool output (logs, scan results) to a sampled view; lossy-but-recoverable via `eson crush`/`retrieve` |\n| `honey-px` | satellite skill | read huge dense *read-only* bulk as rendered PNG pages (`npx pxpipe-proxy export`) — image tokens scale with pixels, not chars: **up to −85%** on token-dense content (Fable-class readers only); lossy on exact strings, never for files you'll edit |\n| `honey-loop` | satellite skill | cost discipline for recurring `/loop` runs: cache-aware pacing (skip the 300s dead zone), event-driven-over-polling, no-change short-circuit, compact state handle, stop condition |\n| `honey-superpowers` | satellite skill | stack Honey onto Superpowers-style subagent workflows: the Honey directive to inject into each dispatch prompt (worker + reviewer variants). On Claude Code the plugin's `SubagentStart` hook injects it automatically |\n| `honey-hive` | guide skill | decide when to delegate to the hive vs. work inline |\n| `hive-scout` | subagent (haiku, read-only) | locate symbols / callers / configs; returns a compact id-keyed JSON map |\n| `hive-reviewer` | subagent (haiku, read-only) | review a diff/files; returns columnar id-keyed JSON findings |\n| `hive-builder` | subagent (sonnet, ≤2 files) | make a surgical edit under the ladder; returns a compact change-manifest |\n\nThe **hive** is Lever 3 with a runtime: each subagent returns a compressed handoff,\nso the result injected back into the orchestrator's context is **−44–53%** smaller\nwith zero loss (`npm run bench:hive`). Live, the skills hold up too — honey −86%,\nhoney-review −70%, hive-reviewer −43% output tokens at passing correctness\n(`npm run bench:skills`). See [`bench/hive/RESULTS.md`](bench/hive/RESULTS.md) and\n[`bench/skills/RESULTS.md`](bench/skills/RESULTS.md).\n\nOn **user-facing** work — where the core skill *spends* tokens because polish is the\nspec — `honey-design` keeps the same rendered polish for **−19% output tokens** vs no\nskill (judge 92 vs 90), beating the core skill on both axes across 7 landing-page/UI\ntasks. See [`bench/results/honey-design.md`](bench/results/honey-design.md).\n\n> **Honesty note.** Earlier versions of this README quoted `92% / 78% / 73%` quality\n> and `−57% / −65% / −70%` tokens from an unpublished run. Those don't reproduce —\n> the real quality spread is far narrower and the token savings are tier-dependent\n> (and Ponytail *adds* tokens on simple code).\n>\n> A second correction, 2026-07-29: the figures before that were **ratios of arm\n> totals** (`sum(honey)/sum(baseline)`), which one long task can dominate. Everything\n> above is now a paired per-task median with a p-value. That moved honey's headline\n> from −15% to **−29%** — the old method was understating it — but it also retired\n> two numbers that turned out to be outlier artifacts: Ponytail's \"−22% output\" is\n> really −7% (ns), and Caveman's \"tied quality\" is a 16-of-23-task loss (p=0.004).\n> Method and pre-registered endpoints: [`bench/METHODOLOGY.md`](bench/METHODOLOGY.md).\n> Regenerate any figure offline with\n> `node bench/src/report.js --stamp full-opus48 --by-type`.\n\n## Install\n\n### Claude Code (plugin marketplace)\n\n```\n/plugin marketplace add Green-PT/honey-for-devs\n/plugin install honey@greenpt\n```\n\nThen `/honey` **once** to turn it on (`/honey lite|full|ultra` to set intensity,\n`/honey off` to stop). The state persists across sessions — a SessionStart hook\nre-activates it every session until you run `/honey off`. A 🍯 badge shows the\nactive mode in your statusline. If your client autocompletes `/honey` to\n`honey:honey`, that's the same command.\n\n### Plain Claude (claude.ai / API) — no install\n\nThe chat edition, [`skills/honey-chat/SKILL.md`](skills/honey-chat/SKILL.md)\n(~500 tokens), is the terse-prose core with the agent-harness levers removed —\nnothing in it needs tools. Two ways to use it:\n\n- **Project custom instructions or a Style (recommended):** paste the file in.\n  Instructions become part of the system prompt, so Honey applies to **every\n  message in every conversation** — always on, no triggering needed. The prefix\n  is prompt-cached, and the ~500 input tokens are repaid many times over by the\n  halved output.\n- **Uploaded Skill (paid plans):** zip the `honey-chat/` folder and upload it as\n  a Skill. Cheaper at rest (only the description stays in context) but loads\n  only when Claude judges it relevant — for an always-on writing style, Project\n  instructions are the better default.\n\nOn the API, use the file as (part of) your `system` prompt. Pin intensity by\nappending one line: `Default to honey ultra` or `Default to honey lite`.\n\n**Other chat UIs (ChatGPT, Gemini, …):** the prompt is model-agnostic — nothing\nin it is Claude-specific. Web custom-instruction fields often cap input\n(ChatGPT: 1,500 characters), so paste the compact edition,\n[`skills/honey-chat/COMPACT.md`](skills/honey-chat/COMPACT.md) (&le;1,500\nchars, test-guarded), into ChatGPT's \"How would you like ChatGPT to respond?\"\nfield or Gemini's saved-info/instructions field. Same rules, condensed; where\nthe field allows more (Claude Projects, API system prompts), prefer the full\n`SKILL.md`.\n\n### One-line installer (interactive wizard)\n\nIn a terminal it asks which agents you use, whether to wire the CO₂ badge, drop\nper-repo rule files, and your default mode — then sets up exactly that. The wizard\nprompts on `/dev/tty`, so it works through `curl | bash`. CI/pipes and `--yes`\nfall back to auto-detect.\n\nmacOS / Linux / WSL / Git Bash:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Green-PT/honey-for-devs/main/install.sh | bash\n```\n\nWindows (PowerShell 5.1+):\n\n```powershell\nirm https://raw.githubusercontent.com/Green-PT/honey-for-devs/main/install.ps1 | iex\n```\n\nWindows (`irm | iex`) runs non-interactive; clone and run `node bin/install.js`\nfor the wizard. Add `bash -s -- --yes` to skip prompts. Requires Node.js on your\nPATH. Safe to re-run; skips tools you don't have.\n\n### Every supported platform\n\n| Platform | Install |\n|----------|---------|\n| Claude Code | `/plugin marketplace add Green-PT/honey-for-devs` then `/plugin install honey@greenpt` |\n| Codex | `codex plugin marketplace add Green-PT/honey-for-devs` then `codex plugin add honey@greenpt` |\n| oh-my-pi (`omp`) | `omp plugin marketplace add Green-PT/honey-for-devs` then `omp plugin install honey@greenpt` |\n| GitHub Copilot CLI | `copilot plugin marketplace add Green-PT/honey-for-devs` then `copilot plugin install honey@greenpt` |\n| Gemini CLI | `gemini extensions install https://github.com/Green-PT/honey-for-devs` |\n| OpenClaw | `clawhub install honey` (companions: `clawhub install honey-review`, …) |\n| Hermes Agent | `node bin/install.js --only hermes` — copies `.hermes/skills/` into `~/.hermes/skills/`; activate with `/honey` (workspace `AGENTS.md` is always-on) |\n| Cursor | copy `.cursor/rules/honey.mdc` into your project |\n| Windsurf | copy `.windsurf/rules/honey.md` into your project |\n| Cline | copy `.clinerules/honey.md` into your project (token-conscious: the compact `skills/honey/cline-rule.md`) |\n| GitHub Copilot (editor) | copy `.github/copilot-instructions.md` into your project |\n| Kiro | copy `.kiro/steering/honey.md` (project or `~/.kiro/steering/`) |\n| OpenCode | `node bin/install.js --only opencode` — copies `AGENTS.md` to `~/.config/opencode/AGENTS.md` (always-on in every project) and `skills/` into `~/.config/opencode/skills/` as native skills; verify with `opencode debug skill` |\n| Kilo Code | copy `.kilo/rules/honey.md` into your project (auto-discovered; `.kilocode/rules/` also works) |\n| Aider / Zed / any AGENTS.md reader | copy `AGENTS.md` into your project |\n\nAll of these are also handled automatically by the one-line installer. See\n[INSTALL.md](INSTALL.md) for manual steps, flags, and uninstall.\n\n## Carbon badge (Claude Code)\n\nWhen Honey is active, the statusline also shows a live **CO₂ estimate** for the\nsession and the **CO₂/$ saved** vs a no-Honey baseline:\n\n```\n🍯 honey:full · 🌿 44g CO₂ (saved ~26g · $0.18)\n```\n\n(Illustrative — a ~2k-output-token Opus session.) The estimate is a faithful port\nof [EcoLogits](https://github.com/genai-impact/ecologits) v0.8.2 (verified to match\nthe package exactly). **Model params come from EcoLogits' own registry**\n([`hooks/eco-models.json`](hooks/eco-models.json), exported by\n[`scripts/build-eco-models.py`](scripts/build-eco-models.py)) — matched by exact id,\nfalling back to a per-family alias for frontier models too new for the registry.\n**Grid switches per provider** — Anthropic on AWS Trainium (~500 gCO₂/kWh), OpenAI\non Azure (~400), Google on GCP (~330). Aliases, grids, and per-mode savings live in\n[`hooks/eco-config.json`](hooks/eco-config.json).\n\nThe badge itself renders **only in Claude Code** (it reads Claude Code's\ntranscript, where every model is a Claude model). The provider switching matters\nfor [`scripts/eco_report.py`](scripts/eco_report.py), which runs against any\ntranscript — Codex/Gemini CLIs would each need their own statusline hook to show\na live badge there.\n\n> Params are **speculative** — Anthropic discloses none. EcoLogits' raw coefficient\n> is a **single-stream (batch-size-1) upper bound** — it gives one request the whole\n> GPU set for the full generation (for Opus, ~1.9 tok/s, ~30× slower than reality),\n> which alone is ~1.4 kg per 1M output tokens. Production serves many requests\n> concurrently, so the badge divides that ceiling by an effective batch concurrency\n> (`serving_concurrency`, default 32 — calibrated so modeled throughput matches real\n> ~50–70 tok/s serving) to show realistic **served** impact. `eco_report.py` prints\n> both the served figure and the single-stream ceiling. Treat these as a range, not\n> a meter reading.\n\nFor the full breakdown (usage + embodied + primary energy) run the real package:\n\n```bash\npip install ecologits\npython scripts/eco_report.py        # newest session, or --transcript PATH\n```\n\n## honey-usage — actual token usage across your coding agents\n\n`honey-usage` ([`bin/usage.js`](bin/usage.js), inspired by\n[tokscale](https://github.com/junhoyeo/tokscale)) reads the session data your\ncoding agents already write to disk and reports **actual token usage** —\ntokens, approximate USD, and served CO₂ — per app and model. Zero dependencies,\nno network, nothing leaves your machine.\n\n| App | Source |\n|---|---|\n| `claude` (Claude Code) | `$CLAUDE_CONFIG_DIR` or `~/.claude` — `projects/**/*.jsonl` |\n| `codex` (Codex CLI) | `$CODEX_HOME` or `~/.codex` — `sessions/**/*.jsonl` |\n| `opencode` (OpenCode) | `($XDG_DATA_HOME` or `~/.local/share)/opencode/opencode.db` (system `sqlite3`) |\n\nApps without data are skipped; adding another is a small scanner returning\n`{app, model, ts, input, output, cacheRead, cacheWrite, cost}` records.\n\n```bash\nhoney-usage                                  # table by app + model, totals row\nhoney-usage --json                           # same aggregation as JSON\nhoney-usage --daily --since 2026-08-01       # per-day breakdown, date-filtered\nhoney-usage --client codex,opencode --today  # scope by app and local day\n```\n\n```\nAPP     MODEL        INPUT      OUTPUT   CACHE-R      CACHE-W     USD     CO2\nclaude  claude-opus-5  85,540  4,296,591  1,814,741,458  44,864,917  $1295.62  94.45kg\n...\n```\n\nDetails that keep the numbers honest:\n\n- **Dedup** — Claude Code repeats assistant records across retries and\n  continuations; each `(message.id, requestId)` counts once, globally.\n- **Cache-aware cost** — rates from [`bench/pricing.json`](bench/pricing.json)\n  (cache writes/reads billed as multipliers on the input rate; unknown models\n  fall back to `_default`, so treat $ as approximate). Codex's\n  `cached_input_tokens` are split out of `input_tokens` and priced as cache\n  reads; OpenCode rows use the app's own recorded cost.\n- **CO₂** — the same served EcoLogits estimate as the badge\n  ([`hooks/eco.js`](hooks/eco.js)), from output tokens; the badge's caveats\n  apply.\n- **Savings are ledger-gated** — the default report has no \"saved\" column: it\n  shows what was actually spent, and app logs don't record whether Honey was\n  active. `honey-usage --savings` claims savings **only** for sessions the\n  SessionStart hook logged to `$CLAUDE_CONFIG_DIR/.honey-usage-ledger.jsonl`\n  (Claude Code, since Honey was installed — history before that is never\n  claimed), and only for models with a committed bench stamp\n  ([`hooks/eco-config.json`](hooks/eco-config.json) `savings_provenance`).\n  Everything else is footnoted, not estimated. The figures stay modeled\n  counterfactuals (`est. modeled from bench/results/… — not measured`), same\n  basis as the badge.\n\n## How it stays in sync\n\nThe skill is authored **once** in [`skills/honey/SKILL.md`](skills/honey/SKILL.md).\nEvery per-platform rule file (and `AGENTS.md`) is generated from it:\n\n```bash\nnode scripts/build-rules.js          # regenerate all rule files\nnode scripts/build-rules.js --check  # CI: fail if any copy drifted\n```\n\nThe OpenClaw (`.openclaw/skills/`) and Hermes (`.hermes/skills/`) skill packages\nare generated the same way from `skills/`; rerun\n`node scripts/build-openclaw-skills.js` / `node scripts/build-hermes-skills.js`\nafter changing a skill. `tests/openclaw-skills.test.js` and\n`tests/hermes-skills.test.js` fail if a committed copy is stale.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\nThe carbon-estimation data and coefficients in `hooks/eco-models.json` and\n`hooks/eco.js` are derived from [EcoLogits](https://github.com/genai-impact/ecologits)\nand remain under the **MPL-2.0**. See [NOTICE](NOTICE) for details.\n",
  "bytes": 30720,
  "sha": "0709a3ba1d91d4c505c42a93538958610acd9665efb2faa22452e98ed6d5e6e9",
  "repo_slug": "green-pt/honey-for-devs",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_green_pt_honey_for_devs_b3fbdd3b/readme"
}