A CLI tool to configure Claude Code or pi-code with BMO.
This repository includes code and Markdown content adapted from ALT-F4-LLC/dotfiles.vorpal.
- Original project:
https://github.com/ALT-F4-LLC/dotfiles.vorpal - Upstream license: Apache License 2.0
- Attribution details for this repository: see NOTICE
Substantial credit for the agent, skill, and workflow design belongs to the
dotfiles.vorpal maintainers and contributors. This repository contains
modifications and simplifications focused on a standalone Claude Code setup tool and a pi-code extension.
The code in this repository was written by Claude Code.
If you use pi-code, you can install the pi-bmo-agents extension instead of
running this CLI tool.
The full agentsuite, both orchestration skills, and a live board status widget:
pi install git:github.com/erewok/pi-bmo
pi install git:github.com/erewok/bmo-agent-setupSee docs/pi-extension.md for the full guide: installation, the dev-team workflow, per-agent reference, and troubleshooting.
bmo-agent-setup contains a BMO-powered agent team for claude-code or pi-code:
- agents/ — Five agent definition files (Markdown prompts consumed by Claude Code)
- skills/ — Two orchestration skills (
dev-teamanddocumentation-driver) - settings.json — Claude Code configuration
- statusline.sh — Status bar script for Claude Code
If you run the CLI, it dumps all related files into a local ./claude-code-env dir and then prints step-by-step instructions showing where to place each generated file so that Claude Code picks them up automatically.
The agent team is configured to use bmo for issue tracking.
Technical architect and code reviewer. Produces Technical Design Documents (TDDs) in docs/tdd/ for complex work, maintains project specifications in docs/spec/, and reviews all @senior-engineer implementation changes before they are considered complete. Never writes implementation code — outputs are design documents and review feedback only.
Plans and decomposes work into BMO issues. Explores the codebase, creates issue hierarchies with dependencies, attaches affected files to issues for collision detection, and runs bmo plan to verify the computed execution phase structure. The only agent that creates BMO issues. Never writes code.
Implements solutions from pre-planned BMO issues. Claims issues atomically with bmo issue claim, implements within the scoped files, then moves issues to review status when done. Does not close issues (closing requires @staff-engineer sign-off) and does not commit code unless explicitly instructed after review passes.
Verifies implementation against acceptance criteria after the review phase. Writes and runs tests, checks for regressions, and reports results and defects as BMO comments. Does not claim or close issues — communicates via comments only.
Produces UX design specs in docs/ux/ for user-facing work: UI, CLI commands, API ergonomics, error messages, config formats, and onboarding flows. Designs interaction flows and acceptance criteria before technical planning begins. Never writes implementation code.
Reviews implementation output for readability, clarity, and structural correctness. Evaluates naming, function size, single responsibility, module flow, nesting depth, magic values, misplaced code, duplication, and minimum-necessary code. Read-only — does not write, edit, or commit code. Does not review architecture, security, or operational concerns (those belong to @staff-engineer). Used as a feedback loop for @senior-engineer output before @staff-engineer review.
| Skill | Description |
|---|---|
| dev-team | Coordinates all five agents for planning and executing development work |
| documentation-driver | Bootstraps docs/spec/ project specifications for new repositories |
The agent team uses the bmo CLI for issue tracking. Each agent references bmo commands in its system prompt. When you invoke the dev-team skill or any individual agent, they manage work through bmo.
Issues flow through a defined lifecycle enforced by the agent roles:
todo → in-progress (senior-engineer claims) → review (senior-engineer when done) → done (orchestrator after staff-engineer sign-off)
| Agent | claim | move to review | close | comment |
|---|---|---|---|---|
| senior-engineer | ✅ only agent that claims | ✅ when done | ❌ | ✅ |
| qa-engineer | ❌ | ❌ | ❌ | ✅ only |
| staff-engineer | ❌ | ❌ | ❌ | ✅ |
| project-manager | ❌ | ❌ | ❌ | ✅ |
| orchestrator (dev-team) | ❌ | ❌ | ✅ after review | ❌ |
- Rust toolchain (stable, 1.70+)
- macOS or Linux
Basic setup (uses the built-in default posture, no customization):
cargo run --releaseWith statusline:
cargo run --release -- --with-statusline=trueUsing one of the other built-in presets:
cargo run --release -- --config bmo-config.hardened.toml
cargo run --release -- --config bmo-config.yolo-mode.tomlSee CONFIG.md for detailed configuration documentation.
# Build
cargo build --release
# Run with the built-in default posture
cargo run --release
# Run with custom output directory
cargo run --release -- --output ~/my-claude-env
# Run with one of the other built-in presets
cargo run --release -- --config bmo-config.hardened.toml
# Run with CLI overrides
cargo run --release -- --config bmo-config.hardened.toml --with-thinking=false
# Or with justfile
just run
just run ~/my-claude-env| Flag | Description | Default |
|---|---|---|
-o, --output <PATH> |
Output directory for the generated environment | ./claude-code-env |
-c, --config <FILE> |
Path to TOML configuration file | Built-in bmo-config.default.toml |
--with-statusline <BOOL> |
Enable/disable statusline (overrides config) | From config |
--with-thinking <BOOL> |
Enable/disable always-thinking mode (overrides config) | From config |
-h, --help |
Print help | |
-V, --version |
Print version |
Three presets are included — see CONFIG.md for what each one actually allows/asks/denies:
bmo-config.default.toml- Balanced default, used automatically when no--configis given. Also the fully-documented reference for every option this tool supports.bmo-config.yolo-mode.toml- Skips nearly all permission prompts. Only use in a disposable environment.bmo-config.hardened.toml- Reads unrestricted, writes scoped to the current directory, sandboxed, everything else asks or is denied.
For complete configuration documentation, see CONFIG.md.
After the tool runs, copy the generated files into ~/.claude/:
# Agent definitions
cp -r ~/my-claude-env/agents ~/.claude/
# Skills
cp -r ~/my-claude-env/skills ~/.claude/
# Settings
cp ~/my-claude-env/claude.settings.json ~/.claude/settings.json
# Statusline script
cp ~/my-claude-env/statusline.sh ~/.claude/statusline.shOr install everything at once:
cp -r ~/my-claude-env/{agents,skills} ~/.claude/ && \
cp ~/my-claude-env/claude.settings.json ~/.claude/settings.json && \
cp ~/my-claude-env/statusline.sh ~/.claude/statusline.sh~/.claude/
├── agents/
│ ├── code-quality.md
│ ├── distributed-systems-engineer.md
│ ├── project-manager.md
│ ├── qa-engineer.md
│ ├── senior-engineer.md
│ ├── staff-engineer.md
│ └── ux-designer.md
├── skills/
│ ├── documentation-driver/
│ │ └── SKILL.md
│ └── dev-team/
│ └── SKILL.md
├── settings.json
└── statusline.sh
- docs/pi-extension.md — Pi-code integration: install, usage, agent reference
- CONFIG.md — Claude Code CLI tool configuration reference
- GOALS.md — Pi extension goals and architecture
just build # debug build
just test # run tests
just lint # clippy
just fmt # format
just ci # full CI pipeline locallyContributor: Erik Aker eraker@gmail.com GitHub: https://github.com/erewok/bmo-agent-setup
This project is licensed under the Apache License 2.0.
Additional third-party attribution and adaptation notes are documented in NOTICE.