Summary
A declarative API for defining workflows that span multiple hook events, enabling complex multi-step behaviors that single hooks cannot express.
Motivation
Individual hooks react to a single event. But real-world needs often involve coordinated behavior across events:
- Snapshot a file before edit → run linter after edit → restore on failure
- Track a sequence of tool calls and block if a dangerous pattern emerges
- Accumulate context across multiple tool uses and inject a summary at compaction
These require orchestration that today must be hacked together with shared state and convention.
Proposed API
cc.workflow("safe-edit", [
{ event: "PreToolUse", matcher: "Edit", action: snapshotFile },
{ event: "PostToolUse", matcher: "Edit", action: runLinter },
{ event: "PostToolUseFailure", matcher: "Edit", action: restoreSnapshot },
])Design Considerations
- State scoping: Each workflow instance gets isolated state (e.g., per-file snapshot)
- Lifecycle: Workflows activate on the first matching event and deactivate on completion or timeout
- Error handling: Define fallback actions when a step fails
- Composition: Workflows can be nested or chained
- Visualization:
hx dashboard can show workflow state transitions
Why This Matters
This is something Claude Code cannot do natively. Workflows make hx a reactive orchestration layer on top of Claude Code, not just a hook compiler.
Summary
A declarative API for defining workflows that span multiple hook events, enabling complex multi-step behaviors that single hooks cannot express.
Motivation
Individual hooks react to a single event. But real-world needs often involve coordinated behavior across events:
These require orchestration that today must be hacked together with shared state and convention.
Proposed API
Design Considerations
hx dashboardcan show workflow state transitionsWhy This Matters
This is something Claude Code cannot do natively. Workflows make hx a reactive orchestration layer on top of Claude Code, not just a hook compiler.