Search BrigadeStack

Search BrigadeStack pages and docs.

BrigadeStack
Menu
Docs menu

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.

receiptbrigadestack doctor · exit 1
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 manual

Review 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.

receiptbrigadestack status · exit 0ok
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 sync

When 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