Skip to content

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-warp marketplace 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.