swiz
AI coding agents are capable of impressive things. They're also capable of forgetting to commit, shipping debug statements, ignoring failing CI, losing track of what they were supposed to do, and declaring "task complete" the moment they want to stop. swiz is a hook framework that doesn't let them get away with any of it.
One manifest of TypeScript hook scripts gets installed across Claude Code, Cursor, Gemini CLI, and Codex CLI — translating tool names, event names, and config formats automatically so every agent plays by the same rules. The hooks enforce discipline at every stage of the agent loop: before tools run, after they complete, and before the session is allowed to stop.
When swiz idea and swiz continue are used together, the system can enter a self-directed loop — a closed-loop state where the agent's own outputs become the next inputs, expanding the project without external prompts. See docs/ai-providers.md for the canonical terminology.
116 hooks. 12 event types. Every agent. Zero compromises.
Install
bun install
bun link
Then use swiz from anywhere.
How It Works
Every agent exposes hook events at key moments in the loop. swiz intercepts those moments:
User prompt submitted → userpromptsubmit-* hooks inject context (git state, active tasks)
↓
Agent calls a tool → pretooluse-* hooks can block the call before it executes
↓
Tool completes → posttooluse-* hooks validate results, remind about tests
↓
Agent tries to stop → stop-* hooks audit the full session state and block if anything is unresolved
Hooks communicate back using polyglot JSON — a single output format that all four agents understand. A hook script written once works identically whether it was triggered by Claude, Cursor, Gemini, or Codex.
{
"decision": "block",
"reason": "Uncommitted changes detected: 2 modified (3 file(s))...",
"hookSpecificOutput": { "permissionDecision": "deny" }
}
The Agent Ecosystem
swiz supports every agent that has a hook system, with automatic translation of tool names and event names from a single canonical manifest:
| Agent | Config Path | Status |
|---|
| Claude Code | ~/.claude/settings.json | Full support — nested matcher groups, all 5 event types |
| Cursor IDE | ~/.cursor/hooks.json | Full support — flat list (version: 1), all events |
| Cursor CLI | ~/.cursor/hooks.json | Limited — only beforeShellExecution/afterShellExecution fire (tracking issue). Use swiz shim as workaround. |
| Gemini CLI | ~/.gemini/settings.json | Full support — nested matcher groups, all 5 event types |
| Codex CLI | ~/.codex/hooks.json | Full support — nested matcher groups, shipped event types (SessionStart, Stop, UserPromptSubmit) |
Cross-Agent Translation
The canonical manifest uses neutral names. At install time, agents.ts translates everything per-agent so hook scripts never need to know which agent ran them:
Tool Names
