Claude Code iPhone notifications when the agent finishes

There is a familiar pattern to a Claude Code session that grows teeth. You hand it a task — refactor an auth middleware, port a test suite, untangle a flaky build — and ten minutes in you alt-tab back to the terminal to see if it's done. It isn't. You alt-tab away. Ninety seconds later you alt-tab back. The cycle eats more time than the agent saves.

The fix is not a better terminal. It is a glanceable surface on the device already in your hand. Claude Code lifecycle hooks can report session state to a native Live Activity. Passive hooks are status-only; a phone decision can return allow or deny only through the separate synchronous PermissionRequest command-hook bridge, and iOS requires device authentication/unlock before a Lock Screen action executes.

Why a Live Activity beats `tail -f`-ing your Claude Code session

Push notifications batch into your notification center and die. A long-running agent needs the opposite: a small, persistent UI that stays put while the work is in flight. iOS Live Activities were built for the rideshare ETA and the food-delivery progress bar — they are the right surface for any task that has a start, an end, and useful intermediate state.

• Glanceable: lock-screen visible without unlocking — you check from across the room.
• Persistent: pinned for the whole session, not a banner that scrolls away.
• Stateful: updates on coarse lifecycle changes without narrating every tool call.
• Tappable: deep-link back to Chirp without placing prompts, source, or tool output on the Lock Screen.

What you see when Chirp wraps a Claude Code session

With the reviewed status bridge enabled, an `@claude-code` activity can show coarse session lifecycle state: ready, working after a prompt, waiting on a bounded notification type, turn complete, and session ended. The default setup deliberately removes Chirp-owned PreToolUse/PostToolUse hooks, so it does not send a tool-by-tool feed, file paths, command arguments, or tool output. A passive Notification cannot approve anything. The same default setup installs the separate synchronous PermissionRequest bridge: one exact blocked request can show a time-bounded Allow once or Deny decision, and iOS requires device authentication/unlock before that Lock Screen action executes.

Wire it up in three steps

The integration uses reviewed command-hook bridge code plus Claude Code settings. Distribution and dependencies must be verified before install. The default setup installs both the coarse lifecycle set and PermissionRequest; setup time depends on app readiness, host pairing, and physical-phone verification.

Hook and CLI success proves that Chirp accepted a status event, not that an iPhone displayed it. Finish setup only after the readiness rail records a separate receipt from the selected phone.

1. 1Use the verified signed Chirp iPhone build, then use a verified Chirp CLI build and run `chirp login` on the Claude host. Approve the matching code, host, provider, and capabilities in the browser.
2. 2From the reviewed CLI source build, run `chirp setup claude`. It merges the supported hook entries without replacing unrelated settings.
3. 3Restart Claude Code, exercise a passive status event, then trigger one real PermissionRequest and verify its exact allow-once/deny binding on a physical phone.

The default bridge distinguishes a finite set of lifecycle events. SessionStart, UserPromptSubmit, Notification, Stop, and SessionEnd report only bounded status labels. PermissionRequest is separate: Claude waits for a documented command-hook result, so Chirp binds the one-time decision to the exact host, session, tool, and normalized request hash and denies safely on expiry.

Pick which lifecycle events fire the card

The checked-in setup intentionally uses only that small lifecycle set plus PermissionRequest. It removes older Chirp-owned PreToolUse/PostToolUse entries rather than narrating every tool call. This reduces noise and sensitive payload risk. Changing status granularity never grants approval authority; permission decisions still require PermissionRequest.

Keep the Lock Screen state compact and sanitized. Do not send prompts, full source, raw command arguments, or tool output merely to make a timeline feel richer. Retention controls and privacy disclosures must match every table that stores any integration metadata.

Run two Claude Code sessions side-by-side without the cards stepping on each other

If you run multiple Claude Code sessions concurrently — one in each of two tmux panes, or one local and one in a Codespace — the hook script uses the session ID Claude exports in its hook payload to keep the activities distinct. Each session gets its own card with the provider label and coarse lifecycle status; the default hooks do not add a project subtitle or tool counter. SessionEnd closes its card. If SessionEnd never arrives, a scheduled server cleanup marks any still-active instance older than eight hours ended when that sweep runs. That age-based backstop is not immediate process-exit detection.

Edge cases worth knowing about

Most setups work on the first try. A few situations are worth flagging in advance so you do not bounce off them:

• Container Claude (Codespaces, devcontainers): pair inside the execution environment or use a reviewed scoped credential from the container secret manager. Never paste an account key into chat or bake it into the image.
• Force-quit sessions: SessionEnd may not fire. Verify stale-activity cleanup for the release build; pending approvals must invalidate on process exit, cancellation, disconnect, or heartbeat expiry.
• Older Claude Code versions: hooks shipped in mid-2025, so anything older than that release will silently no-op. Run `claude --version` and update if the card never appears.

Where Claude Code iPhone notifications fit in the bigger picture

Claude Code is the loudest case, but the argument generalizes. Anything that runs longer than a coffee break — a deploy, an ML training run, a backup, an AI agent grinding through a backlog — wants a lock-screen Live Activity instead of a push notification. The full thesis is in the companion post on lock-screen status for long-running jobs, and the CI flavor of the same pattern is documented in the same pattern for GitHub Actions.

The current capability boundary and walkthrough live on the Claude Code integration page. Pair each host explicitly; do not copy a local credential file between machines or assume Claude and Codex expose the same approval surface.

Try it on the next long Claude Code session

1. 1Use the verified signed Chirp iPhone build and run `chirp login` from a verified CLI build on the Claude host.
2. 2Run `chirp setup claude` from the reviewed CLI build and inspect the merged settings.
3. 3Kick off your next non-trivial Claude Code task, lock your phone, and walk away.