Session ID Environment Variable and Deep Link Support

[johnstonmatt]

Session ID Environment Variable and Deep Link Support

Summary

Add a WARP_SESSION_ID environment variable and warp://session/<id> deep link support to enable external tools to focus specific Warp tabs/windows.

Motivation

When using notification systems or external integrations (like Claude Code, CI/CD tools, or monitoring alerts), there's no way to focus the specific Warp tab where the command is running. The current warp://action/new_tab and warp://action/new_window URIs only create new sessions, they can't focus existing ones.

Real-World Use Case

I'm using Claude Code with macOS notifications (via terminal-notifier) to alert me when it needs input. When I click the notification, it activates Warp, but if I have multiple windows/tabs open, I have to manually find the right one. This breaks the workflow.

Proposed Solution

1. Environment Variable

Expose a unique session identifier in each terminal session:

echo $WARP_SESSION_ID
# Output: 550e8400-e29b-41d4-a716-446655440000

2. Deep Link URI

Add a new URI scheme to focus existing sessions:

open "warp://session/550e8400-e29b-41d4-a716-446655440000"

This would:

• Bring Warp to the foreground
• Focus the window containing that session
• Switch to the tab with that session ID

Example Integration

#!/bin/bash
# Notification script that focuses the correct Warp tab

SESSION_ID="${WARP_SESSION_ID}"

terminal-notifier \
  -title "Claude Code" \
  -message "Waiting for input" \
  -execute "open 'warp://session/$SESSION_ID'"

Alternative Considered

Using terminal-notifier -activate dev.warp.Warp-Stable brings Warp to focus, but doesn't switch to the correct tab when multiple sessions are open.

Similar Features in Other Terminals

• iTerm2: Supports session-specific scripting via AppleScript
• tmux/screen: Can target specific sessions by name/ID
• Warp Launch Configurations: Already support active_window_index and active_tab_index, but only for new sessions

Benefits

1. Better IDE/Editor Integration: External tools can jump to the right terminal session
2. Notification Workflows: Click notifications to focus the exact tab that needs attention
3. Automation Scripts: Target specific sessions for sending commands or monitoring
4. Multi-Session Management: Programmatically switch between project-specific terminal sessions

Implementation Notes

• The session ID should persist for the lifetime of the tab/pane
• Should be exposed early in the shell initialization (before .bashrc/.zshrc)
• Consider adding to existing Warp env vars (WARP_IS_LOCAL_SHELL_SESSION, WARP_HONOR_PS1, etc.)
• Could be a UUID, hash of window/tab indices, or any stable unique identifier

Related

• Ability to open and new tab and execute a command in the tab from the command line #3959 - Ability to open new tab and execute command from command line
• Existing URI scheme docs: https://docs.warp.dev/terminal/more-features/uri-scheme

[rogeriochaves]

looking exactly for this, same use case!

[nzaytsev]

same