Add session-code-review plugin for backpressure code review#73
Add session-code-review plugin for backpressure code review#73
Conversation
Adds a new validation plugin that uses Claude Code's agent-based hooks to review session changes against REVIEW.md before allowing completion or commits. Two hooks provide backpressure: - Stop hook: reviews all uncommitted changes when Claude finishes - PreToolUse hook: gates git commit/push with a review check Includes a /code-review skill for on-demand branch review. https://claude.ai/code/session_01FHRTJGN8UmVYoWBmiKrYsH
Agent-based hooks can take up to 50 turns of investigation. 120s was too tight for reviewing large diffs. https://claude.ai/code/session_01FHRTJGN8UmVYoWBmiKrYsH
|
🚅 Deployed to the han-pr-73 environment in han-team-platform 4 services not affected by this PR
|
Agent hooks now invoke the /code-review skill instead of duplicating the review logic inline. Single source of truth for review behavior. https://claude.ai/code/session_01FHRTJGN8UmVYoWBmiKrYsH
|
test comment from agent |
|
Code Review PR 73 — session-code-review plugin. Please see detailed review notes. |
Han - Claude Code Plugin MarketplaceProject OverviewHan is a curated marketplace of Claude Code plugins built on Bushido principles. The codebase consists of:
Development Commands# Build the CLI
cd packages/han && npm run build
# Run tests
cd packages/han && npm test
# Format code (from website directory)
cd website && npx biome format --write .
# Run Playwright tests
cd website && npx playwright testPlugin StructureEach plugin follows this structure: Command FilesCommands require YAML frontmatter: ---
description: Brief description of the command
---
Command content here...hooks.json Format{
"hooks": {
"Stop": [
{
"hooks": [
{ "type": "command", "command": "your-command-here" }
]
}
]
}
}CLI ArchitectureThe CLI (
Key files:
VersioningVersion bumps happen automatically via GitHub Actions:
CI/CD
Plugin ValidationUse # Validate a plugin or marketplace
claude plugin validate .
# Validate a specific path
claude plugin validate /path/to/pluginConventions
Plugin InstallationPlugins automatically install the han binary to For users who want to use the CLI outside of Claude Code sessions: # Recommended: Install via curl
curl -fsSL https://han.guru/install.sh | bash
# Or via Homebrew
brew install thebushidocollective/tap/han
# Then install plugins
han plugin install --autoWithin Claude Code, plugins can also be installed via: /plugin install bushido@hanInstallation ScopesBy default, plugins install to user settings ( # User scope (default) - shared across all projects
han plugin install playwright-mcp
# Project scope - only for current project (.claude/settings.json)
han plugin install typescript --scope project
# Local scope - gitignored project settings (.claude/settings.local.json)
han plugin install --scope localScope recommendations:
Global installation via Homebrew or install.sh is optional but provides faster execution for frequent CLI usage. |
Code Review — PR #73: session-code-review pluginGood concept overall — backpressure code review in the session loop rather than post-PR is the right philosophy. A few issues to address before merging. CRITICAL1. PreToolUse agent hook fires on every single Bash callFile: The Even if the agent immediately returns the skip result, spawning an agent process still incurs an API round-trip (typically 1-4s). A session with 50 Bash calls adds 1-3 minutes of latency from this hook alone. The intent ("skip immediately if not a git command") is sound, but an AI agent is the wrong tool for this check. A fast MODERATE2. The custom output format may not actually block executionFile: The prompts instruct the agent to return a custom JSON shape, but for See For the 3. Stop hook spawns an agent on every session completion, including clean treesFile: The prompt checks for an empty diff inside the agent, but the agent still gets fully spawned to make that discovery. A fast command guard ( MINOR4. 300s timeout on PreToolUse hook is very highFile: A 5-minute timeout on a hook that fires before every Bash call is unexpectedly long. Even a thorough diff review should complete in under 60s. Consider 60-120s and document the rationale if 300s is intentional. 5. README install command missing registry specifierFile: The OverallThe skill implementation (
|
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
|
Code Review Nice concept - bringing backpressure code review into the session rather than as a post-PR comment is genuinely useful. A few issues to address before merging. CRITICAL 1. PreToolUse agent hook fires on EVERY Bash command The PreToolUse hook with matcher Bash spawns a full LLM agent for every single bash command, just to check if it happens to be a git commit or git push. This includes file reads, test runs, npm installs - everything. With a 300s timeout budget, this creates massive latency overhead on every Bash call. The prompt attempts to short-circuit (immediately return ok:true), but an agent still has to spin up, process the prompt, and respond before that short-circuit can happen. Fix: Use a two-layer approach - a fast command hook to pre-filter, only proceeding to the agent hook when the command is actually a git commit/push. A command hook that parses stdin and exits 0 for non-matching commands would make this essentially free for the 99% case. 2. Uncertain if ok:false correctly blocks PreToolUse from an agent hook Command hooks block tool execution via non-zero exit code + stdout JSON in hookSpecificOutput format with permissionDecision: deny. The prompts instruct the agent to return ok:false with a reason, but this is not the documented Claude Code format for blocking PreToolUse. If agent hook output is not parsed the same way as command hook stdout, the git commit gate silently does nothing when issues are found - the whole point of the PreToolUse hook fails. This needs validation against the actual Claude Code agent hook protocol. MODERATE 3. Stop hook runs a 300s-budget agent on every single Stop event Every time Claude finishes responding - including after a simple question - a full LLM code review agent launches. For sessions with no meaningful changes, this is pure overhead. Consider wrapping with a command hook that pre-checks for changes before the agent fires. If git diff shows no changes (git diff --quiet), skip the agent entirely. This makes the common case essentially free. 4. Infinite review cycle with no bound The designed behavior is: Stop -> review finds issues -> Claude continues -> fixes -> Stop -> review again. This is intentional backpressure. However, there is no exit condition if Claude cannot fix the issues (e.g., a REVIEW.md rule requires human judgment, or the fix introduces a different issue). Without a max-iterations guard, this could loop indefinitely. Consider adding guidance to the Stop hook prompt: if the same issues persist after a previous fix attempt in this session, allow completion to avoid an infinite loop. 5. SKILL.md Step 6 is incompatible with hook invocation context Step 6 says: If issues were found, ask the user if they would like you to fix them. When /code-review is called from the Stop or PreToolUse hook agent, there is no interactive user - asking a question blocks indefinitely. The skill should branch on invocation context, or the hook prompts should explicitly instruct the agent to fix issues immediately rather than deferring to step 6. MINOR 6. Broken documentation URL README.md line 10 links to https://code.claude.com/docs/en/hooks which does not resolve. The Claude Code docs are at https://docs.anthropic.com/en/docs/claude-code/hooks. 7. Triple diff overlap in SKILL.md Step 3 gathers three diffs: unstaged (git diff), staged (git diff --cached), and all branch commits (git diff base...HEAD). When on a feature branch with committed changes, the committed work is already included in the branch diff. The overlap creates redundant context and inflates token usage. Consider consolidating or adding a comment explaining why all three are needed. 8. Missing SubagentStop hook Other validation plugins (e.g., biome) register SubagentStop hooks so changes made by subagents are also validated. If a subagent makes file changes and stops, those changes bypass this review. Worth considering whether this is intentional. Overall the plugin design is solid and the SKILL.md implementation guidance is clear. The main risks are (1) performance degradation from per-Bash-command agent spawning and (2) the unverified blocking protocol for the PreToolUse hook. Fix those two and this is ready to ship. |
2 participants
Summary
Adds a new
session-code-reviewvalidation plugin that provides automatic code review of changes againstREVIEW.mdandCLAUDE.mdguidelines. The plugin uses agent-based hooks to review changes before session completion and before git commits/pushes, catching issues early in the development workflow.Changes
session-code-reviewplugin with Stop and PreToolUse hooks for automatic code review/code-reviewskill for on-demand manual review of branch changesREVIEW.mdandCLAUDE.mdType of Change
Plugin Changes
Plugin category:
Validation:
Testing
Checklist
https://claude.ai/code/session_01FHRTJGN8UmVYoWBmiKrYsH