🍯 Honey (I Shrunk the AI)

Write less code and say less about it. Honey (I Shrunk the AI) by

GreenPT is a

cross-tool coding skill that cuts AI coding-agent token usage and LLM API costs —

making agents emit less code *and* less prose without losing correctness. It works

with **Claude (claude.ai and the API), Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, Windsurf, Cline,

OpenClaw, oh-my-pi, Kiro, Kilo Code, and Hermes Agent**. Three independent levers, applied reflexively:

1. Less code — YAGNI first. Walk a ladder (does it need to exist? → stdlib →

language native → existing dependency → one line → minimum block) and stop at

the first rung that works. The cheapest line is the one you never write.

2. Less prose — drop the wind-up, the hedging, the narration of code that

already speaks for itself. Answer first.

3. Denser agent-to-agent handoffs — when the reader is another agent, not a

human, hand it the most token-efficient format it parses losslessly (compact /

columnar JSON, or ESON). Cuts handoff size ~in half at zero loss

of recovery. Fires only here — never as a user-facing answer.

Honey combines what Ponytail

(minimal code) and Caveman (terse

prose) do separately, then goes further:

• Auto-intensity — `lite` / `full` / `ultra` chosen reflexively from the

request, with no deliberation tax (it never spends reasoning tokens deciding

*how* to comply — that would defeat the purpose on reasoning models).

• Safety carve-outs — input validation, error handling, auth, secrets,

migrations, deletes, and anything you explicitly asked for are never

compressed. Lazy ≠ broken.

• A skill family, not one prompt — an always-on core plus on-demand satellites

(review, eco, gain, compress) and a *hive* of read-only subagents that return

compressed handoffs. See Skills & subagents.

Why

Volume is cost. In agentic coding sessions, the volume of generated code and

prose is what runs up the bill — and most of it is waste.

This repo ships a reproducible benchmark (`bench/`) so you don't have

to take the numbers on faith: 23 tasks across three kinds of work — baseline vs

Caveman vs

Ponytail vs Honey — same model, same

prompts, only the skill changes. Correctness is objective (unit tests, structural /

accessibility checks, and lossless round-trip recovery for agent handoffs); quality

is scored by a 4-model cross-family judge panel (median of Opus 4.8 + Sonnet 4.6

+ Haiku 4.5 + GPT-5.5) under a neutral rubric that says nothing about length, so a

terse skill gets no thumb on the scale. The figures below are the committed results

(Claude Opus 4.8, 3 runs each) — run `cd bench && npm run bench` to reproduce.

Every number is a paired per-task delta vs baseline — runs collapse by median,

tasks pair up, and the figure is the median of those paired deltas with a two-sided

Wilcoxon `p`. Not a ratio of arm totals: that is dominated by whichever task happens

to be longest, and it is how token-saving tools end up publishing numbers nobody can

reproduce. Endpoints and the run ladder are pre-registered in

`bench/METHODOLOGY.md`.

On Claude Opus 5 (23 tasks × 3 runs, 207 cells, zero refusals or truncation —

`full-opus5-lean`):

the original by hash on demand.

some-tool | eson crush          # → sampled view + sentinel; originals cached in .honey-ccr/
eson retrieve             # → the full original array, verbatim

Validated on a 90-row log (opus-4.8 + gpt-5.5): −82% tokens, crushed-only 96%

answer accuracy, 100% with retrieve — and the lone crushed miss was a refusal, not a

hallucination. Benches: `npm run bench:ccr` (tokens) and `npm run bench:ccr:comprehension`

(quality). The `honey-ccr` skill tells the agent when to reach for it.

> Known limitation (upstream): Claude Code builds affected by

> anthropics/claude-code#68951

> (a regression present since ~2.1.121, still open) ignore a PostToolUse hook's

> `updatedToolOutput` for the built-in Bash tool. On those versions the entry-time

> hook runs and stashes the original, but the model still receives the raw

> uncompressed output — honey warns once at session start when it detects an

> affected version. Piping explicitly (`some-tool | eson crush`) is unaffected:

> compression happens before the output leaves the tool. Separately, the hooks

> need Node >= 14 on the PATH Claude Code spawns them with — desktop-app

> sessions inherit the launchd PATH, not your shell profile, so a stale

> `/usr/local/bin/node` is common; the hook now warns instead of failing silently.

PX — image-rendered reads for huge dense read-only bulk

The intuition: sending a file as text pays per character; sending an image

pays per pixel, no matter how much text is crammed into it. So a "photo of the

page" costs ~5× less than the page itself — and reading it has photo problems:

the gist survives, an exact serial number might not.

Concretely: dense text packs ~3 chars per image-token vs ~1 as text. PX

exploits the gap on the *read* path: when the agent must skim something huge it

will never edit (vendored code, a large diff, docs), it renders it to PNG pages

with pxpipe's `export` and `Read`s the

images instead of the text.

npx pxpipe-proxy export --json --out "$TMPDIR" src/   # → page-*.png + factsheet.txt + token report

Measured: up to −85% tokens on a single read. Repo-corpus bench

(`npm run bench:px`, results): −79…85%, −82% average

(26.4k Claude text tokens → 4.8k image est.); ~−75% all-in per read after the

factsheet + report overhead; pxpipe's own end-to-end proxy bill measures −59…70%

at whole-workload level.

Comprehension is a Fable story. The live 4-model panel

(`node bench/px/comprehension.mjs` — 10 byte-exact questions, text vs render):

Only Fable-class models read renders usably — and even Fable is not byte-safe.

Lossy on exact strings — misreads are silent confabulations (Haiku answered a

seed question with `0x9e3779b9`, a constant that isn't in the file), so the export

ships verbatim precision tokens (paths, SHAs, numbers) as `factsheet.txt` text, and

the `honey-px` skill forbids it for files you'll edit, secrets, or non-Fable

readers. Over the raw API, prepend the export's `prompt.txt` banner — Fable's

safety layer refuses naked dense renders. Complementary to CCR: CCR drops

redundant rows recoverably; PX keeps everything in view at pixel prices. At

`/honey ultra` the core skill reaches for PX automatically on qualifying reads

(big, dense, read-only); at other intensities it stays on-demand via `honey-px`.

For the

full wire-level version (system prompt, tool docs, history), run the pxpipe proxy

itself — Honey and pxpipe stack.

Pick Honey when you want the best quality-per-token, especially in Claude Code.

Input precompression — a measured negative result

The three levers above cut output. There's symmetric waste on the input side —

filler, pleasantries, and repeated sentences in the prompt itself.

`hooks/precompress.js` is a deterministic, no-model compressor

that strips them before the prompt reaches the LLM, protecting code, paths, URLs,

double-quoted strings, and numbers verbatim (it never touches a token you'd need exact).

printf '%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
# -> write a function `add(a, b)` that returns their sum? in advance!

It's safe and lossless (35/35 property checks; on 10 unit-tested tasks the model's output

passes 100%→100% from full vs compressed prompts), and on *chatty* prompts it cuts a lot —

−16.5% median on a hand-written verbose corpus.

But that corpus flatters it. Measured on 266 real human-typed prompts from 35 actual

sessions (`bench/input/RESULTS.md`), the cut is **2.5% total, median

0%** — 219 of 266 prompts compress to nothing, because real prompts are already terse and carry

almost no filler. Deterministic no-model compression can't catch *reworded* restatement (that

needs a model), so this is the real ceiling, not a tuning problem.

The honest conclusion: the prompt is the wrong target. Real input volume in agentic coding

is tool output (CCR's domain) and re-pasted context across turns — not human pleasantries. This

ships as a CLI filter for the chatty-prompt case; it is not wired always-on, because on real

traffic it would save ~nothing. Kept here as a measured negative result, in the repo's spirit of

not overstating. Reproduce: `node bench/input/tokens.mjs`.

Skills & subagents

Honey is one always-on core plus a family of on-demand tools. The core is a

*writing style* (it must be the default to pay off); the rest are *actions* you

reach for at a specific moment.

The hive is Lever 3 with a runtime: each subagent returns a compressed handoff,

so the result injected back into the orchestrator's context is −44–53% smaller

with zero loss (`npm run bench:hive`). Live, the skills hold up too — honey −86%,

honey-review −70%, hive-reviewer −43% output tokens at passing correctness

(`npm run bench:skills`). See `bench/hive/RESULTS.md` and

`bench/skills/RESULTS.md`.

On user-facing work — where the core skill *spends* tokens because polish is the

spec — `honey-design` keeps the same rendered polish for −19% output tokens vs no

skill (judge 92 vs 90), beating the core skill on both axes across 7 landing-page/UI

tasks. See `bench/results/honey-design.md`.

> Honesty note. Earlier versions of this README quoted `92% / 78% / 73%` quality

> and `−57% / −65% / −70%` tokens from an unpublished run. Those don't reproduce —

> the real quality spread is far narrower and the token savings are tier-dependent

> (and Ponytail *adds* tokens on simple code).

>

> A second correction, 2026-07-29: the figures before that were **ratios of arm

> totals** (`sum(honey)/sum(baseline)`), which one long task can dominate. Everything

> above is now a paired per-task median with a p-value. That moved honey's headline

> from −15% to −29% — the old method was understating it — but it also retired

> two numbers that turned out to be outlier artifacts: Ponytail's "−22% output" is

> really −7% (ns), and Caveman's "tied quality" is a 16-of-23-task loss (p=0.004).

> Method and pre-registered endpoints: `bench/METHODOLOGY.md`.

> Regenerate any figure offline with

> `node bench/src/report.js --stamp full-opus48 --by-type`.

Install

Claude Code (plugin marketplace)

/plugin marketplace add Green-PT/honey-for-devs
/plugin install honey@greenpt

Then `/honey` once to turn it on (`/honey lite|full|ultra` to set intensity,

`/honey off` to stop). The state persists across sessions — a SessionStart hook

re-activates it every session until you run `/honey off`. A 🍯 badge shows the

active mode in your statusline. If your client autocompletes `/honey` to

`honey:honey`, that's the same command.

Plain Claude (claude.ai / API) — no install

The chat edition, `skills/honey-chat/SKILL.md`

(~500 tokens), is the terse-prose core with the agent-harness levers removed —

nothing in it needs tools. Two ways to use it:

• Project custom instructions or a Style (recommended): paste the file in.

Instructions become part of the system prompt, so Honey applies to **every

message in every conversation** — always on, no triggering needed. The prefix

is prompt-cached, and the ~500 input tokens are repaid many times over by the

halved output.

• Uploaded Skill (paid plans): zip the `honey-chat/` folder and upload it as

a Skill. Cheaper at rest (only the description stays in context) but loads

only when Claude judges it relevant — for an always-on writing style, Project

instructions are the better default.

On the API, use the file as (part of) your `system` prompt. Pin intensity by

appending one line: `Default to honey ultra` or `Default to honey lite`.

Other chat UIs (ChatGPT, Gemini, …): the prompt is model-agnostic — nothing

in it is Claude-specific. Web custom-instruction fields often cap input

(ChatGPT: 1,500 characters), so paste the compact edition,

`skills/honey-chat/COMPACT.md` (≤1,500

chars, test-guarded), into ChatGPT's "How would you like ChatGPT to respond?"

field or Gemini's saved-info/instructions field. Same rules, condensed; where

the field allows more (Claude Projects, API system prompts), prefer the full

`SKILL.md`.

One-line installer (interactive wizard)

In a terminal it asks which agents you use, whether to wire the CO₂ badge, drop

per-repo rule files, and your default mode — then sets up exactly that. The wizard

prompts on `/dev/tty`, so it works through `curl | bash`. CI/pipes and `--yes`

fall back to auto-detect.

macOS / Linux / WSL / Git Bash:

curl -fsSL https://raw.githubusercontent.com/Green-PT/honey-for-devs/main/install.sh | bash

Windows (PowerShell 5.1+):

irm https://raw.githubusercontent.com/Green-PT/honey-for-devs/main/install.ps1 | iex

Windows (`irm | iex`) runs non-interactive; clone and run `node bin/install.js`

for the wizard. Add `bash -s -- --yes` to skip prompts. Requires Node.js on your

PATH. Safe to re-run; skips tools you don't have.

Every supported platform

All of these are also handled automatically by the one-line installer. See

INSTALL.md for manual steps, flags, and uninstall.

Carbon badge (Claude Code)

When Honey is active, the statusline also shows a live CO₂ estimate for the

session and the CO₂/$ saved vs a no-Honey baseline:

🍯 honey:full · 🌿 44g CO₂ (saved ~26g · $0.18)

(Illustrative — a ~2k-output-token Opus session.) The estimate is a faithful port

of EcoLogits v0.8.2 (verified to match

the package exactly). Model params come from EcoLogits' own registry

(`hooks/eco-models.json`, exported by

`scripts/build-eco-models.py`) — matched by exact id,

falling back to a per-family alias for frontier models too new for the registry.

Grid switches per provider — Anthropic on AWS Trainium (~500 gCO₂/kWh), OpenAI

on Azure (~400), Google on GCP (~330). Aliases, grids, and per-mode savings live in

`hooks/eco-config.json`.

The badge itself renders only in Claude Code (it reads Claude Code's

transcript, where every model is a Claude model). The provider switching matters

for `scripts/eco_report.py`, which runs against any

transcript — Codex/Gemini CLIs would each need their own statusline hook to show

a live badge there.

> Params are speculative — Anthropic discloses none. EcoLogits' raw coefficient

> is a single-stream (batch-size-1) upper bound — it gives one request the whole

> GPU set for the full generation (for Opus, ~1.9 tok/s, ~30× slower than reality),

> which alone is ~1.4 kg per 1M output tokens. Production serves many requests

> concurrently, so the badge divides that ceiling by an effective batch concurrency

> (`serving_concurrency`, default 32 — calibrated so modeled throughput matches real

> ~50–70 tok/s serving) to show realistic served impact. `eco_report.py` prints

> both the served figure and the single-stream ceiling. Treat these as a range, not

> a meter reading.

For the full breakdown (usage + embodied + primary energy) run the real package:

pip install ecologits
python scripts/eco_report.py        # newest session, or --transcript PATH

honey-usage — actual token usage across your coding agents

`honey-usage` (`bin/usage.js`, inspired by

tokscale) reads the session data your

coding agents already write to disk and reports actual token usage —

tokens, approximate USD, and served CO₂ — per app and model. Zero dependencies,

no network, nothing leaves your machine.

Apps without data are skipped; adding another is a small scanner returning

`{app, model, ts, input, output, cacheRead, cacheWrite, cost}` records.

honey-usage                                  # table by app + model, totals row
honey-usage --json                           # same aggregation as JSON
honey-usage --daily --since 2026-08-01       # per-day breakdown, date-filtered
honey-usage --client codex,opencode --today  # scope by app and local day

APP     MODEL        INPUT      OUTPUT   CACHE-R      CACHE-W     USD     CO2
claude  claude-opus-5  85,540  4,296,591  1,814,741,458  44,864,917  $1295.62  94.45kg
...

Details that keep the numbers honest:

• Dedup — Claude Code repeats assistant records across retries and

continuations; each `(message.id, requestId)` counts once, globally.

• Cache-aware cost — rates from `bench/pricing.json`

(cache writes/reads billed as multipliers on the input rate; unknown models

fall back to `_default`, so treat $ as approximate). Codex's

`cached_input_tokens` are split out of `input_tokens` and priced as cache

reads; OpenCode rows use the app's own recorded cost.

• CO₂ — the same served EcoLogits estimate as the badge

(`hooks/eco.js`), from output tokens; the badge's caveats

apply.

• Savings are ledger-gated — the default report has no "saved" column: it

shows what was actually spent, and app logs don't record whether Honey was

active. `honey-usage --savings` claims savings only for sessions the

SessionStart hook logged to `$CLAUDE_CONFIG_DIR/.honey-usage-ledger.jsonl`

(Claude Code, since Honey was installed — history before that is never

claimed), and only for models with a committed bench stamp

(`hooks/eco-config.json` `savings_provenance`).

Everything else is footnoted, not estimated. The figures stay modeled

counterfactuals (`est. modeled from bench/results/… — not measured`), same

basis as the badge.

How it stays in sync

The skill is authored once in `skills/honey/SKILL.md`.

Every per-platform rule file (and `AGENTS.md`) is generated from it:

node scripts/build-rules.js          # regenerate all rule files
node scripts/build-rules.js --check  # CI: fail if any copy drifted

The OpenClaw (`.openclaw/skills/`) and Hermes (`.hermes/skills/`) skill packages

are generated the same way from `skills/`; rerun

`node scripts/build-openclaw-skills.js` / `node scripts/build-hermes-skills.js`

after changing a skill. `tests/openclaw-skills.test.js` and

`tests/hermes-skills.test.js` fail if a committed copy is stale.

License

MIT — see LICENSE.

The carbon-estimation data and coefficients in `hooks/eco-models.json` and

`hooks/eco.js` are derived from EcoLogits

and remain under the MPL-2.0. See NOTICE for details.