Skip to content

Toolbox overview

A toolbox is a named bundle of skills and agents that runs at a defined moment in your workflow: at session start, on file save, before a commit, at session end, or when you invoke its slash command.

Toolboxes let you declare the council you want reviewing your work without hand-loading skills each session.

Lifecycle

flowchart LR
  A[Declare toolbox] --> B[Trigger fires]
  B --> C[Council runner<br/>builds plan]
  C --> D[Agents run<br/>scoped to plan.files]
  D --> E[Findings recorded<br/>as Verdict]
  E -->|HIGH / CRITICAL| F[Guardrail blocks<br/>pre-commit]
  E -->|LOW / MEDIUM| G[Logged,<br/>session continues]

Each arrow is a concrete module:

  • Declare: toolbox_config.py loads ~/.claude/toolboxes.json and merges per-repo .toolbox.yaml on top.
  • Trigger: toolbox_hooks.py listens for session-start, file-save, pre-commit, session-end, and the /toolbox run slash command.
  • Plan: council_runner.py assembles a RunPlan honoring scope, dedup, and graph-blast expansion.
  • Verdict: toolbox_verdict.py merges findings by id and escalates level to max(findings).

Minimal declaration

# .toolbox.yaml (per-repo)
version: 1
toolboxes:
  review:
    description: "Post-feature code review"
    post:
      - code-reviewer
      - security-reviewer
    scope:
      analysis: diff
    trigger:
      slash: true
      pre_commit: true
    guardrail: true

Run it manually:

ctx-toolbox run review

Or let the pre-commit hook fire it automatically — see Hooks & triggers.

Scope modes

Mode What gets reviewed Best for
diff Files in the current uncommitted diff Pre-commit, real-time review
dynamic Diff + graph blast radius (imports of modified files) Refactor safety
full Entire repo Security sweeps, docs audits