Push Notifications for AI Coding Workflows: Engineering Reliable Delivery

Claude Code can run for minutes or hours on a complex task. Without notifications, you either watch the terminal or check back periodically and hope you haven't missed something important. Neither approach respects your time.

Push notifications are what make Tactic Remote a workflow tool rather than a remote viewer. This post covers how we built the notification system, the integration with Claude Code hooks, the reliability engineering behind delivery, and the usage patterns we've observed from real developers.

The Core Insight

The value of push notifications in Tactic Remote is not "your phone buzzes." It's that notifications change when and how you interact with your AI coding agent. Instead of synchronous terminal monitoring, you get asynchronous task management:

1. Start a Claude Code task from your Mac (or from the iPhone app).
2. Walk away. Make coffee. Join a meeting. Commute home.
3. Your phone notifies you when the task completes, encounters an error, or needs your approval.
4. You review and respond in seconds, then return to what you were doing.

We call this the "check your phone, not your desk" workflow. It's the same mental model as CI/CD notifications — you don't watch your build pipeline; you wait for it to tell you the result.

Claude Code Hooks Integration

The notification system is powered by Claude Code's hook mechanism. Hooks are user-configurable scripts that Claude Code executes at defined lifecycle points. Tactic Remote's Mac companion app registers hooks for three event types:

Task completion — Fires when Claude Code finishes processing a request. The hook captures the exit status, a summary of changes made, and the final lines of terminal output.

Approval required — Fires when Claude Code encounters an operation that requires human confirmation (file writes outside the project directory, shell commands, network requests, etc.). The hook captures the pending operation description and a unique approval ID.

Error — Fires when Claude Code encounters a fatal error, a tool failure, or an API timeout. The hook captures the error message and relevant context.

Each hook invocation sends a structured payload to the Mac companion server, which determines notification routing, constructs the APNs (Apple Push Notification service) payload, and dispatches it through our notification relay.

Notification Types in Practice

Each notification type is designed for a specific interaction pattern:

Task completion notifications include the task summary and a status indicator (success or partial completion). Tapping the notification opens the Tactic Remote app directly to the completed session's terminal view so you can review the output.

Approval notifications are the highest priority. They include the operation description ("Claude wants to run rm -rf build/ in project directory") and present Approve/Reject actions directly on the notification banner. On iPhone, you can respond to an approval without opening the app — long-press the notification to see the inline actions. Our telemetry shows that 62% of approvals are handled via notification actions without fully opening the app.

Error notifications include the error category and a truncated message. These are actionable — tapping opens the session view where you can review the full error context and decide whether to restart or modify the task.

Delivery Reliability

Push notification delivery is not guaranteed by APNs. Apple's documentation states that notifications are "best effort" and may be dropped under device power management, network conditions, or rate limits. For a developer tool where a missed approval notification means a stalled task, "best effort" is insufficient.

We layer several reliability mechanisms on top of APNs:

Server-side state tracking. The Mac companion server maintains a delivery ledger for every notification. Each notification has a unique ID, a timestamp, and a delivery state (pending, sent, acknowledged, expired).

Client-side acknowledgment. When the iPhone app receives and displays a notification, it sends an acknowledgment back to the Mac companion server. If no acknowledgment arrives within 30 seconds, the server retransmits.

Exponential backoff retransmission. Unacknowledged notifications are retried at 30s, 60s, and 120s intervals. After three failures, the notification is marked as potentially undeliverable and flagged in the Mac companion's status UI.

In-app sync. When the iPhone app opens (or returns from background), it queries the Mac companion for any unacknowledged notifications and displays them in the notification center. This catches any notifications that APNs dropped entirely.

Deduplication. With retransmission comes the risk of duplicate delivery. Every notification carries a unique ID that the iPhone client tracks. Duplicates are silently dropped in normal operation so the same approval request is not repeatedly shown.

In internal beta observations, most approval notifications are acknowledged quickly, with a longer tail under degraded network or power conditions.

Notification Deduplication Details

Deduplication deserves special attention because it affects user trust. If a developer sees the same "approve file write" notification twice, they question whether they already approved it. If they see an approval notification for an operation they already approved, they question whether their approval was received.

Our deduplication works at two levels:

Transport-level. Each notification has a UUID that persists across retransmissions. The iPhone client maintains a rolling window of 500 recently seen UUIDs. Any notification with a previously seen UUID is dropped before display.

Semantic-level. For approval notifications specifically, the client checks whether the approval ID has already been acted on. If you approved an operation via the first notification delivery, and a retransmission arrives, the retransmission is suppressed even if its transport UUID differs (which can happen if the server generated a new push payload for the retry).

How Developers Actually Use Notifications

After four months of beta data, clear patterns have emerged:

Peak notification hours are 9-11 AM and 2-4 PM in the user's local timezone — corresponding to the start of coding sessions and post-lunch productivity blocks.

In our internal tests, approval response time is usually measured in seconds, with a longer tail under poor connectivity.

Most common notification-driven workflow: Start a multi-step refactoring task, leave desk for a meeting, approve 2-3 file operations during the meeting via notification actions, return to find the task completed.

Notification volume: The median active user receives 8 notifications per day. Power users (P95) receive around 30. We haven't seen notification fatigue in our surveys — likely because each notification represents an actionable event, not a status update.

Mute patterns: some users configure focus-mode rules that batch non-approval notifications during certain hours. For approval-critical flows, we prioritize immediate delivery and in-app reconciliation when the user returns.

What's Next

We're working on several notification improvements:

• Rich notifications with code previews — Approval notifications that show a diff preview directly on the notification, so you can make informed approve/reject decisions without opening the app.
• Notification grouping — Batching rapid-fire task completions (common during multi-session workflows) into a single summary notification.
• Custom notification sounds — Distinct audio cues for completions vs. approvals vs. errors, so you can triage by sound without looking at your phone.

For notification configuration options, see the Notification Settings guide. For the Claude Code hooks reference that powers this system, see Hooks Integration.