micode-beads

An OpenCode plugin that turns AI coding into a structured Brainstorm, Plan, Implement workflow. Ships 26 specialized agents, 12 lifecycle hooks, project-aware constraint enforcement via .mindmodel/, and browser-based interactive brainstorming.

Install

Use the installer script (recommended). It downloads a standalone binary when available, falling back to package managers automatically:

curl -fsSL https://raw.githubusercontent.com/flipch/micode-beads/main/scripts/install.sh | sh

Or install directly via a package manager (requires the Bun runtime):

bun add -g micode-beads
# or, if Bun is already on your PATH:
npm install -g micode-beads

After installing, verify your setup:

micode-beads doctor

Run micode-beads doctor --fix to auto-repair common issues (missing config, unregistered plugin, missing directories).

Quick Start

1. Add the plugin to your OpenCode configuration (~/.config/opencode/opencode.json):

   { "plugin": ["micode-beads"] }

2. Launch OpenCode in your project directory and run /init to scaffold project docs.

3. Describe your task and the commander agent takes over -- brainstorming designs, creating a plan, and implementing in parallel.

Usage

Workflow Overview

Brainstorm --> Plan --> Implement --> Verify

Brainstorm -- Explore ideas through collaborative questioning. Spawns research subagents in parallel. Optionally opens a browser-based interactive session (Octto). Produces a design document in thoughts/shared/designs/.

Plan -- Converts the design into a set of micro-tasks (2-5 min each) with exact file paths, dependencies, and TDD workflow. Outputs a plan to thoughts/shared/plans/.

Implement -- The executor orchestrates parallel implementer and reviewer agents across a git worktree. Each task follows test-first development, and completed work is verified against the plan.

Verify -- Cross-references the plan against actual implementation: completeness, test coverage, plan adherence, and passing tests. Failures produce actionable error messages.

CLI Commands

Command	Description
micode-beads init	Initialize project: create opencode.json, scaffold thoughts/ directories, run health checks
micode-beads init --mindmodel	Also scaffold .mindmodel/ constraint directory
micode-beads doctor	Diagnose installation and environment health (11 checks across CLI, plugin, OpenCode, and config)
micode-beads doctor --fix	Attempt to auto-fix failed checks (create config, register plugin, scaffold directories)
micode-beads doctor --json	Output diagnostic results as machine-readable JSON
micode-beads doctor --verbose	Show detailed information for each check

OpenCode Commands

Command	Description
/init	Scaffold project documentation (ARCHITECTURE.md, CODE_STYLE.md)
/mindmodel	Generate .mindmodel/ coding constraints from your codebase
/ledger	Create or update a continuity ledger for session state
/search	Full-text search across past plans, ledgers, and artifacts
/review-feedback	Ingest GitHub PR review comments and generate corrective fixes

AFK Mode

Run the entire workflow without human prompts. Useful for CI pipelines or overnight runs.

AFK mode is activated via any of (highest priority first):

1. Command argument: include --afk in your task message
2. Environment variable: MICODE_AFK=1
3. Config flag: "afk": true in micode-beads.json

Combine with --git-pr to automatically create a draft pull request when the workflow completes.

Stage Resumption

Resume a workflow from any previously completed stage without re-running earlier work:

• --resume-from=plan -- skip brainstorm, re-run plan and everything after it
• --correct "use JWT instead of sessions" -- provide a correction when resuming

Stage outputs are persisted to thoughts/workflow/ so they can be reloaded on resume. Each stage is versioned, letting you compare the original run against corrected runs.

Configuration

opencode.json

Set your default model and register the plugin:

{
  "model": "provider/model-name",
  "plugin": ["micode-beads"]
}

All agents inherit the default model unless overridden.

micode-beads.json

Create ~/.config/opencode/micode-beads.json for per-agent overrides and feature flags:

{
  "agents": {
    "brainstormer": { "model": "openai/gpt-4o", "temperature": 0.8 },
    "commander": { "maxTokens": 8192 }
  },
  "features": { "mindmodelInjection": true },
  "compactionThreshold": 0.5,
  "fragments": { "commander": ["custom-instructions.md"] },
  "researchDirs": ["docs"],
  "afk": false,
  "gitPr": { "draftByDefault": true }
}

Falls back to micode.json if micode-beads.json is not found.

Option	Type	Default	Description
agents	object	--	Per-agent overrides: model, temperature, maxTokens, reasoningEffort, effort, thinking
features.mindmodelInjection	boolean	false	Auto-inject .mindmodel/ patterns into every message
compactionThreshold	number	0.5	Context usage ratio (0-1) that triggers auto-compaction
fragments	object	--	Additional prompt fragment files per agent
researchDirs	string[]	["thoughts/shared/designs/"]	Directories scanned for existing research/design documents
afk	boolean	false	Enable autonomous mode by default
methodology	string	"default"	Development methodology profile ("default", "tdd") -- injects methodology-specific instructions into planner, executor, and implementer agents
gitPr.draftByDefault	boolean	true	Create PRs as drafts when using --git-pr

Model resolution order: per-agent override > opencode.json default model > plugin default.

Research Directories

The brainstormer and planner agents read existing documentation from configured directories. Point researchDirs at your project's docs folder to incorporate existing knowledge into the workflow. Missing or empty directories produce a warning, not an error.

Agents

Agent	Role
commander	Primary orchestrator -- classifies tasks, routes to specialists
brainstormer	Design exploration via research subagents and Octto browser UI
planner	Converts designs into parallel micro-task plans
executor	Batch-spawns implementers and reviewers, orchestrates the implement phase
implementer	Executes a single micro-task with test-first development
reviewer	Reviews a single task for correctness, completeness, and style
verifier	Post-implementation cross-reference against the plan
pr-feedback	Ingests GitHub PR review comments and generates fixes
bootstrapper	Bootstraps new project scaffolding
probe	Lightweight investigation agent
octto	Manages interactive brainstorming sessions
codebase-locator	Finds relevant files for a given task
codebase-analyzer	Deep structural analysis of code
pattern-finder	Discovers existing code patterns
project-initializer	Generates ARCHITECTURE.md and CODE_STYLE.md
ledger-creator	Creates and updates continuity ledgers
artifact-searcher	Full-text search over indexed artifacts
mm-orchestrator	Coordinates the mindmodel generation pipeline
mm-stack-detector	Detects tech stack and frameworks
mm-pattern-discoverer	Discovers coding patterns in the codebase
mm-example-extractor	Extracts representative code examples
mm-constraint-writer	Assembles .mindmodel/ constraint files
mm-constraint-reviewer	Reviews generated code against constraints
mm-dependency-mapper	Maps module dependencies
mm-convention-extractor	Extracts naming and style conventions
mm-domain-extractor	Identifies domain concepts
mm-code-clusterer	Clusters related code modules
mm-anti-pattern-detector	Flags anti-patterns in the codebase

Tools

Tool	Description
ast_grep_search	AST-aware code pattern search
ast_grep_replace	AST-aware code pattern replacement
look_at	Extract file structure overview
artifact_search	Full-text search across indexed artifacts
milestone_artifact_search	Search milestone-specific artifacts
btca_ask	Query library source code
mindmodel_lookup	Query .mindmodel/ patterns by keyword
spawn_agent	Spawn subagents in parallel
batch_read	Read multiple files in parallel
pty_spawn	Start a background terminal session
pty_write	Send input to a PTY session
pty_read	Read output from a PTY session
pty_list	List active PTY sessions
pty_kill	Terminate a PTY session
Octto tools	Create, await, and manage browser brainstorm sessions

Hooks

Hook	Trigger	Purpose
Fragment Injector	chat.params	Injects user-defined prompt fragments (highest priority)
Ledger Loader	chat.params	Injects continuity ledger into system prompt
Context Injector	chat.params + tool.execute.after	Loads project context files and directory READMEs
Context Window Monitor	chat.params	Warns at 70% and 85% context usage thresholds
Mindmodel Injector	chat.messages.transform + chat.system.transform	Auto-injects matching .mindmodel/ patterns (feature-flagged)
Auto-Compact	event	Summarizes session at configurable context threshold
Session Recovery	event	Recovers session state after interruptions
Token-Aware Truncation	tool.execute.after	Caps large tool outputs based on context limits
Comment Checker	tool.execute.after	Validates Edit tool output for placeholder comments
Artifact Auto-Index	tool.execute.after	Indexes artifacts written to thoughts/ into SQLite FTS5
File Ops Tracker	tool.execute.after	Records read/modified files for session ledger
Constraint Reviewer	tool.execute.after	Validates generated code against .mindmodel/ constraints

Development

git clone git@github.com:flipch/micode-beads.git && cd micode-beads
bun install

For contributors: The repo optionally uses Hermit to pin tool versions (Bun 1.3.8, Node 22.14.0) for local development. Activate it with source bin/activate-hermit or let the shell hooks do it automatically. Hermit is not required for end users of the plugin or CLI.

Point OpenCode at your local clone for development:

{ "plugin": ["~/path/to/micode-beads"] }

Build

bun run build

Test

bun test                   # all tests (~97 files, 580+ assertions)
bun run test:e2e           # end-to-end suite only (3 files)
bun run test:coverage      # generate lcov report in ./coverage
bun test --watch           # re-run on file changes

Lint and Format

bun run lint               # biome lint
bun run format             # biome format --write
bun run check              # biome check (lint + format)

Git Hooks (Lefthook)

Installed automatically via bun install. Two hooks run on every commit and push:

• pre-commit -- formats and lint-checks staged files via Biome
• pre-push -- runs tsc --noEmit to catch type errors before they reach CI

CI Pipeline

Every push and PR triggers the CI workflow which runs five quality gates in order: lint, format check, type check, build, and test with coverage. Coverage results are uploaded to Codecov.

Release

Releases are managed by release-please. Merge the release PR to cut a new version. The CI workflow publishes to npm via OIDC trusted publishing.

Demo

The demo/ directory contains a 100-agent stress test that builds a complete terminal-based snake game in parallel. Each agent is a Bun subprocess that receives a micro-task and generates code from canned mock LLM responses.

bun run demo               # from the project root

Reduce concurrency on resource-constrained machines:

cd demo && bun run orchestrator.ts --concurrency 25

See demo/README.md for full options, system requirements, and expected output.

Contributing

Contributions are welcome. Please open an issue to discuss significant changes before submitting a pull request. Run bun test and bun run lint before pushing.

Attribution

Forked from micode by vtemian.

License

MIT