GitHub stars
35

Install

/plugin install claude-bumper-lanes@claude-bumper-lanes

Run it inside Claude Code after adding the marketplace with /plugin marketplace add kylesnowschwartz/claude-bumper-lanes.

Contents

Discovered from source

Skills 2

Budget-Aware Planning

This repository meters your working-tree diff. Every added line spends points from a review budget (edits 1.3× weight, new files 1.0×, deletions free, plus a penalty for touching many files). When the budget runs out, your turn is blocked until a human reviews and resets. The budget is a scope contract: plan increments that fit it, rather than working until the meter trips.

Before large edits

Check the remaining budget before starting a multi-file change:

${CLAUDE_PLUGIN_ROOT}/bin/bumper-lanes budget

Output like 150/600 review-budget pts remain (75% used) means about 110 edited lines remain. Size the next increment to finish inside that remainder, including tests.

Planning rules

  1. Decompose work so each increment lands within one budget: implement, test, and stop at a reviewable boundary before the meter trips.
  2. When a plan will not fit the remaining budget, say so and ask the user whether to pause for review now or split the plan — do not spend the budget and let the trip decide.
  3. When the budget is close to tripping (roughly 85% used, or fewer points remain than the next step needs), run a review before doing more work: review the increment so far (the repo's review command, /code-review by default), stop at the reviewable boundary, and let the user reset — rather than spending the last points and hitting the breaker mid-change.
  4. Deletions are free. Prefer removing code over adding it.
  5. Do not work around the meter: committing solely to reset the budget, or batching edits into fewer, larger writes, defeats the review contract.

When the meter trips

Stop adding scope. Summarize what changed and why at the level a reviewer needs (decisions and risky spots, not a line-by-line recap), then wait. The user runs /bumper-reset after review to restore the budget.

Hook-Intercept-Block Pattern

Pattern for implementing slash commands that execute entirely in the hook handler, bypassing the Claude API call entirely.

Why Use This Pattern

  • No API cost: Commands execute in Go, no Claude API call
  • Faster: Direct execution vs markdown parsing + API round trip
  • Deterministic: No model variance - same input, same output

How It Works

User types: /bumper-reset
    ↓
UserPromptSubmit hook fires
    ↓
prompt_handler.go matches regex: ^/(?:claude-bumper-lanes:)?bumper-reset\s*$
    ↓
handleReset() executes Go logic
    ↓
Returns JSON to stdout: {"decision":"block","reason":"Baseline reset. Score: 0/400"}
    ↓
Claude Code shows "reason" to user, skips API call

The Confusing Naming

Claude Code's hook response API uses counterintuitive terminology:

ResponseWhat It Actually Means
decision: "block""I handled this, don't call Claude API" (NOT "blocked/rejected")
decision: "continue""Let it through to Claude API"
reason: "..."Message shown to user (only with "block")

Key insight: block = "handled and done", not "rejected". The command succeeded.

Implementation Components

  1. Hook config (hooks.json): Routes UserPromptSubmit to handler binary
  2. Handler (internal/hooks/prompt_handler.go): Regex matching + dispatch
  3. Command stubs (commands/*.md): MUST exist for /help discovery (body ignored)

Adding a New Command

Step 1: Add Regex Pattern

In prompt_handler.go:

var newCmdPattern = regexp.MustCompile(`^/(?:claude-bumper-lanes:)?bumper-foo\s*(.*)$`)

The (?:claude-bumper-lanes:)? makes the plugin namespace optional.

Step 2: Add Dispatch

In HandlePrompt():

if m := newCmdPattern.FindStringSubmatch(prompt); m != nil {
    return handleFoo(sessionID, strings.TrimSpace(m[1]))
}

Step 3: Implement Handler

Use the helper functions for DRY session management:

func handleFoo(sessionID, args string) int {
    sess := loadSessionOrBlock(sessionID)
    if sess == nil {
        return 0
    }

    // ... your logic here ...

    if !saveOrBlock(sess) {
        return 0
    }

    blockPrompt("Success message")
    return 0
}

Step 4: Create Command Stub

Create commands/bumper-foo.md:

---
description: Does the foo thing
argument-hint: <optional-args>
---

This command is handled by the hook system.

The markdown body is ignored - the hook handles everything. The file MUST exist for the command to appear in /help.

Step 5: Rebuild

just build-bumper-lanes

Helper Functions

Two helpers reduce boilerplate:

loadSessionOrBlock

func loadSessionOrBlock(sessionID string) *state.SessionState

Returns session state or nil. If nil, error already shown to user via blockPrompt().

saveOrBlock

func saveOrBlock(sess *state.SessionState) bool

Returns true on success. If false, error already shown to user via blockPrompt().

JSON Response Format

The UserPromptResponse struct:

type UserPromptResponse struct {
    Decision string `json:"decision,omitempty"`
    Reason   string `json:"reason,omitempty"`
}

Output via blockPrompt():

func blockPrompt(reason string) {
    resp := UserPromptResponse{
        Decision: "block",
        Reason:   reason,
    }
    out, _ := json.Marshal(resp)
    fmt.Println(string(out))
}

Existing Commands Using This Pattern

All bumper-lanes slash commands use hook-intercept-block:

CommandHandlerPurpose
/bumper-resethandleReset()Capture new baseline, reset score
/bumper-pausehandlePause()Disable enforcement
/bumper-resumehandleResume()Re-enable enforcement
/bumper-viewhandleView()Set/show visualization mode
/bumper-confighandleConfig()Show/set threshold

Debugging Tips

  1. Command not recognized: Check regex pattern matches user input exactly
  2. No output shown: Ensure blockPrompt() is called and JSON printed to stdout
  3. Command not in /help: Verify commands/*.md stub file exists
  4. Binary not updated: Run just build-bumper-lanes after changes

Commands 5

This command is handled by the hook system.

This command is handled by the hook system.

This command is handled by the hook system.

This command is handled by the hook system.

This command is handled by the hook system.

Sponsors

Details

Marketplace
kylesnowschwartz/claude-bumper-lanes
Source
bumper-lanes-plugin
Category
Community