BEP: a guardrail for AI coding agents (Claude Code first)

Agents speed up execution. BEP makes sure you don’t accelerate in the wrong direction.

“When code is cheap, you’re forced to make more product bets, more often. The limiting factor becomes selecting the right thing to build and validating it quickly, not implementing it.”

BEP prevents “Feature A → B → C” before A is validated by turning “build whatever” into budgeted bets:

• a time cap (hours / calendar days),
• a validation target (what would prove this matters),
• a fallback (what you do if validation fails).

Rabbit-hole protection for feature work: BEP is the moment where you decide, do we validate, or do we keep building?

How it works (3 lines)

1. Define a bet (bep new) with a cap + validation target.
2. Track time manually (bep start/bep stop) or automatically via Claude Code hooks (bep init --install-hooks).
3. Use the guardrail: bep status shows when you’re nearing/at cap; Claude hooks can hard-stop new prompts when you’re at cap.

Supported coding agents

• Claude Code (only supported agent right now) via hooks: bep init --install-hooks --agent claude-code.
• Planned (not supported yet): Codex, Cursor, OpenCode, and other agent runners.

Supported analytics platforms

Validation checks run via a provider configured in .bep.providers.json (or by manual entry).

• Mixpanel (mixpanel) — see docs/providers/mixpanel.md.
• Manual entry (manual) — you type the observed value during bep check.

Quick start (Claude Code)

1) Install BEP

npm install -g @samboyd/bep-cli@latest 

2) Initialize in your repo

bep init

This creates repo-local state under bets/:

bets/
  <id>.md
  _state.json
  _logs/
  _evidence/

It also creates .bep.providers.json (provider config) and (if this is a Git repo) adds .bep.providers.json to .gitignore.

During init, BEP will ask if you want to install Claude Code hooks. If you say yes, it writes commands into .claude/settings.json for these hook events: UserPromptSubmit, PostToolUse, PostToolUseFailure, SessionEnd.

Non-interactive install:

# Requires a `.claude/` directory in this repo (or a parent directory)
bep init --install-hooks --agent claude-code

3) Create a bet

bep new landing-page-cta

4) Use Claude Code (automatic time tracking)

Once hooks are installed, Claude Code will call BEP on hook events. BEP will try to attribute work to a bet and (when confident) automatically start/stop/switch so time is tracked without you babysitting timers.

Practical pattern: tell Claude which bet it is working on (use the bet id in your prompt), then build until the guardrail warns/blocks.

5) Check the guardrail

bep status

Manual override (if you want it):

bep start landing-page-cta
bep stop landing-page-cta

Why AI coding agent users use BEP

AI coding agents are extremely good at building. The failure mode is spending hours/tokens producing “finished” features before you’ve validated the underlying assumption.

BEP gives you three guardrails:

• Time caps: stop after N hours (or calendar days) instead of “just one more change”.
• Validation targets: force a measurable check before expanding scope.
• Fallbacks: when validation fails, you have a default next move (kill, narrow, pivot, extend).

Stop agents from turning uncertainty into sunk cost.

Claude Code mode (hooks that can stop runaway prompts)

What BEP installs

bep init --install-hooks --agent claude-code writes hook commands into .claude/settings.json that call:

bep hook claude-code user-prompt-submit
bep hook claude-code post-tool-use
bep hook claude-code post-tool-use-failure
bep hook claude-code session-end

What the guardrail actually does

On user-prompt-submit, BEP may respond with JSON like:

{"continue": false, "stopReason": "Bet 'landing-page-cta' is at cap ..."}

That is the “kill switch” moment: Claude is about to keep going, BEP says “stop and validate (or change the bet).”

You can sanity-check the hook command locally:

echo '{"session_id":"demo","prompt":"Implement more changes","cwd":"/repo"}' \
  | bep hook claude-code user-prompt-submit

Notes:

• Hook events are logged under bets/_logs/ (for example: bets/_logs/agent-sessions.jsonl, bets/_logs/agent-attribution.jsonl, bets/_logs/agent-blocks.jsonl).
• If BEP can’t confidently attribute work to a bet, it logs uncertainty and stays non-blocking.

A realistic workflow (day in the life)

1. bep new pricing-page (set cap, validation, fallback).
2. bep start pricing-page.
3. Paste the “agent contract” (next section) into Claude Code.
4. Let Claude implement until BEP warns you via bep status or blocks new prompts via hooks.
5. Run the validation step; capture evidence with bep check pricing-page.
6. If validation fails: do the fallback instead of polishing the feature.

Using BEP as an agent contract (paste into Claude)

Use this as a system-style rule for Claude Code when working on a bet:

• Implement only until you hit the time cap (or BEP blocks prompts).
• If you’re blocked or nearing cap, propose the smallest validation step that would change the decision.
• If validation can’t be reached cheaply, propose the bet’s fallback (kill, narrow, pivot, extend) and stop building.

What BEP is (and isn’t)

• BEP is a repo-native guardrail for decisions under uncertainty.
• BEP isn’t a PM suite, an OKR system, or a time-tracking app.

CLI surface (current)

Use npx @samboyd/bep-cli@latest ... if you have not installed it globally.

bep init [options]
bep new [id...]
bep start <id>
bep stop <id>
bep status
bep check <id> [--force]
bep hook <agent> <event>

bep init options:

• --install-hooks
• --no-install-hooks
• --agent <agent> (currently: claude-code)

Experimental status (v0.1.0)

This project is experimental. Expect breaking changes before v1.0.0.

Safe to try:

• BEP only adds repo-local files/config under bets/ and .bep.providers.json, plus optional hook config in .claude/settings.json if you choose hook install.
• To remove it, delete bets/, delete .bep.providers.json, and remove the .bep.providers.json entry from .gitignore if BEP added it.

More docs

• README.md (full project overview)
• docs/agents/claude-code-hooks-integration.md (hook integration notes; currently a stub)
• docs/providers/mixpanel.md (Mixpanel validation provider)