Docs / Reference
Tool catalog
Catalog the tools your agents can call, review each call before it runs, and set the policy that governs them.
brigadestack tools keeps one catalog of the callable tools, slash commands, skills, superpowers, scripts, and MCP configs your agent tools use. It inspects local files, reports health, writes projection files for each agent tool, and supervises local runtimes for approved script and MCP calls. It does not connect to remote MCP servers, fetch schemas, store auth, or install schedulers. An approved MCP call runs the configured local stdio command for that one call. (Runtime MCP server configs are managed by brigadestack mcp.)
The local config is gitignored:
.brigade/tools.toml
Create it with:
brigadestack tools init
brigadestack tools defaults merges BrigadeStack’s built-in portable tools (simplify, superpowers, frontend, antislop) into an existing catalog.
Commands
brigadestack tools defaults
brigadestack tools list
brigadestack tools list --json
brigadestack tools show simplify
brigadestack tools search simplify
brigadestack tools describe simplify
brigadestack tools contracts
brigadestack tools call plan simplify --args '{"path":"README.md"}'
brigadestack tools call plan simplify --args-json args.json
brigadestack tools call queue simplify --args '{"path":"README.md"}'
brigadestack tools call queue simplify --args-json args.json
brigadestack tools call list
brigadestack tools call show <call-id>
brigadestack tools call approve <call-id>
brigadestack tools call reject <call-id> --reason "not needed"
brigadestack tools call hold <call-id> --reason "needs review"
brigadestack tools call run <call-id>
brigadestack tools call run --next
brigadestack tools run list
brigadestack tools run show <run-id>
brigadestack tools run latest
brigadestack tools run replay <run-id>
brigadestack tools checkpoint list
brigadestack tools checkpoint show <checkpoint-id>
brigadestack tools checkpoint approve <checkpoint-id> --choice continue
brigadestack tools checkpoint reject <checkpoint-id> --reason "not safe"
brigadestack tools checkpoint resume <checkpoint-id>
brigadestack tools runtime init
brigadestack tools runtime list
brigadestack tools runtime show <runtime-id>
brigadestack tools runtime status
brigadestack tools runtime start <runtime-id>
brigadestack tools runtime stop <runtime-id>
brigadestack tools runtime restart <runtime-id>
brigadestack tools runtime doctor
brigadestack tools policy init
brigadestack tools policy show
brigadestack tools policy doctor
brigadestack tools plan
brigadestack tools plan simplify
brigadestack tools apply simplify --dry-run
brigadestack tools apply simplify
brigadestack tools apply --all
brigadestack tools sync plan
brigadestack tools sync apply
brigadestack tools parity status
brigadestack tools parity closeout
brigadestack tools pack build
brigadestack tools pack list
brigadestack tools pack show <pack-id>
brigadestack tools pack import <pack-id>
brigadestack tools pack archive <pack-id>
brigadestack tools doctor
brigadestack tools doctor --json
brigadestack tools import-issues
defaults merges BrigadeStack’s built-in portable tools into the local catalog. 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 executes approved script and MCP 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 resume local pause records. runtime commands manage local runtimes. policy commands inspect host-local execution gates and env label bindings. plan previews projection writes without touching files. apply writes projections and requires either one tool id or --all. sync plan and sync apply plan and apply a reviewed projection sync. parity status and parity closeout inspect and close out projection parity issues. pack builds and inspects local portable tool packs. 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 = "brigadestack 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:
id: stable logical tool id.name: display name.family: one ofskill,slash-command,superpower,mcp,openapi,graphql,script, orcustom.enabled: true or false.description: safe short description for humans and wrappers.source_path: local source file for the portable entry.manifest_path: optional local manifest path.schema_path: optional local JSON schema or tool schema path.command: optional command label. Required forscriptandcustomentries.auth_label: safe label only, such aslocal-userorgithub-readonly.timeout: expected timeout in seconds.input_schema_path: optional JSON Schema path for call arguments. Required forcall plan.output_schema_path: optional JSON Schema path for wrapper output expectations.examples_path: optional local examples file.permissions: safe labels for needed capabilities.effects: safe labels for expected effects such aslocal-read.approval_mode:never,on-request, oralways.cwd: optional local working directory label or relative path.env_labels: safe environment labels only, never values.argument_template: table of call-plan argument names to template strings such as{path}.runtime_id: optional id of a local runtime from.brigade/tools/runtimes.toml.requires_runtime: true whencall runmust refuse execution unless that runtime is running and healthy.runtime_health_path: optional local runtime health file label or path.supported_harnesses: configured agent tools that should have projections.projections: per-agent-tool projection target paths.health_path: optional local health summary file used for stale-health checks.fingerprint: optional source fingerprint when the source file is generated elsewhere.
Supported agent tool labels are local conventions. BrigadeStack recognizes an extensible set of agent tool labels: claude, codex, opencode, antigravity, pi, cursor, aider, goose, continue, copilot, qwen, kimi, adal, openhands, grok, amp, crush, hermes, openclaw, mcp, and scripts. The supported_harnesses block in brigadestack tools init output is the source of truth.
Runtime Supervisor
Runtimes are local processes that approved script and MCP calls can depend on. They are configured in a gitignored file:
.brigade/tools/runtimes.toml
Create a starter config with:
brigadestack 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:
brigadestack tools runtime listandshow <runtime-id>inspect config and current process state.brigadestack tools runtime statusreports running, stopped, and stale runtime states.brigadestack tools runtime start <runtime-id>starts one runtime withshell=False, writes PID metadata, and writes stdout/stderr logs under.brigade/tools/runtime/.brigadestack tools runtime stop <runtime-id>stops only a process with matching BrigadeStack runtime metadata.brigadestack tools runtime restart <runtime-id>stops then starts the same runtime.brigadestack tools runtime doctorreports stale PID files, port conflicts, missing cwd, high-risk commands, failed health checks, and missing runtime config.
BrigadeStack 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 do not start runtimes.
When a tool has requires_runtime = true, brigadestack 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:
brigadestack 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:
allowed_families: optional allow-list for tool families that can run.allowed_effects: optional allow-list for effect labels.denied_effects: effect labels that always block planning and execution.required_approval_modes: allowed approval modes for executable calls.max_timeout: maximum allowed call timeout in seconds.allowed_runtimes: optional allow-list for runtime ids.env_bindings: maps safe env labels from tool config to process environment variable names.
When a policy file exists, brigadestack tools call plan and brigadestack 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, BrigadeStack 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.
brigadestack tools policy doctor checks the policy file directly. brigadestack tools doctor, brigadestack work brief, and brigadestack 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
brigadestack tools plan expands configured supported_harnesses and projections into exact projection actions. Each projection reports:
- logical tool id
- source family
- harness
- source path
- projection path
- source fingerprint
- expected projection fingerprint
- status
- action
Projection statuses are:
missing: target file is absent and can be createdcurrent: managed projection matches the current sourcestale: managed projection is safe to update from changed source or changed renderer outputunmanaged: target exists without BrigadeStack projection metadataconflicted: managed target has local editsmissing_source: source file cannot be read
brigadestack tools apply <tool-id> and brigadestack 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 do not apply projections.
brigadestack tools sync plan plans a reviewed projection sync without writing, and brigadestack tools sync apply applies a reviewed projection sync. brigadestack tools parity status shows projection parity closeout state, and brigadestack tools parity closeout closes out current projection parity issues.
Managed projection files start with a Brigade metadata header containing:
- logical tool id
- source family
- harness
- source fingerprint
- projection fingerprint
- generated-at timestamp
For slash-command, skill, and superpower entries, BrigadeStack writes the source content behind that metadata header. For script entries, BrigadeStack writes a safe reference projection with the command label and source excerpt. For mcp entries in the tool catalog, BrigadeStack writes a documentation stub only. Runtime MCP server configs are written by the separate brigadestack mcp subsystem.
Portable Tool Packs
brigadestack tools pack builds and inspects local portable tool packs:
brigadestack tools pack buildbuilds a local portable tool pack from the catalog.brigadestack tools pack listlists local portable tool packs.brigadestack tools pack show <pack-id>shows one local portable tool pack.brigadestack tools pack import <pack>imports catalog entries and source files from a portable tool pack directory containingtool-pack.json.brigadestack tools pack archive <pack-id>archives one local portable tool pack.
Contracts And Call Planning
Contracts let wrappers understand how a portable tool should be called without invoking it. BrigadeStack supports a practical local subset of JSON Schema:
- root object schemas
required- scalar types:
string,number,integer,boolean, andnull - arrays with
items - enums
- boolean
additionalProperties
Unsupported schema keywords are reported as contract health issues. brigadestack 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:
- tool id, family, command label, cwd, timeout, auth label, and env labels
- rendered argument mapping
- permissions and effects
- approval mode and approval requirement
- blockers for invalid args, missing schemas, missing commands, unsafe labels, and conflicted or unmanaged projections
Call planning does not invoke the command, start daemons, start MCP servers, resolve approvals, fetch remote schemas, or store auth.
Call Approval Queue
brigadestack tools call queue stores planned calls in:
.brigade/tools/calls.jsonl
Each queued call stores:
- status:
pending,approved,rejected, orheld - redacted args and rendered argument mapping
- contract metadata, approval mode, permissions, and effects
- blockers from call planning
- projection summary
- source and contract fingerprints
- created and reviewed timestamps
- review reason when rejected or held
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.
brigadestack 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. brigadestack work brief shows pending approval count and the highest-priority call approval issue. brigadestack tools import-issues routes call approval health problems into tool-catalog imports.
Call Execution Receipts
brigadestack tools call run <call-id> executes exactly one approved call. brigadestack tools call run --next runs the oldest approved call. Execution is intentionally narrow:
- only
scriptandmcpfamily calls run - the call must be
approved - blockers must be empty
- approval, args, contract, source, and projection fingerprints must still match
- completed calls cannot be run again
- commands run with
shell=False
For script calls, BrigadeStack 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, run OpenAPI or GraphQL calls, or execute unapproved queue entries.
For MCP calls, BrigadeStack 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. BrigadeStack 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. This starts the local stdio command for that call, but it does not connect to remote MCP servers or start the runtime for you.
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/:
brigadestack tools run listsummarizes receipts by status.brigadestack tools run show <run-id>shows one receipt by id or unique prefix.brigadestack tools run latestshows the newest receipt.brigadestack tools run replay <run-id>creates a new pending call from the receipt’s redacted args after revalidating the current tool contract, source fingerprint, projection summary, runtime requirement, and policy decision.
Replay queues a pending call. It does not execute the command or mark the call approved. Operators or wrappers must review and approve the new call through the normal approval queue, then run it with brigadestack 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.
brigadestack 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. brigadestack work brief surfaces the highest-priority run-history issue, and brigadestack 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. BrigadeStack 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:
id, optional. BrigadeStack generates one when absentreasonrequested_actionpromptoroperator_promptcontext, redacted before storagechoicesorallowed_resume_choicescreated_at, optionalexpires_at, optional
When a run writes a checkpoint, BrigadeStack normalizes the file into .brigade/tools/checkpoints/, marks the call waiting, and writes a waiting receipt linked to the checkpoint. brigadestack tools checkpoint approve <checkpoint-id> --choice <choice> marks the checkpoint approved and moves the call to resume-pending. brigadestack 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 is not triggered by doctor, brief, work run, or call run. BrigadeStack redacts checkpoint context and does not store process env values in checkpoints, receipts, logs, imports, or docs.
brigadestack tools doctor warns on stale, expired, rejected, blocked, and failed checkpoints. brigadestack work brief surfaces the highest-priority checkpoint issue, and brigadestack tools import-issues routes checkpoint problems into tool-catalog imports.
Health Checks
brigadestack tools doctor reports:
- missing source, manifest, schema, projection, or health files
- invalid schema JSON
- invalid or unsupported contract schemas
- missing call contracts for command-backed tools
- missing examples
- bad argument templates
- missing required script or custom commands
- command labels that do not resolve on the current host
- high-risk command shapes such as shell pipes into
sh,bash -c,sudo, orrm -rf - parity gaps where a supported harness lacks a projection target
- missing, stale, unmanaged, or locally edited projection files
- stale health files
- unsafe auth or env field names in the local config
- stale or blocked tool call approvals
- approved tool calls with stale source or contract fingerprints
- failed tool call executions
- tool call executions left running too long
- failed or timed-out run receipts
- failed MCP executions, malformed JSON-RPC responses, and MCP tool-list mismatches
- malformed run receipts and missing run log files
- run replay candidates blocked by current tool, runtime, or policy state
- stale, expired, rejected, blocked, or failed checkpoints
- missing, stopped, stale, unhealthy, or unmanaged required runtimes
- runtime config, cwd, command, PID, port, and health-check issues
- missing execution policy for executable contract-backed tools
- policy blockers for effects, timeouts, approval modes, runtimes, families, and env labels
- MCP config issues in local JSON files with
mcpServers
MCP discovery is structural. BrigadeStack summarizes server count and server ids, checks for missing commands and timeout metadata, and flags broad shell-like command shapes. MCP execution runs only approved calls through brigadestack tools call run, against local runtimes.
Work Inbox Routing
brigadestack tools import-issues creates local work imports with:
source = "tool-catalog"- logical tool id
- source family
- issue type
- harness and projection target when relevant
- safe issue detail
- stable source item key and fingerprint
Repeated imports dedupe equivalent pending or promoted issues. Dismissed tool-catalog imports stay dismissed until the issue fingerprint changes.
Keep secrets out of the catalog
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. BrigadeStack reports unsafe field names without copying their values into command output, work imports, session artifacts, docs, or handoffs.
brigadestack tools call run executes approved local script entries and approved local mcp entries with already-running managed runtimes, and records local receipts. Call planning, approval review, run history inspection, and checkpoint review do not execute anything. Replay creates a pending call that still goes through the approval, runtime, and policy gates. Execution policy is host-local and gitignored. BrigadeStack 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.