You know the type. Unbothered, has seen every framework rise and fall and didn't migrate to any of them. You hand over a vague ticket and fifty lines of someone's first draft. He reads it, asks the two questions that actually matter, draws a little box-and-arrow on a napkin, and replaces the whole thing with the part you needed.

Capybaraa puts that habit inside your AI agent.

It's the half of "good engineering" that agents skip: think before you type, then leave the place clean. It makes the agent clarify the spec before it writes code, pick the right complexity, stop padding output, actually verify "done", and not leave dead code and stale comments behind.

Before and after

You ask for "add a settings page." A stock agent invents a SettingsManager, a ConfigProvider, three new files, a migration, and starts coding before it knows what settings you even mean.

With capybaraa it drops into plan mode first:

🦫 a couple of questions before I touch code:

   ┌─ settings ─┐
   │ theme      │  persisted where?
   │ ...        │  (localStorage / your API / both)
   └────────────┘

   1. Just theme for now, or more fields coming?
   2. Per-device, or synced to the account?

   edge cases I'll handle: no-JS fallback, unknown stored value, first load.

Then it writes the smallest thing that answers your actual answers, and runs the check before it says it's done.

The six pillars

The capybaraa way: understand the prompt, gather real context, learn the codebase, explore the actual flow. For anything past a trivial ask, drop into plan mode, ask the curated questions you need (ASCII on the options), then write the real root-cause fix. Never patchwork.

| Pillar | What it enforces | |--------|------------------| | CLARIFY | Understand and explore first, then for non-trivial work use plan mode: as many curated questions as the task actually needs (one or a dozen, never a fixed quota), a small ASCII sketch on the options, explicit edge cases. Don't guess the spec. | | LEAN | The YAGNI ladder: does it need to exist? reuse what's here? stdlib? native? one line? then minimal code. | | OPTIMAL | Right data structure, best feasible time and space, no needless O(n²). | | ECONOMY | Terse output, no useless comments or filler, minimal tokens, no over-exploring. | | COMPLETE | Finish terminally, root cause not symptom, and run the check before claiming done. | | HYGIENE | Refactor means replace, not pile-on. Delete dead code and stale comments, sanitize inputs, flag security. Out-of-scope finds get surfaced, not silently changed. |

The point was never "fewest tokens." It's: do exactly what the task needs, understand it first, and never cut validation, error handling, security, or accessibility. The code ends up small because it's necessary, not golfed.

How it works

One source of truth, principles/build-instructions.js, injected every session by a SessionStart hook and into every subagent by a SubagentStart hook. Your level lives in a flag file (~/.claude/.capybaraa-active).

It's proportional, on purpose:

 ALWAYS-ON  the 6 pillars as terse rules. prompt-cached, ~free per turn.
 PLAN MODE  the clarify-with-ASCII questions and the run-the-check done-gate
            kick in only when the task is big enough to earn them.

A one-line fix gets the rules and nothing else: no ceremony, no token burst. A real feature gets the full treatment through Claude Code's plan mode.

Does it actually help? (numbers)

Short answer: there's a benchmark you can run yourself, and the results live in benchmarks/. We don't ship made-up numbers in this README. Run the suite against your own models and read the dated writeup it produces:

cd benchmarks
npx promptfoo eval -c promptfooconfig.yaml --output results/latest.json   # needs your model creds
node score.js results/latest.json                                        # LOC / cost / latency table

The harness pairs each task with a correctness gate, so a broken one-liner that "looks short" fails instead of scoring well. Methodology and caveats (what's executed vs. structurally checked, single-shot vs. agentic) are in benchmarks/README.md. Once you've run it, the medians land in benchmarks/results/ and you can quote them here.

Install

Claude Code (native plugin, recommended)

/plugin marketplace add katipally/capybaraa

/plugin install capybaraa@capybaraa

(Two separate prompts.) Needs node on your PATH for the lifecycle hooks. Without it the skills still work, the always-on activation just stays quiet.

Cursor, Copilot, OpenCode (one-shot wizard)

Run in your project. It detects what you have and writes each tool's rules file:

npx capybaraa init       # detect tools, install the rules
npx capybaraa doctor     # show what's installed where
npx capybaraa update     # refresh to the latest text

(After npm i -g capybaraa it's just capybaraa init.)

Levels

/capybaraa low | medium | high | off          "stop capybaraa" also turns it off

| low | nudges only: build it, name the leaner option in one line | | medium (default) | all pillars, proportional; plan mode when the task warrants it | | high | aggressive: max questioning, deletion first, strict done-gate |

The level shows in your statusline as [CAPYBARAA] or [CAPYBARAA:HIGH]. Set a default for every session with CAPYBARAA_DEFAULT_LEVEL (low/medium/high/off) or defaultLevel in ~/.config/capybaraa/config.json. Default is medium.

Commands

The six pillars are always on, there's no command to run them. Once installed, capybaraa applies to every task automatically. The slash commands are just for intensity, review, and help:

| Command | What it does | |---------|--------------| | /capybaraa [low \| medium \| high \| off] | Set the intensity, or turn it off. No argument means medium. | | /capybaraa-review | Review the current diff against the six pillars. Lists findings, doesn't edit. | | /capybaraa-help | Quick reference card. |

They're plugin skills, so they may show up namespaced as /capybaraa:capybaraa in the menu. Skills load at session start, so start a new session after installing. The wizard-installed tools (Cursor, Copilot, OpenCode) get the same always-on rules.

Develop and test locally

git clone https://github.com/katipally/capybaraa && cd capybaraa
node test/smoke.js                 # the runnable checks (principles, parsing, bridges)
claude --plugin-dir .              # load the plugin without installing
claude plugin validate .           # validate the manifest (Claude Code CLI)

To exercise the wizard without publishing: node bin/capybaraa.js init in a throwaway directory.

Uninstall

| Host | Command | |------|---------| | Claude Code | /plugin remove capybaraa | | Cursor / Copilot / OpenCode | npx capybaraa uninstall (removes the rules it wrote) |

FAQ

Does it slow every task down with questions? No. Trivial asks get the rules and nothing else. The questions and the done-gate only fire when the task is big or ambiguous enough to need them.

Do I need a config file? No. CAPYBARAA_DEFAULT_LEVEL or ~/.config/capybaraa/config.json can set a default level, but nothing is required.

Why a capybaraa? Calmest animal alive, gets along with everything, wastes zero energy. You already knew.

License

MIT.