Kashif Manzer has released clear-caption, a new open-source plugin for Claude Code designed to eliminate the blind approval fatigue many developers experience when interacting with AI coding agents. The tool intercepts commands before they execute, injecting a plain-English summary directly above the raw code. This addresses a critical usability gap: users frequently approve complex shell operations like git reset --hard or recursive file deletions without fully parsing the implications, effectively trusting the model’s intent over their own verification.

The Mechanics of Human-Readable AI

The plugin operates using Claude Code’s early-access mod hooks, ensuring that the original command structure remains untouched while providing a descriptive layer. For shell commands and subagent calls, clear-caption displays the agent’s own description. For file edits and writes, which often lack explicit intent, the plugin prompts Claude to generate a one-sentence explanation of why the change is occurring. This caption appears as a separate line above the diff, preserving the integrity of the actual code while offering immediate context. Crucially, subagent internal calls remain un-captioned to prevent screen flooding during complex, multi-step operations.

Safety Warnings and Risk Detection

A standout feature is the proactive risk warning system, marked by a ⚠ symbol. Unlike the descriptive captions, these warnings are generated by pattern-matching the actual command syntax rather than relying solely on Claude’s self-description. The system flags high-risk operations such as recursive deletes (rm -r) outside temp folders, force pushes, git clean -f, and piping curl into a shell. It intelligently excludes routine cleanup in /tmp or scratchpad directories, recognizing that not all deletions are dangerous. This dual-layer approach—descriptive captions for understanding and pattern-based warnings for safety—provides a robust guardrail against catastrophic mistakes.

Performance and Implementation

Manzer reports that edit captions successfully landed on 57 out of 57 tested edits across Opus, Sonnet, and Haiku models. The performance impact is minimal, with testing showing an average cost identical to non-captioned sessions, despite a marginal 3% increase in output tokens. Users can configure verbosity via slash commands: /caption all for full narration, /caption risky for safety-only warnings, or /caption off to disable the feature. The plugin is free, MIT-licensed, and available for installation via the Claude Code prompt using the marketplace command /plugin install clear-caption --marketplace KashifManzer/clear-caption.

Key Takeaways

  • Transparency Layer: clear-caption adds plain-English descriptions to shell commands and file edits without altering the underlying code execution.
  • Pattern-Based Safety: The tool uses regex-like pattern matching to flag dangerous commands (e.g., git reset --hard) independently of Claude's self-description.
  • Low Overhead: Testing showed no significant cost increase, with only a 3% rise in output tokens on Opus models.
  • Configurable Verbosity: Users can toggle between full captions, risk-only warnings, or complete disablement via slash commands.
  • Early Access Dependency: The plugin relies on Claude Code’s early-access mod hooks, meaning future API changes could affect stability.

The Bottom Line

Blindly approving AI-generated shell commands is a ticking time bomb for production environments; clear-caption offers a pragmatic, low-cost insurance policy that restores human oversight to the loop.