JuhBDI is a Claude Code plugin that transforms AI-assisted coding from prompt-and-pray into a governed development engine. Built on the BDI (Belief-Desire-Intention) cognitive model, it brings enterprise-grade governance, auditability, and intelligent automation to every task.

The loop: Define intent → Challenge assumptions → Plan waves → Execute in isolation → Learn from outcomes → Repeat.

User Intent ──→ Socratic Challenge ──→ Wave Planning ──→ Parallel Execution
                     │                      │                    │
              intent-spec.json      roadmap-intent.json    git worktrees
                     │                      │                    │
              HITL gates             dependency waves      task-executor agents
                     │                      │                    │
                     └──── decision-trail.log ◄──── audit everything ───┘

Why JuhBDI

Most AI coding tools do what you tell them. JuhBDI does what you mean.

• No more context loss — persistent beliefs, memory, and state across sessions
• No more cowboy AI — every decision audited, every file governed, every task verified
• No more wasted tokens — 5-signal model routing sends tasks to the cheapest tier that works
• No more manual retry — 3-strike recovery with root cause analysis and alternative strategies
• No more blind execution — Socratic challenge catches bad ideas before they become bad code

Install

npm (all platforms)

npx juhbdi@latest

macOS

curl -fsSL https://www.juhlabs.com/juhbdi/install.sh | bash -s -- --global

Linux (Ubuntu/Debian/Fedora/Arch/WSL2)

# Ensure prerequisites
sudo apt install -y nodejs npm git    # Debian/Ubuntu

# Install JuhBDI
curl -fsSL https://www.juhlabs.com/juhbdi/install.sh | bash -s -- --global

# If CLI not on PATH after install
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

Windows (WSL2)

# Install WSL2 first (if not already installed)
wsl --install

# Then inside WSL2 (Ubuntu):
sudo apt install -y nodejs npm git
curl -fsSL https://www.juhlabs.com/juhbdi/install.sh | bash -s -- --global

Interactive mode

curl -fsSL https://www.juhlabs.com/juhbdi/install.sh -o install.sh && bash install.sh

Platforms: macOS · Linux · Windows (WSL2) Requirements: Bun (auto-installs if missing) · Node.js · Claude Code · Git

IDE Support

JuhBDI works natively in Claude Code and can be installed into 17 AI coding tools:

npx juhbdi install --list              # See all supported IDEs
npx juhbdi install --ide cursor        # Install for Cursor
npx juhbdi install --ide all           # Install for all detected IDEs
npx juhbdi install --ide detect        # Auto-detect IDEs in project
npx juhbdi uninstall --ide cursor      # Remove from an IDE

Supported: Claude Code, Cursor, Windsurf, Kilo Code, Kiro, Roo Code, Cline, OpenCode, GitHub Copilot, Codex CLI, Gemini CLI, Google Antigravity, Augment Code, CodeBuddy, Trae, QwenCoder, VS Code

Commands

| Command | Description | |---------|-------------| | /juhbdi:init | Initialize project — scans codebase, asks about goals, creates governance config | | /juhbdi:plan | Interactive planning — discovers intent, analyzes code, generates wave-based roadmap | | /juhbdi:execute | Governed execution loop with parallel worktrees, model routing, and auto-recovery | | /juhbdi:quick | Fast-track simple tasks (skips full planning, keeps governance) | | /juhbdi:status | Dashboard: progress, routing stats, cost intelligence, context health | | /juhbdi:cost | Cost analysis: per-task spend, savings vs always-opus, tier distribution | | /juhbdi:trail | Query the SHA-256 chained audit trail | | /juhbdi:audit | Verify decision trail integrity (tamper detection) | | /juhbdi:reflect | Extract learned principles from plan-vs-actual divergence | | /juhbdi:pause | Pause execution with full context handoff | | /juhbdi:resume | Resume from handoff in a new session | | /juhbdi:validate | Validate roadmap structure and intent alignment | | /juhbdi:activate | Inject JuhBDI activation into CLAUDE.md |

Dashboard — Cognitive Flow

Real-time visualization of the BDI agent model. Start with /juhbdi:dashboard or:

bun run src/dashboard/server.ts   # → http://localhost:3141

Overview — 3 BDI columns (Beliefs/Desires/Intentions) with live cards for trust, memory, state, roadmap, goals, spec, active wave, trail, and cost.

Focused Views — Click any card to drill down: Trust gauge with tier progression, Intelligence Memory (reflexions/traces/principles), Cost Intelligence with cumulative spend chart and model distribution donut, Decision Trail with type filters and search, Context health from live session bridge files.

Ambient Intelligence — File Hotspots (edit frequency), Test Pulse (pass/fail rate), Git Timeline, Session Activity summary, and a scrolling activity ticker in the footer.

Live Updates — SSE streaming with 5s broadcast cycles, debounced rendering, and data-fingerprint skip to prevent UI thrashing.

How It Works

The BDI Loop

JuhBDI implements a cognitive architecture where the AI maintains persistent Beliefs (what it knows about the project), Desires (what the user wants to achieve), and Intentions (the concrete plan to get there).

┌─────────────────────────────────────────────────────┐
│                    BDI Control Loop                 │
│                                                     │
│   Beliefs ──→ Desires ──→ Intentions ──→ Actions    │
│     ↑                                       │       │
│     └───────── observe outcomes ◄───────────┘       │
└─────────────────────────────────────────────────────┘

1. Intent Specification — You define goals, constraints, and tradeoff weights (quality ↔ speed ↔ security). JuhBDI challenges your request against these constraints through Socratic review.

2. Wave Planning — Tasks are decomposed into dependency-aware waves. Wave 1 is concrete; future work is a horizon sketch refined after each wave (receding-horizon planning).

3. Parallel Execution — Each task runs in an isolated git worktree with its own agent. Independent tasks execute simultaneously. Every file write passes through governance checks.

4. Recovery — Failed tasks get classified, diagnosed by a specialist agent, and retried with alternative strategies. Approaches that failed are banned from retries.

5. Learning — Successful patterns are stored in cross-linked memory (A-MEM). Future tasks get pre-loaded with relevant approaches, warnings, and principles.

Model Routing (5-Signal Algorithm)

Every task is routed to the cheapest model tier that will succeed:

| Signal | What It Does | |--------|-------------| | Override | Respects explicit tier locks from the user | | Failure escalation | Auto-bumps tier on retries | | Memory match | Learns "this type of task passed with haiku" | | Structural complexity | Multi-factor score: goal weight, verification type, scope, keywords | | Tradeoff bias | Quality-biased projects shift toward opus; speed-biased toward haiku |

Trust scoring modulates confidence — unreliable tiers get less weight. Difficulty estimation enriches routing context.

The Audit Trail

Every autonomous decision is logged to an append-only, SHA-256 chained trail:

{
  "event_type": "routing",
  "description": "Routed task t3 to haiku",
  "reasoning": "{\"recommended_tier\":\"haiku\",\"confidence\":0.85}",
  "timestamp": "2026-03-08T12:00:00.000Z",
  "hash": "a1b2c3...",
  "prev_hash": "d4e5f6..."
}

OpenClaw Integration

JuhBDI is available as an OpenClaw plugin that brings BDI governance to any OpenClaw agent, regardless of which LLM it runs on (Claude, GPT, Gemini, DeepSeek, etc.).

# Install via OpenClaw
openclaw plugins install @juhlabs/openclaw-bdi

# Or via npm
npm install @juhlabs/openclaw-bdi

What it gives your OpenClaw agents

| Tool | Purpose | |------|---------| | bdi_verify_intent | Challenge risky or vague actions before execution | | bdi_recall | Retrieve past experiences and learned principles | | bdi_log_decision | SHA-256 hash-chained audit trail for every decision | | bdi_reflect | Extract principles from plan-vs-actual divergence | | bdi_assess | Estimate task difficulty and check model trust scores |

Plus automatic hooks: governance rules injected before every prompt, audit trail + trust scoring updated after every agent run.

28 tests, 0 failures. Works with all 13,700+ OpenClaw skills. See openclaw-bdi/ for source.

Agents

| Agent | Role | |-------|------| | task-executor | Executes tasks in isolated worktrees with TDD verification | | diagnostician | Root-cause analysis on failures (no code access — pure analysis) | | strategist | Alternative approach generation from banned approaches + memory | | librarian | Compresses execution state, updates project beliefs | | belief-updater | Propagates wave outcomes into project state between waves |

Hooks

| Hook | Event | Purpose | |------|-------|---------| | statusline | Notification | Catppuccin Mocha gradient context display | | context-monitor | PostToolUse | 3-tier warnings + auto-handoff at critical context | | session-primer | SessionStart | Surfaces pending tasks and relevant memory | | auto-trigger | UserPromptSubmit | Suggests JuhBDI commands on natural language prompts |

Architecture

src/
├── auto-trigger/     # Rule-based command suggestion scoring
├── bench/            # Performance benchmarks + routing simulation
├── cli-utils/        # 25+ CLI wrappers (thin shells over core logic)
├── core/             # Config, trail, tradeoffs, patterns
├── cost/             # Token cost estimation + reporting
├── integration/      # End-to-end integration tests
├── memory/           # A-MEM, tool bank, TNR, principles, speculation
├── parallel/         # Execution progress tracking
├── repomap/          # PageRank graph, semantic edges, knowledge extraction
├── routing/          # Trust scoring, difficulty estimation
├── schemas/          # Zod v4 schemas (11 modules)
├── trail/            # Audit trail filtering + formatting
├── quick/            # Quick mode preflight, governance, recording
├── dashboard/        # Cognitive flow dashboard (SSE, 8 views)
├── governance/       # Compliance, autonomy certs, NIST RMF
└── statusline/       # Context bridge + gradient display

openclaw-bdi/         # OpenClaw governance plugin
├── src/core/         # Portable BDI algorithms (adapted from src/)
├── src/tools/        # 5 agent tools
├── src/hooks/        # Governance injection + audit hooks
└── tests/            # 28 tests

commands/             # 20 slash commands
agents/               # 5 agent system prompts
hooks/                # Hook configuration
site/                 # Landing page (juhlabs.com/juhbdi)
.claude-plugin/
├── plugin.json       # Plugin manifest
└── hooks/            # 4 event hooks (.cjs)

Benchmarks

| Metric | Value | |--------|-------| | Test suite | 1271 tests, 0 failures across 124 files | | Assertions | 2,892 expect() calls | | Auto-trigger latency | 0.01ms per evaluation | | Trust scoring | <0.001ms per update | | Routing savings | ~80% vs always-opus | | Competitive score | 39 capabilities implemented | | Unique to JuhBDI | 26 (zero competitors have them) | | Milestones completed | 18 |

Built by

Julian Hermstad — JuhLabs · LinkedIn · GitHub

License

MIT