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/hooks.md
View on GitHub# Hooks & triggers
[`src/toolbox_hooks.py`](https://github.com/stevesolun/ctx/blob/main/src/toolbox_hooks.py)
is the bridge between Claude Code's hook system and the toolbox runner.
It listens for four hook events. User-initiated slash wrappers use the same
toolbox config but are not emitted by this hook runner.
## Event model
| Event | Fires on | Typical toolbox |
|---|---|---|
| `session-start` | New Claude Code session | Skill preloaders, intent suggestions |
| `file-save` | File written to disk | Linters, quick reviewers |
| `pre-commit` | `git commit` before write | `security-sweep` guardrail |
| `session-end` | Session closes | Digest, behavior miner, retro |
`session-start` matches active toolboxes with a non-empty `pre` list.
`file-save`, `pre-commit`, and `session-end` use the toolbox's `trigger`
map. Events with no matching toolbox emit nothing. User-initiated slash
wrappers are dispatched outside `toolbox_hooks.py` and select toolboxes from
the same config with `trigger.slash`.
## Emission format
One JSON line per matching toolbox, on stdout:
```jsonc
{
"trigger": "pre-commit",
"toolbox": "security-sweep",
"plan_file": "/Users/steve/.claude/toolbox-runs/abc123.json",
"agents": ["security-reviewer", "security-auditor", "penetration-tester"],
"files": ["src/toolbox_verdict.py", "src/tests/test_toolbox_verdict.py"],
"source": "fresh",
"guardrail": true
}
```
Claude Code's hook handler reads these lines and dispatches each agent
against the listed files.
## Exit codes
| Code | Meaning |
|---|---|
| `0` | Success; zero or more toolboxes emitted |
| `1` | Unknown trigger or config error |
| `2` | `pre-commit` + `guardrail=true` + verdict level is HIGH/CRITICAL |
The `2` exit from `pre-commit` is what actually blocks `git commit`.
## Installation
`pip install claude-ctx` exposes `python -m toolbox` on PATH; wire it into
`.githooks/pre-commit` directly:
```bash
# .githooks/pre-commit
#!/bin/sh
python -m toolbox run --event pre-commit
```
Then `git config core.hooksPath .githooks`.
## file-save path matching
`file-save` triggers honor the `trigger.file_save` glob. Without a
`--path` arg the event matches nothing (there's no file to test). This is
intentional: file-save toolboxes must be path-scoped.
## session-end digest
On `session-end`, the hook also calls
[`behavior_miner.build_profile`](behavior-miner.md), saves the updated
profile, and prints any new suggestions. This is informational only —
the digest never blocks and never changes the return code.
## Reference
- [Council runner](council-runner.md) — how plans are built.
- [Verdicts & guardrails](verdicts.md) — how blocking is decided.
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 |