Buzzcut

Ponytail discipline, trimmed down.

Buzzcut is a tiny instruction layer for Claude Code and Codex. It nudges coding agents toward the smallest correct change: skip speculative work, reuse what exists, prefer the platform, fix the shared root cause, and keep code readable.

It is proudly inspired by Ponytail, Dietrich Gebert's excellent “lazy senior developer” toolkit. Ponytail is the original, more ambitious product: polished, funny, extensively benchmarked, and packed with modes, commands, audits, and integrations. Buzzcut explores one narrow question raised by that work:

How much of the discipline can fit in a durable, readable ruleset without paying to repeat the whole idea every turn?

Why Buzzcut?

• Small by construction. The durable rules are about 412 o200k_base tokens in the current build.
• No per-prompt tax. An 89-token reminder runs only after resume/compaction and when a subagent starts.
• Minimal scope, not golfed code. Descriptive names and readable control flow beat clever one-liners.
• Correctness has a floor. Root-cause fixes, trust-boundary validation, data-loss prevention, security, accessibility, calibration, and one runnable check for non-trivial behavior stay in scope.
• Reports match the work. Tiny changes get tiny summaries; substantial changes retain useful verification and decision context.
• Upgradeable installs. Managed markers let reruns replace the rules safely without duplicating them or disturbing the rest of your project guidance.

Ponytail and Buzzcut

This is a specialization, not a claim that Ponytail should disappear.

| | Ponytail | Buzzcut | |---|---|---| | Best for | A full lazy-developer product with modes, commands, audits, reviews, and broad agent support | A compact, opinionated rules layer for Claude Code and Codex | | Default instruction footprint¹ | ~1,264 tokens | ~412 durable tokens | | Reinforcement | Full rules at supported session boundaries and in subagents | ~89-token reminder after resume/compaction and in subagents | | One-line rung | Explicit | Deliberately omitted; readability wins | | Root-cause and safety rules | Yes | Yes | | Non-trivial runnable check | Yes | Yes | | Intensity modes | Lite, full, ultra, off | No; one boring default | | Extra workflows | Review, audit, debt, gain, help | No; YAGNI |

¹ Local estimate from the effective Ponytail full instructions and Buzzcut's durable rules using tiktoken o200k_base. Token billing depends on the host, prompt caching, compaction, model, and session shape. Treat the figures as instruction-footprint measurements, not a cost guarantee.

Ponytail remains the better choice when you want its ecosystem or adjustable intensity. Buzzcut is aimed at teams that want one small policy, readable code, and very little machinery.

The decision ladder

Before writing code, read the touched flow and stop at the first rung that holds:

1. Does this need to exist? Skip it.
2. Does the codebase already do it? Reuse it.
3. Does the standard library or native platform do it? Use it.
4. Does an installed dependency do it? Use it.
5. Only then, write the minimum that works.

The ladder shortens the solution, never the investigation. A tiny patch in the wrong place is still a bug.

Install

Buzzcut is published on npm as @ramigbcom/buzzcut. npx runs the installer without adding Buzzcut to your project's dependencies or requiring a global install.

From the project you want to configure:

npx @ramigbcom/buzzcut

Or pass the project explicitly:

npx @ramigbcom/buzzcut /path/to/project

You can also run a local checkout with node /path/to/buzzcut/install.mjs. The installer requires Node.js 18 or newer and is safe to rerun.

After installation:

• Claude Code: restart the session, then use /hooks to inspect the two Buzzcut entries.
• Codex: use /hooks, review and trust the hooks, then start a new thread from the project root.
• Older Codex versions: if hooks do not fire, enable them in ~/.codex/config.toml:

[features]
codex_hooks = true

What gets installed

| Path | Purpose | |---|---| | CLAUDE.md | Managed full-rules block for Claude Code | | AGENTS.md | Managed full-rules block for Codex | | .claude/buzzcut.md | Compact reactivation reminder | | .claude/hooks/buzzcut.mjs | Structured reminder hook | | .claude/settings.json | Claude context-boundary and subagent registrations | | .codex/buzzcut.md | Compact reactivation reminder | | .codex/hooks/buzzcut.mjs | Structured reminder hook | | .codex/hooks.json | Codex context-boundary and subagent registrations |

The hooks are local Node scripts. They read the installed reminder and return it as additional agent context. They do not make network requests, run project code, or collect telemetry.

Upgrade behavior

Rerun the installation command. Blocks wrapped in these markers are replaced in place:

<!-- buzzcut:start -->
...
<!-- buzzcut:end -->

Earlier releases under the discipline-kit name used either discipline-kit:start markers or an unmarked section. Buzzcut automatically migrates marked blocks. It leaves an unmarked legacy section unchanged because it cannot know where surrounding user guidance begins; delete that old ## Minimal Code Discipline section once, then rerun the current installer.

Existing per-prompt discipline-kit hooks are removed during a current install and replaced with Buzzcut context-boundary hooks. The old reminder files are inert and may be deleted after migration.

Tune without bloating

Edit ruleset.md for durable policy and buzzcut.md for the compact reactivation message, then rerun the installer.

Every new sentence consumes context somewhere. Keep durable details in the ruleset and reserve the reminder for the behavior most likely to drift after compaction.

Run the guardrail check after editing:

node verify.mjs

It enforces:

• a 2,600-byte / 400-word durable-rules budget;
• a 500-byte / 70-word reminder budget;
• required safety and correctness concepts;
• managed block markers;
• context-boundary hooks, with no accidental return to per-prompt injection.

Verify an installation

node /path/to/buzzcut/verify.mjs
node --check /path/to/buzzcut/install.mjs
node --check /path/to/buzzcut/buzzcut.mjs

For an installed project, inspect /hooks in Claude Code or Codex. The registered events should be SessionStart with resume|compact, plus SubagentStart.

Uninstall

1. Delete the buzzcut:start through buzzcut:end block from CLAUDE.md and AGENTS.md.
2. Delete .claude/buzzcut.md, .claude/hooks/buzzcut.mjs, .codex/buzzcut.md, and .codex/hooks/buzzcut.mjs.
3. Remove the hook groups containing buzzcut from .claude/settings.json and .codex/hooks.json.

License

Buzzcut is free and open-source software released under the MIT License. You may use, copy, modify, distribute, sublicense, and sell it, provided the copyright and license notice remain with substantial copies. The software is provided as is, without warranty; the author and copyright holder accept no liability for its use. The LICENSE file is the authoritative legal text.

Credits

Buzzcut was conceived by Rami GB. He liked Ponytail a lot, but wanted to explore a smaller, readability-first direction that could diverge on its own. Fable helped shape the original plan, and GPT-5.6-Sol helped refine and improve the resulting product.

Buzzcut would not exist without Ponytail. Its decision ladder, “lazy, not careless” framing, safety work, public benchmarks, and willingness to document benchmark limitations made this experiment possible—and set a high bar for doing it honestly.

If you want the full experience, install Ponytail. If you want the smallest boring subset that keeps readable-code guardrails, that is what Buzzcut is trying to be.