Tool catalog

brigade tools describes local callable tools, slash commands, skills, superpowers, scripts, and MCP configs across agent harnesses. It inspects local files, reports health, can explicitly write reviewed harness projection files, and can explicitly supervise local runtimes for approved script calls. It does not start MCP servers, auto-sync harness configs, fetch schemas, store auth, install schedulers, or auto-start runtimes.

The local config is gitignored:

.brigade/tools.toml

Create it with:

brigade tools init

Commands

brigade tools list
brigade tools list --json
brigade tools show simplify
brigade tools search simplify
brigade tools describe simplify
brigade tools contracts
brigade tools call plan simplify --args '{"path":"README.md"}'
brigade tools call plan simplify --args-json args.json
brigade tools call queue simplify --args '{"path":"README.md"}'
brigade tools call queue simplify --args-json args.json
brigade tools call list
brigade tools call show <call-id>
brigade tools call approve <call-id>
brigade tools call reject <call-id> --reason "not needed"
brigade tools call hold <call-id> --reason "needs review"
brigade tools call run <call-id>
brigade tools call run --next
brigade tools run list
brigade tools run show <run-id>
brigade tools run latest
brigade tools run replay <run-id>
brigade tools checkpoint list
brigade tools checkpoint show <checkpoint-id>
brigade tools checkpoint approve <checkpoint-id> --choice continue
brigade tools checkpoint reject <checkpoint-id> --reason "not safe"
brigade tools checkpoint resume <checkpoint-id>
brigade tools runtime init
brigade tools runtime list
brigade tools runtime show <runtime-id>
brigade tools runtime status
brigade tools runtime start <runtime-id>
brigade tools runtime stop <runtime-id>
brigade tools runtime restart <runtime-id>
brigade tools runtime doctor
brigade tools policy init
brigade tools policy show
brigade tools policy doctor
brigade tools plan
brigade tools plan simplify
brigade tools apply simplify --dry-run
brigade tools apply simplify
brigade tools apply --all
brigade tools doctor
brigade tools doctor --json
brigade tools import-issues

list, show, and search inspect configured entries. describe and contracts inspect schema-backed call contracts. call plan validates arguments and returns a safe call plan without executing anything. call queue stores a plan for local review, and call approve, reject, and hold update review status only. call run explicitly executes approved script calls and writes local receipts. run list, show, and latest inspect receipts, and run replay queues a pending replay candidate without executing it. checkpoint commands review and explicitly resume local pause records. runtime commands explicitly manage local runtimes. policy commands inspect host-local execution gates and env label bindings. plan previews projection writes without touching files. apply is the only command that writes projections, and it requires either one tool id or --all. doctor reports catalog health issues. import-issues writes those issues into the normal work import inbox as tool-catalog task imports with stable source fingerprints.

Config Shape

Each logical tool is a TOML table:

[[tool]]
id = "simplify"
name = "Simplify"
family = "slash-command"
enabled = true
description = "Portable simplify command."
source_path = "tools/simplify.md"
manifest_path = "tools/simplify.manifest.json"
schema_path = "tools/simplify.schema.json"
command = "brigade tools show simplify"
auth_label = "local-user"
timeout = 30
input_schema_path = "tools/simplify.input.schema.json"
output_schema_path = "tools/simplify.output.schema.json"
examples_path = "tools/simplify.examples.json"
permissions = ["read-files"]
effects = ["local-read"]
approval_mode = "on-request"
cwd = "."
env_labels = ["SAFE_ENV"]
argument_template = { path = "{path}", mode = "--mode={mode}" }
runtime_id = "local-helper"
requires_runtime = false
runtime_health_path = ".brigade/tools/runtime/local-helper.json"
supported_harnesses = ["claude", "codex", "opencode"]
projections = { claude = ".claude/commands/simplify.md", codex = ".codex/skills/simplify/SKILL.md" }
health_path = ".brigade/tools/simplify-health.json"
fingerprint = "source-fingerprint"

Fields:

Supported harness labels are local conventions. Brigade recognizes Claude Code, Codex, OpenCode, Hermes, OpenClaw, MCP, and scripts through the labels claude, codex, opencode, hermes, openclaw, mcp, and scripts.

Runtime Supervisor

Runtimes are explicit local processes that approved script calls can depend on. They are configured in a gitignored file:

.brigade/tools/runtimes.toml

Create a starter config with:

brigade tools runtime init

Each runtime is a TOML table:

[[runtime]]
id = "local-helper"
name = "Local Helper"
enabled = true
command = "python3 -m http.server 8765"
cwd = "."
port = 8765
health_command = "python3 --version"
health_path = ".brigade/tools/runtime/local-helper.json"
pid_path = ".brigade/tools/runtime/local-helper.pid"
log_path = ".brigade/tools/runtime/local-helper.log"
timeout = 10

Runtime commands are local and explicit:

Brigade refuses high-risk runtime command shapes, detects already-running runtimes, detects stale PID files, and warns when configured ports are already in use. doctor, brief, and work run never start runtimes automatically.

When a tool has requires_runtime = true, brigade tools call run refuses execution unless the configured runtime exists, is running, is managed by Brigade metadata, and passes health checks. Receipts include the runtime id and runtime snapshot used for the run.

Execution Policy

Execution policy is host-local and gitignored:

.brigade/tools/policy.toml

Create a starter policy with:

brigade tools policy init

The policy shape is:

allowed_families = ["script"]
allowed_effects = ["local-read", "local-write"]
denied_effects = ["remote-mutation", "secret-read"]
required_approval_modes = ["on-request", "always"]
max_timeout = 60
allowed_runtimes = ["local-helper"]
env_bindings = { SAFE_ENV = "SAFE_ENV" }

Policy fields:

When a policy file exists, brigade tools call plan and brigade tools call run report policy blockers for denied effects, effects outside the allow-list, disallowed families, missing env bindings, missing process env values, timeout caps, disallowed runtimes, and approval-mode mismatches. A missing policy is a health issue for executable contract-backed tools, but it does not break older read-only catalog workflows.

For env bindings, Brigade reads the current process environment at execution time and passes values to the script under the configured label name. It never stores env values in .brigade/tools/calls.jsonl, receipts, logs, docs, or work imports. Receipts include the policy decision and env labels used, with values redacted.

brigade tools policy doctor checks the policy file directly. brigade tools doctor, brigade work brief, and brigade tools import-issues also surface missing policy, missing env labels, denied effects, timeout caps, approval-mode blockers, and runtime/policy mismatches.

Projection Planning And Apply

brigade tools plan expands configured supported_harnesses and projections into exact projection actions. Each projection reports:

Projection statuses are:

brigade tools apply <tool-id> and brigade tools apply --all write only create and update actions. --dry-run reports writes without touching files. --force is required to overwrite unmanaged files or managed projections with local edits. doctor, brief, work run, and import-issues never apply projections automatically.

Managed projection files start with a Brigade metadata header containing:

For slash-command, skill, and superpower entries, Brigade writes the source content behind that metadata header. For script entries, Brigade writes a safe reference projection with the command label and source excerpt. For mcp entries, Brigade writes a documentation stub only. It does not write runtime MCP server configs.

Contracts And Call Planning

Contracts let wrappers understand how a portable tool should be called without invoking it. Brigade supports a practical local subset of JSON Schema:

Unsupported schema keywords are reported as contract health issues. brigade tools call plan accepts inline JSON with --args or a file with --args-json, validates it against input_schema_path, renders argument_template, and returns a redacted plan with:

Call planning is read-only. It does not invoke the command, start daemons, start MCP servers, resolve approvals, fetch remote schemas, or store auth.

Call Approval Queue

brigade tools call queue stores planned calls in:

.brigade/tools/calls.jsonl

Each queued call stores:

Equivalent valid plans dedupe while pending or approved. Rejected calls can be requeued only when args or the contract fingerprint changes. Blocked plans require --include-blocked to enter the queue, and blocked calls cannot be approved. Approval never executes a tool.

brigade tools doctor warns on stale pending approvals, approved calls whose contract or source fingerprint has gone stale, blocked queued calls, and held or rejected calls. brigade work brief shows pending approval count and the highest-priority call approval issue. brigade tools import-issues routes call approval health problems into tool-catalog imports.

Call Execution Receipts

brigade tools call run <call-id> executes exactly one approved call. brigade tools call run --next runs the oldest approved call. Execution is intentionally narrow:

For script calls, Brigade parses the configured command, appends rendered argument_template values in stable key order, uses the configured cwd when present, and applies the configured timeout. It does not resolve auth, fetch secrets, start MCP servers, run OpenAPI or GraphQL calls, or execute unapproved queue entries.

For MCP calls, Brigade requires an approved mcp family call with runtime_id, mcp_tool_name, input_schema_path, timeout, permissions, effects, and approval mode. The configured runtime must already be running, managed by Brigade metadata, healthy, and allowed by policy. Brigade then runs the configured local stdio command with shell=False, sends JSON-RPC initialize, tools/list, and tools/call, validates that the requested MCP tool is listed, and records the redacted request and response in the receipt. It does not connect to remote MCP servers or start runtimes automatically.

Each run writes a receipt and raw local logs under:

.brigade/tools/runs/

Receipts include call id, tool id, family, status, timestamps, duration, exit code, timeout status, command label, cwd, redacted args and rendered arguments, redacted stdout/stderr summaries, stdout/stderr log paths, contract/source/call/approval fingerprints, approval metadata, permissions, effects, runtime snapshot, policy decision, env labels used, and projection summary. MCP receipts also include server id, tool name, request id, redacted request payload, redacted response summary, and MCP response count. Raw stdout and stderr logs stay local and gitignored.

Run History And Replay

Run history commands read only from .brigade/tools/runs/:

Replay never executes the command directly and never marks the replay call approved. Operators or wrappers must review and approve the new call through the normal approval queue, then run it with brigade tools call run. Replay uses only the redacted receipt args, so secret env values and secret-looking argument values are not recovered from logs or receipts.

brigade tools doctor warns on failed or timed-out runs, malformed receipts, missing stdout/stderr log files, and replay candidates blocked by stale tool, runtime, or policy state. brigade work brief surfaces the highest-priority run-history issue, and brigade tools import-issues routes run-history problems into tool-catalog imports.

Execution Checkpoints

Approved script tools can request an operator checkpoint by writing a JSON file under the directory in BRIGADE_TOOL_CHECKPOINT_DIR. Brigade also passes BRIGADE_TOOL_CALL_ID and BRIGADE_TOOL_RUN_ID to the script so checkpoint writers can include the current call and run id.

Checkpoint JSON supports:

When a run writes a checkpoint, Brigade normalizes the file into .brigade/tools/checkpoints/, marks the call waiting, and writes a waiting receipt linked to the checkpoint. brigade tools checkpoint approve <checkpoint-id> --choice <choice> marks the checkpoint approved and moves the call to resume-pending. brigade tools checkpoint resume <checkpoint-id> then revalidates the call, contract, source, projection, runtime, and policy state before executing. Resume receipts include the original call id, original run id, checkpoint id, resume run id, selected choice, and checkpoint approval metadata.

Checkpoint approval does not execute anything. Checkpoint resume never runs automatically from doctor, brief, work run, or call run. Brigade redacts checkpoint context and does not store process env values in checkpoints, receipts, logs, imports, or docs.

brigade tools doctor warns on stale, expired, rejected, blocked, and failed checkpoints. brigade work brief surfaces the highest-priority checkpoint issue, and brigade tools import-issues routes checkpoint problems into tool-catalog imports.

Health Checks

brigade tools doctor reports:

MCP discovery is structural. Brigade summarizes server count and server ids, checks for missing commands and timeout metadata, and flags broad shell-like command shapes. MCP execution is explicit, local-runtime-only, and limited to approved calls through brigade tools call run.

Work Inbox Routing

brigade tools import-issues creates local work imports with:

Repeated imports dedupe equivalent pending or promoted issues. Dismissed tool-catalog imports stay dismissed until the issue fingerprint changes.

Privacy Boundary

Keep all catalog state local and gitignored. Do not put tokens, passwords, raw credentials, URLs with embedded secrets, private hostnames, or host-private paths in public templates. Brigade reports unsafe field names without copying their values into command output, work imports, session artifacts, docs, or handoffs.

Projection apply is local and explicit. Call planning, call approval review, run history inspection, and checkpoint review are local and non-executing. Tool execution is explicit through brigade tools call run, limited to approved local script entries and approved local mcp entries with already-running managed runtimes, and recorded with local receipts. Replay creates a pending call and never bypasses approval, runtime, or policy gates. Checkpoint resume is explicit and never automatic. Runtime lifecycle is explicit through brigade tools runtime; no command auto-starts runtimes as a side effect. Execution policy is host-local and gitignored. Brigade does not store secrets, connect to remote MCP servers, run OpenAPI or GraphQL calls, install schedulers, fetch remote schemas, store auth, send notifications, or mutate remote services.