Docs / Reference
init, doctor, status
Install a workspace and verify the wiring.
Use this to set up a repo or workspace, and to check afterward that your agent tools are wired correctly.
init
Run brigadestack init --target <dir> for the interactive picker:
brigadestack init --target ~/agent-workspace
A non-interactive shell needs the flags instead: bare brigadestack init exits 2 with error: brigade init needs a TTY for the interactive prompt. Pass --depth and --harnesses for scripting. The CLI names itself brigade in its messages under either command name.
For CI or scripts, pass flags directly:
brigadestack init --target ~/agent-workspace --depth workspace --harnesses claude,codex,openclaw
brigadestack init --target ./repo --depth repo --harnesses codex
brigadestack init --target ./repo --harnesses none # generic install
Add --dry-run to preview the full file-by-file list without writing anything. Files that already exist are listed with (exists; kept), so nothing is implied to be overwritten.
The workspace config directory is .brigade.
brigade --help opens with a short start-here block and lists commands in five groups: the core memory loop, the daily operator loop, components and tools, review/security/research, and wiring and advanced. Every command stays listed. The grouping just replaces the flat dump.
doctor
brigadestack doctor verifies the wiring. It checks installed bootstrap files against hard byte budgets so overgrown files fail before agents load truncated context. It folds installed managed tools into its report and surfaces each tool’s own health. A missing optional tool is not a failure. Missing optional managed tools collapse into one non-failing summary line telling you to run brigadestack add <component>, instead of a per-tool wall.
brigadestack doctor
Add --json to emit the machine-readable report instead of text, --target/-t <dir> to point at another install, and --harness {generic,openclaw,hermes} to run a specific harness’s checks.
This abbreviated output was captured with v0.31.0 in an isolated generic fixture after removing AGENTS.md. Counts vary by installation.
brigade doctor: target <fixture>
harnesses: (none) (owner=this-repo, depth=workspace)
scope: target workspace only (pass --operator for host-global checks)
triage: 49 checks, 38 ok, 7 warn, 1 failed, 0 manual, 3 info
failures:
[fail] bootstrap: AGENTS.md target=<fixture>: missing at <fixture>/AGENTS.md
warnings:
[warn] bootstrap: CLAUDE.md target=<fixture>: not present at <fixture>/CLAUDE.md
[warn] outcome loop: dormant target=<fixture>: wired but no verify run ever captured; run `brigade work verify run --target . --command "<test>" --capture <skill-or-card-id>`
[warn] security: config target=<fixture>: missing at <fixture>/.brigade/security.toml; run `brigade security init --target .`
showing 8 actionable checks; run `brigade doctor --full` to show all checks
summary: 49 checks, 1 failed, 0 manualReview every [warn] to decide whether it needs action. [fail] means the install is incomplete. The openclaw and hermes agent tools add their own checks on top.
status
Once installed, brigadestack status reports over the component registry as a per-component table.
brigadestack status
Add --json to emit the machine-readable report instead of text, and --target/-t <dir> to point at another install.
The component rows below come from a v0.31.0 capture. The work mode: strict line uses the 0.32.0 beta mode name. 0.31.0 prints engineer for the same mode.
brigade status: /home/you/agent-workspace
work mode: strict; safety rails: on
core [ok] 16 ok, 1 warn, 0 fail - workspace bootstrap and harness adapters
memory [ok] 15 ok, 2 warn, 0 fail - handoff inbox, ingest, and memory-care
guard [ok] 2 ok, 0 warn, 0 fail - publish safety and content scrub
tokens [empty] 0 ok, 0 warn, 0 fail - output compaction
search [empty] 0 ok, 0 warn, 0 fail - local semantic code search
security [ok] 2 ok, 3 warn, 0 fail - agent workspace security scanning
pantry [empty] 0 ok, 0 warn, 0 fail - agent session auth sync
notifications [empty] 0 ok, 0 warn, 0 fail - operator notification wiring
evidence [empty] 0 ok, 0 warn, 0 fail - local-first evidence ledger and source exporters
mcp [empty] 0 ok, 0 warn, 0 fail - canonical MCP server config syncWhen setup misbehaves: bug diagnose and bug report
Two commands help when a wiring problem is not obvious from doctor.
brigadestack bug diagnose compares a selected project’s configuration against one agent tool without running it. --harness and --summary are required. --component mcp compares the project’s MCP catalog with that agent tool’s configuration. --component instructions diagnoses project-only Codex instruction loading, such as which AGENTS.md files Codex would select, and models the selection without reading file bodies. Add --json for machine-readable output. --save-finding <new-path> exports the finding locally, and --prepare-report prepares a local report for bug report.
brigadestack bug diagnose --harness codex --summary "MCP server missing in Codex"
brigadestack bug diagnose --component instructions --harness codex --summary "AGENTS.md not picked up" --assume-codex-defaults
brigadestack bug report collects a redacted diagnostics bundle and previews it before anything is shared. --dry-run saves and previews locally with no network calls. Submitting needs --report-id <id> from a saved preview plus --yes once you have approved the complete preview. --kind is bug, feedback, or security, and --via picks auto, gh, url, email, or file. --summary or --summary-file describes what happened and what you expected, and --include-output <file> adds a redacted 200-line tail of a file you choose.
brigadestack bug report --title "Doctor fails after init" --summary "Expected a clean doctor." --dry-run
Running without the backend
A local install with no backend routes handoffs into a single workspace on that machine, and init picks that workspace automatically. To choose a different one, pass --owner to brigadestack init, brigadestack operator quickstart or brigadestack reconfigure. On init the value must be this-repo or one of the names you gave to --harnesses. The receipt commands brigadestack handoff receipt plan and brigadestack handoff receipt record also take --owner, as a label for the workspace the receipt belongs to. The output of init and quickstart names the chosen workspace on a line that starts brigade: memory owner ->.
brigadestack init --target ./repo --depth repo --harnesses claude,codex --owner claude