BRHP is an OpenCode plugin for structured, persistent planning.
Instead of treating planning as a few disposable notes in a chat, BRHP gives planning its own state. You can start from a problem statement, build and revisit a planning session over time, and keep that session grounded in the instructions and constraints that matter for the current project.
BRHP is short for Boltzmann Recursive Hierarchical Planning. At a high level, it models planning as a graph of scopes, nodes, and validation signals rather than a flat checklist, so the system can keep track of what is still unresolved and whether a plan has actually converged.
BRHP is built for work that is too large, too uncertain, or too constrained to handle well with "just start coding."
It is meant to help you:
- turn a vague problem into an explicit planning session
- keep track of the active frontier of unresolved work
- validate whether the current plan is coherent enough to proceed
- resume planning later without losing the thread
- keep project-specific instructions in the loop while planning
Most AI-assisted development workflows are very good at moving fast. They are much less reliable at holding a careful plan in memory across multiple turns, especially when the work has dependencies, constraints, or policy-like requirements.
BRHP exists to make planning a first-class activity inside OpenCode. The goal is not only to generate a plan once, but to maintain an explicit planning state that can be inspected, constrained, resumed, and handed off with more confidence.
BRHP currently provides:
- a
/brhpslash command for inspecting, creating, and resuming planning sessions - a
/brhp historyview for deeper bounded recent planner history on the active session - a
/brhp inspectview for bounded graph, frontier, and validation drill-down on the active session - a TUI sidebar for the current planning state
- instruction loading from both user-level and project-level directories
- local persistence so planning sessions survive across turns and restarts
BRHP reads instructions from:
~/.config/opencode/brhp/instructions.opencode/brhp/instructions
A default instruction set is included in .opencode/brhp/instructions/planning-with-brhp.md that teaches the LLM how to use BRHP tools.
Planning sessions are stored locally at:
.opencode/brhp/brhp.db
Optional planner configuration can be set in:
.opencode/brhp/config.yaml
An example config is provided at .opencode/brhp/config.example.yaml. Currently supported: temperature (0.001–1.0) and maxDepth (1–10). Missing or invalid config degrades gracefully to defaults.
Requirements:
- OpenCode
v1.4.0+ - Node.js
20+
BRHP is not published on npm yet. Until it is, load it from a local checkout with OpenCode's path-like plugin spec support and a file:// package path.
Local checkout requirements:
pnpmbun
Build BRHP locally:
corepack enable
pnpm install
pnpm build
pnpm verify:packageThen add the local package path to your OpenCode runtime config.
opencode.json
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["file:///absolute/path/to/brhp"]
}Add the same local package path to your OpenCode TUI config.
tui.json
{
"plugin": ["file:///absolute/path/to/brhp"]
}Restart OpenCode after changing plugin config. Re-run pnpm build after local BRHP source changes.
After BRHP is published to npm, replace the file:// entries with "brhp" in both config files.
Common commands:
/brhpor/brhp statusto inspect the active planning session/brhp historyto inspect the newest 25 planner events for the active session/brhp inspectto inspect bounded graph, frontier, validation, node, edge, and activity detail for the active session/brhp plan <problem statement>to start a new planning session/brhp resume <session id>to resume an existing session
Planner tools (available to the LLM during BRHP planning):
| Tool | Purpose |
|---|---|
brhp_get_active_plan |
Read the authoritative active planning state. |
brhp_decompose_node |
Decompose a node into smaller child nodes. |
brhp_validate_active_scope |
Persist a validation verdict for the active scope. |
brhp_complete_leaf |
Mark a leaf node as complete with a result summary. |
Operator read surfaces are intentionally bounded:
| Surface | What it shows |
|---|---|
/brhp status |
Compact active-session summary, instruction inventory, skipped files, and stack-free diagnostics. |
/brhp history |
Newest 25 planner events for the active session. |
/brhp inspect |
Active graph/frontier/validation drill-down with bounded frontier selections, validation clauses, focus nodes, edges, and recent activity. |
| TUI sidebar | Compact read-only active-session summary. |
The exact Markdown output is for humans, not a machine-stable API. The stable contract is the command surface and the read-model concepts documented in Operator contract.
Example:
/brhp plan Design a safe rollout strategy for migrating our job system
The README is meant to explain the project at a high level. If you want the internal design and formal model, start here:
Install dependencies:
pnpm installValidate the project:
pnpm typecheck
pnpm test
pnpm build
pnpm verify:packagepnpm verify:package requires bun and npm on PATH. It uses Bun to run the verifier, npm pack to build the package artifact, and npm install inside a temporary project to smoke-test the installed package. It may need npm registry or cache access for dependency resolution.
If you are working on the local planner schema:
pnpm db:compile
pnpm db:vetBRHP is an early public release. The core planning model, OpenCode integration, and local persistence are in place, but the public surface is still intentionally small while the planning kernel hardens.
MIT. See LICENSE.