Tap To Tmux

tap-to-tmux

Push notifications and one-tap deep links for AI agents running in tmux on a remote server.

Table of contents

- Who this is for
- Key features
- How it works
- Tap-to-connect deep links
- Notification delivery
- Prerequisites
- Installation
- Configuration
- Claude Code hooks setup
- Starting the services
- macOS setup
- Health check
- Troubleshooting
- Project structure
- Receiving notifications on desktop
- Self-hosted ntfy server
- tap-to-tmux vs Claude Code Remote Control
- FAQ
- Open tasks

Who this is for

You run Claude Code, Codex, Gemini CLI, or other AI agents inside tmux sessions on a VPS, cloud instance, or any machine reachable via SSH. You walk away — to make coffee, take a call, work on something else. When an agent finishes, needs permission, or hits an error, tap-to-tmux sends a push notification to your phone with context about what happened. Tap the notification and Blink Shell opens an SSH connection straight into the exact tmux pane where the agent is waiting.

tmux is required. tap-to-tmux discovers sessions by walking the process tree to find parent tmux panes, builds deep links that attach to specific tmux sessions, and creates independent mobile viewports via grouped tmux sessions. Without tmux, the core notification and deep link features do not work.

The remote machine can be anything reachable via SSH — a cloud VPS, a dedicated server, or even your laptop on the same network or connected via Tailscale.

Key features

- Push notifications via ntfy with rich context (task, last response, project name)
- Tap-to-connect deep links via Blink Shell — one tap from notification to the right tmux pane
- Any agent in tmux — Claude Code, Codex, Gemini CLI, or anything else running in a tmux session
- Smart deduplication — one…