Warp Terminal Notification Plugin¶
- Date: 2026-04-10
- Status: Accepted
- Tags:
tooling
Context¶
Claude Code sessions frequently run for minutes or longer, especially during plan execution, research, or multi-step debugging. Without a notification mechanism, the user must manually check the terminal to know when Claude is idle, waiting for permission, or finished. This creates unnecessary context-switching overhead and slows down workflows where Claude is blocked on human input.
Decision¶
Adopted the warp plugin (v2.0.0) from the claude-code-warp marketplace. The plugin hooks into six Claude Code lifecycle events — SessionStart, Stop, Notification (idle_prompt), PermissionRequest, UserPromptSubmit, and PostToolUse — to deliver native Warp terminal notifications. This keeps the user informed without requiring them to watch the terminal.
Alternatives Considered¶
| Option | Why Rejected |
|---|---|
| Manual polling | Tedious and error-prone; defeats the purpose of running long autonomous sessions |
Generic OS notifications (e.g., terminal-notifier) |
Less integrated with Warp terminal; no awareness of Claude Code lifecycle hooks |
Custom shell scripts with osascript |
Brittle, hard to maintain, no hook integration |
Consequences¶
Positive:
- Immediate awareness when Claude is idle, done, or needs permission — reduces blocked time
- Native Warp integration feels seamless and does not require additional notification infrastructure
- Works alongside existing plugins (superpowers, rlm-claude-code) without conflict
Negative / Trade-offs:
- Only works in Warp terminal — users on iTerm2, Alacritty, or other terminals get no benefit
- Adds another plugin to maintain and keep updated
Ongoing obligations:
- Keep plugin updated as
claude-code-warpmarketplace releases new versions - Verify notification behavior after Warp app updates, as Warp API changes could break the integration
ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.