stevesolun/ctx / docs
skill-router
FlaggedRepo-aware recommendation manager for ctx. Scans the active repository, identifies stack and workflow signals, recommends a capped set of skills, agents, and MCP servers, and unloads helpers that no longer match the current work after user confirmation. Harnesses are recommended by the custom-model onboarding flow or loop adapters and then attach to the same recommendation layer.
toolbox/index.md
View on GitHub# Toolbox overview
!!! info "Part of the recommendation surface, not CTX Fit"
The product is **CTX Fit** (`ctx fit`): it finds the cheapest AI coding
setup that reliably works on a repository. See the [home page](../index.md).
This page documents the older graph-backed recommendation layer, which
still ships and is what the published PyPI release installs.
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
```mermaid
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`](https://github.com/stevesolun/ctx/blob/main/src/toolbox_config.py)
loads `~/.claude/toolboxes.json` and merges per-repo `.toolbox.yaml` on top.
- **Trigger**: [`toolbox_hooks.py`](https://github.com/stevesolun/ctx/blob/main/src/toolbox_hooks.py)
listens for `session-start`, `file-save`, `pre-commit`, and `session-end`.
User-initiated `/toolbox run` wrappers use the same toolbox config but do
not enter through `toolbox_hooks.py`.
- **Plan**: [`council_runner.py`](https://github.com/stevesolun/ctx/blob/main/src/council_runner.py)
assembles a `RunPlan` honoring scope, budget caps, dedup, and graph-blast expansion.
- **Verdict**: [`toolbox_verdict.py`](https://github.com/stevesolun/ctx/blob/main/src/toolbox_verdict.py)
merges findings by id and escalates level to max(findings).
## Minimal declaration
```yaml
# .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:
```bash
python -m toolbox run --event pre-commit
```
Or let the `pre-commit` hook fire it automatically — see
[Hooks & triggers](hooks.md).
## Scope modes
| Mode | What gets reviewed | Best for |
|---|---|---|
| `diff` | Files in the current uncommitted diff | Pre-commit, real-time review |
| `dynamic` | Diff by default; graph-blast for tiny diffs when graph edges are available; full repo when no diff exists | General-purpose review |
| `graph-blast` | Diff plus one graph hop when graph edges are supplied | Refactor safety |
| `full` | Entire repo | Security sweeps, docs audits |
## Related
- [Configuration schema](configuration.md) — full field reference.
- [Starter toolboxes](starters.md) — 5 shipping presets.
- [Intent interview](intent-interview.md) — `toolbox init` walkthrough.
- [Verdicts & guardrails](verdicts.md) — how blocking works.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |