Ask Buddy to Develop customer search with filters and pagination and it coordinates the work from research and specification through implementation, verification, and independent review. For a tiny, contained edit, it keeps the work direct and lets your host make the change without an extra review stage. As the change grows or carries more risk, Buddy adds the planning and review steps that help catch problems.
Each stage writes its result to a worklog in your repository, so the next stage starts from facts on disk instead of a long chat history. A narrow fix goes straight to implementation; larger or unclear work gets research and a spec first. Buddy scales review and verification to the change: trivial edits need no independent review, small changes get one balanced review, and substantial changes use the full workflow.
Quick start
Install Buddy in Claude Code:
claude plugin marketplace add leszekgruchala/buddy@main
claude plugin install buddy@buddy
Run /reload-plugins or restart Claude Code, then describe the outcome you want:
Develop customer search with filters and pagination
That's it. You do not configure models or API keys: Buddy uses the models your coding tool already offers. Using Codex or Cursor? See Install and update.
What it does
| Skill | What you get | Try |
|---|
develop | A complete change, from research to verified and reviewed code. | Develop customer search with filters and pagination |
brainstorm | A discussion that tests an idea, kept in one living document. | Brainstorm a neighborhood tool-sharing service with me |
research | A short brief of current facts, evidence, open questions, and rejected ideas. No code changes. | Research how customer search currently works |
innovate | Different solution directions and their trade-offs, added to a passed research brief. | Compare ways to add pagination to customer search |
spec | A phased plan with requirements, success criteria, and verification. | Create a spec for customer search with filters and pagination |
implement | A narrow fix, or one approved spec run with verification. | /implement .ai/worklog/20260804_customer-search/spec_customer-search.md |
test-runner | The relevant tests, lint, type checks, and builds, run and reported. | Run the tests affected by my change |
review-code | Independent, evidence-backed findings for a local change. | /review-code |
change-report | An HTML report that explains a PR or branch diff and its impact. | Use change-report to explain PR #123 and its impact |
archive-worklogs | Old worklogs moved into yearly archive folders. | Archive worklogs older than 30 days |
See progress live in Claude Code
When a Buddy skill runs in Claude Code, a band above the prompt shows:
- the stage track from Research to Review, with skipped stages marked;
- the spec phase in work and a progress bar from its tasks;
- the subagents working on the stage;
- tokens and cost for the run, per stage and per phase, plus the run's total cached reads.
When detailed usage is available, token counts show new tokens: input, output, and cache writes. Cached reads are shown apart, because each request reads the whole cached conversation again, and their sum grows with the number of requests, not with the work done. The cost still includes them. If an agent reports only a total, Buddy keeps that total without estimating a split.
Select Details, or run /buddy-mod, to open a pane with every phase, its task checklist, and each subagent's tokens with its estimated cost. Input, output, and cached token counts appear when reported. Hide removes the band until the next Buddy run. The mod reads only events Claude Code already reports and adds nothing to your prompts or context.
The mod is on by default, also when you update an installed Buddy. To turn off only the mod, set the Buddy option Show the Buddy mod to off. Buddy's skills, agents, and hooks keep working. Use one of these:
- In a Claude Code terminal session, run
/plugin configure buddy@buddy, or change the Show the Buddy mod row in /config. Claude Code reloads Buddy with the new value when you save.
- From your shell, run the command below. Claude Code applies it in your next session, in the terminal and in the Desktop app.
echo '{"show_mod":"false"}' | claude plugin configure buddy@buddy --values-stdin
To turn the mod on again, set the option back to on, or run the same command with "true". claude plugin install reports this option as not yet set until you choose a value; the mod stays on until then. To turn off all mods, use the mod controls.
Explain a code change
change-report turns a pull request or branch diff into a short HTML report: what changed, why, who is affected, and which actions matter.
Use change-report to compare branch feature/customer-search with main
Reports group changes by feature in a Before / After / Impact table with source evidence. High risk, Breaking change, and Human review markers show what needs attention and the next action. When wiring or execution flow changes, Before / After diagram tabs and an Execution flow view show the affected connections; small changes skip diagrams. Reports work offline and are saved in the change's .ai/worklog/ folder.
Open the interactive sample report, or get its self-contained HTML file for local use. The sample is a frozen development example.
Review and learn from findings
Run /review-code for an independent review of a local change. It returns findings with severity, evidence, and a fix, and does not edit your code. develop chooses review effort by scope and risk. A trivial change (about 30 lines or fewer in one area, with no behavior, security, or public-contract impact) stays with the host and skips independent review. A small, narrow behavior change gets implementation followed by one balanced review, with frontier review reserved for security-sensitive work. Substantial work uses the full workflow. For small changes, Buddy repeats review only after a Medium-or-higher finding is fixed; a Low-only rereview is optional and requires a cost note and your choice. Requests such as “no review,” “just change the text,” or “quick fix” suppress review and subagents for that request. When a fix is confirmed, the reviewer can add a short prevention rule to .ai/memory/memory.md that later specs and implementations read as advice.
Destructive-command guard
Buddy bundles a shell guard that stops a short list of commands that are hard or impossible to undo before they run:
- Terraform and OpenTofu changes, and Kubernetes and Helm deletions.
- Deletions on AWS, Google Cloud, and Azure.
- Destructive SQL, database drops, and database resets such as
prisma migrate reset or rails db:drop.
- Forced or deleting Git pushes,
git reset --hard, git clean -f, and other Git commands that discard history.
- GitHub repository, release, and API deletions, and package publishing.
- Docker volume deletion, disk erasing and formatting, and
crontab -r.
- Recursive removal of a root, home, current, or parent directory, such as
rm -rf ~.
What happens next depends on your coding tool:
- Claude Code and Cursor ask you to approve the command. If you approve, it runs. If you decline, or nobody can approve it, such as in a headless run, the agent stops and gives you the exact command to review and run yourself. If you let your tool approve commands automatically, for example with Cursor's auto-run, it also approves these.
- Codex cannot ask from a hook yet, so the guard blocks the command, and the agent gives you the exact command to run yourself.
All other commands run normally, including heredocs, file removal inside your project, and commands the guard cannot read.
The guard prevents accidents. It is not a sandbox: it does not check scripts or programs that a command starts. To limit what agents can change, use your coding tool's sandbox and permission settings.
The guard runs on macOS 10.15 or newer and needs zsh and jq. If jq is missing, the guard blocks shell commands until you install it.
To check that the guard is active, ask the agent to run terraform apply -help. Buddy should ask for approval, or block it in Codex, before Terraform starts. In Codex, the guard runs only after you review and trust Buddy's hook. In Cursor Cloud Agents, the guard might not run, because Cursor does not yet document plugin hooks as available there.
Install and update
Install: Add the marketplace and install Buddy from an interactive Claude Code session or your terminal:
claude plugin marketplace add leszekgruchala/buddy@main
claude plugin install buddy@buddy
Update:
claude plugin marketplace update buddy
claude plugin update buddy@buddy
Restart Claude Code, or run /reload-plugins, before starting work with Buddy. The shared PreToolUse hook is installed automatically.
On the same machine with the same Codex configuration, desktop and CLI share plugin settings and installed files. Use these terminal commands for either client. See the Codex plugin documentation.
Install: Add Buddy's GitHub repository as a marketplace once, then install the plugin:
codex plugin marketplace add leszekgruchala/buddy --ref main
codex plugin add buddy@buddy
Update:
codex plugin marketplace upgrade buddy
After installation or update, restart Codex desktop or start a new CLI session. Buddy appears in desktop Plugins under the buddy marketplace. Review and trust Buddy's PreToolUse hook if prompted, using /hooks in the CLI or the desktop app.
Install from the Git marketplace: Register Buddy's repository in the IDE: open Customize → Plugins, select Add Marketplace → Import from GitHub, and enter https://github.com/leszekgruchala/buddy. Or register it from your terminal:
cursor agent plugin marketplace add https://github.com/leszekgruchala/buddy
Open Customize → Browser Marketplace, find Buddy in the registered marketplace, and select Add. Restart Cursor or reload Window (cmd+shift+r).
Update:
Cursor's plugin update is broken (issue). The update command does not work. You need to re-add the plugin.
cursor agent plugin marketplace remove buddy && cursor agent plugin marketplace add https://github.com/leszekgruchala/buddy
Then open Customize → Browser Marketplace, find Buddy in the registered marketplace, and select Add. Restart Cursor or reload Window (cmd+shift+r).
During implement, Buddy tries to open a native Cursor Goal for the run, so you can track it without typing a goal. If Cursor refuses, Buddy keeps a checklist instead and continues. Say that you do not want Goal tracking to opt out. See Cursor Goal tracking for details.
Usage
Describe the result you want and let develop coordinate the work:
Develop customer search with filters and pagination
For the best results:
-
Describe the outcome, not the steps. develop picks the stages the task needs. Trivial edits stay direct; small changes get a focused implementation and review; substantial changes get the full pipeline. It validates according to scope and finishes after the required checks and review pass.
-
Run one stage when that is all you need. research, innovate, spec, and implement stop after their own stage. Clarifications stay in that request; new requests are routed by their own scope. Ask for research when you need only facts, or for a spec when you want to approve the plan before code changes.
-
Run an approved spec later. Each piece of work has a folder in .ai/worklog/. Pass its spec to /implement to build it in a new session.
-
Name a model only when you care. Buddy recommends a fast, balanced, or frontier tier per stage and your tool picks the model. Your request overrides that:
Develop customer search with filters and pagination. Use MODEL for review.
See Model selection for the full rules.
Buddy reuses existing tests and adds cases only for distinct uncovered failures. Valid passing checks carry across agents and verification stages; required repository checks still apply. See Testing and evidence reuse.
How it works
skills/: one Agent Skills folder per stage. develop coordinates the others.agents/: subagents for research, innovation, implementation, testing, and review. Each stage runs with only the context it needs.hooks/: the destructive-command guard, shared by all three tools.claude/buddy-mod/: the Claude Code progress mod.- docs/workflow.md: stage contracts, research and spec formats, review rules, and model selection.
- docs/harness-compatibility.md: what each tool supports.
Buddy writes these files to your project:
| Path | Contents |
|---|
.ai/worklog/<yyyyMMdd>_<work-name>/ | Research brief, spec, and change reports for one piece of work. |
.ai/worklog/archive/<yyyy>/ | Worklogs moved by archive-worklogs. |
.ai/memory/memory.md | Prevention rules confirmed by code review. |
docs/brainstorming/<YYYY-MM-DD>-<idea-slug>.md | One living document per brainstormed idea. |
Requirements
| Requirement | Needed by | Notes |
|---|
| Codex, Claude Code, or Cursor | Buddy | Install from each tool's plugin marketplace. |
| macOS 10.15 or newer | Destructive-command guard | |
zsh, jq | Destructive-command guard | Without jq, the guard blocks shell commands. |
| Claude Code v2.1.287 or later (terminal), v2.1.286 or later (Desktop app) | Buddy mod | Codex and Cursor do not load the mod. |
| Python 3 | change-report, archive-worklogs | Uses only the standard library. |
Limits
- Buddy provides workflow guardrails, not a security boundary. Your coding tool's sandbox, permissions, and approval system remain authoritative.
- In Cursor Cloud Agents, the destructive-command guard might not run.
- The Buddy mod shows only in a Claude Code session displayed on its own, not in a split-view pane. Subagent costs are estimates at API list prices; the run total comes from Claude Code's own session cost.
develop runs at most two fix and re-review rounds. If findings stay open, it stops as blocked and reports them.- Completed
develop follow-ups can be reclassified as work evolves. Trivial follow-ups do not require a spec amendment. Tests for affected behavior run first for small or trivial changes; substantial changes and shared-code changes run their full relevant test set at the end.
- Cursor can refuse a Goal request. Buddy then tracks the run with a checklist.
- If a requested model or tier cannot run in your tool, Buddy reports it and does not substitute another.
Contributing
Report bugs and ideas in GitHub issues. See releases for what changed in each version.
License
Elastic License 2.0.
