{ "markdown": "

\"A

\n\n# i-am-the-duck\n\nRubber duck debugging, reversed. You are the duck.\n\n**[中文說明](docs/README.zh-TW.md)**\n\n## What this is\n\nRubber duck debugging is the old trick where you explain your code, line by line, to a rubber duck on your desk. Somewhere in the explanation you find the bug yourself. The duck does nothing. Having to say it out loud, in plain words, is what works.\n\nThis plugin turns that around. The coding agent does the work, and you are the duck. It explains meaningful work in words you can follow without reading the code or the tool output: what is happening and why, what came of it, and what the available evidence supports. It calls out an untested or inferred part when it changes what you can rely on.\n\nIt started as a joke. It stayed because explaining a change in plain words can expose when the reason is missing.\n\n## Early results\n\n**Across three tasks on Opus 5 (high), Duck cut reply characters and output tokens by roughly a third to a half, and wall-clock time and cost by a fifth to two fifths, with blind reviewers rating the answers as correct as the baseline's.**\n\n![Reply characters and output tokens with and without Duck, by task, on Opus 5 high.](evals/assets/initial-results.svg)\n\nSame findings, less to read. The Duck replies open with the verdict, draw a flow only where a fork decides the outcome, answer the asker's questions in the asker's order, and say which claims were checked in code and which were only read.\n\nThe newest task came from a real session where the agent reported a design's status in reviewer finding numbers and spec section codes until the asker had to ask for plain language. Every reply was scored by blind reviewers before the arms were revealed, and the one reply all of them called plain was a Duck reply. [Data and the blind reviews](evals/results/README.md).\n\n## What changes\n\nWithout it, a long session drifts into shorthand:\n\n> Phase C done, all green, merged the fix into the pipeline.\n\nWith it:\n\n> Restarting the service now resumes the timeout check, so overdue work is still detected. `npm test`: 24 passed, 0 failed. I did not run the Codex side; it is not installed here.\n\nThree habits:\n\n- **Before meaningful work** with one clear purpose, say what will happen and why. Reading, searching, and running tests need no announcement.\n- **After meaningful work**, say what happened and the evidence or difference that matters. Call out an untested or inferred part when it changes what you can rely on; do not add checks just to fill out the report.\n- **Words** describe concrete actions or results. Names from code, specifications, plans, tickets, or earlier conversation are labels, not explanations. Use an exact name when it helps locate or distinguish something, then say what it does; otherwise replace it with the concrete action or result. Reuse established context after compaction instead of explaining labels again.\n\nDecisions explain the trade-off that matters for each option and, when relevant, whether its evidence is tested or expected. Work handed to another agent comes back as a result summary, with whether it was checked and any limitation that matters.\n\nIt does not decide what you approve, how far a task goes, what is risky, or whether the code is right. It only makes the agent explain.\n\n## Install\n\nClaude Code:\n\n```\n/plugin marketplace add davidleitw/i-am-the-duck\n/plugin install i-am-the-duck@i-am-the-duck\n```\n\nCodex:\n\n```\ncodex plugin marketplace add davidleitw/i-am-the-duck\ncodex plugin add i-am-the-duck@i-am-the-duck\n```\n\nNeeds `node` 18 or newer on your PATH. Start a new session: a small hook runs at every session start and after context compaction and includes the complete rules in its instruction, so the agent can apply them without searching or rereading them. In Codex, open `/hooks` once, review the hook and trust it; until you do, Codex skips it.\n\nIf the agent drifts back into shorthand, type `/i-am-the-duck:duck` in Claude Code or `$i-am-the-duck:duck` in Codex.\n\nOther hosts, and the update and uninstall commands for each: **[INSTALL.md](INSTALL.md)**.\n\n| Host | Loads the rules for you | Tested by us |\n|---|---|---|\n| Claude Code | yes, at every session start | yes |\n| Codex | yes, once you trust the hook | yes |\n| Gemini CLI | yes, through `GEMINI.md` | no |\n| Qwen Code | not guaranteed — invoke `duck` yourself | no |\n| Kimi Code CLI | not guaranteed — invoke `duck` yourself | no |\n| Cursor, Zed, Copilot, Amp, others | no — invoke `duck` yourself | no |\n\nTested means a real session on the author's machine loaded the rules before the first reply. Reloading after the conversation is compacted has not been tested in a real session on either host; only the hook's answer to that input has.\n\n## Adjust\n\nSay it in the conversation: shorter, more detail, step by step, or only the result at the end. The agent follows that for the rest of the conversation and saves nothing.\n\n## Uninstall\n\nType `/i-am-the-duck:unduck` in Claude Code or `$i-am-the-duck:unduck` in Codex. It shows you what will go, waits for your yes, then removes the plugin. Or by hand:\n\n```\nclaude plugin uninstall i-am-the-duck@i-am-the-duck # add --scope project|local if you installed it there\ncodex plugin remove i-am-the-duck@i-am-the-duck\n```\n\nRemoving the plugin by hand leaves the marketplace you added still configured; `/i-am-the-duck:unduck` offers to remove that too. By hand it is `claude plugin marketplace remove i-am-the-duck`, or `codex plugin marketplace remove i-am-the-duck`.\n\n## What is inside\n\n| Path | What it is |\n|---|---|\n| `skills/duck/SKILL.md` | The rules. This is what the agent reads. |\n| `skills/unduck/` | The uninstall skill. |\n| `hooks/` | The session-start hook: it includes the complete rules at session start and after compaction. |\n| `.claude-plugin/`, `.codex-plugin/`, `.agents/` | The files Claude Code and Codex read to find the plugin. |\n| `gemini-extension.json`, `GEMINI.md`, `qwen-extension.json`, `kimi.plugin.json` | The same for the other hosts. `GEMINI.md` imports the rules rather than copying them. |\n| `INSTALL.md` | Install, update and uninstall, one section per host. |\n\n## Where it came from\n\nLong agent sessions grow a private language. \"All green\" when the run said one failed. \"Phase C\" from a plan the user never opened. The user kept the right to decide and lost the information needed to decide.\n\n## License\n\nMIT\n\nMaintainers: the optional [evaluation workflow](evals/README.md) stays outside the installed skills and hooks.\n", "bytes": 6601, "sha": "eb6649d78c47a57e54e5c7f7fc71afcfbb3cc95b95e1422d8fe3956560fe8e71", "repo_slug": "davidleitw/i-am-the-duck", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_davidleitw_i_am_the_duck_b51f4e82/readme" }