feat: add session detach/attach for tmux-like persistence

- Add detach keybind (Ctrl-\) to leave session running in background
- Add `tap attach [session]` command to reattach to running sessions
- Add `tap start -d` for starting detached sessions
- Update README with new value proposition for tiling WM users
- Sessions now survive terminal close, can be reattached later

The key insight: tiling WM users already have window management.
tmux's tiling is redundant overhead. tap gives you the one thing
that matters (session persistence) without the rest.

Author: andrewgazelka

.github/assets/header.svg

@@ -6,56 +6,75 @@
   <code>nix run github:andrewgazelka/tap</code>
 </p>
 
-Let Claude Code see and control your other terminal windows.
+Terminal session manager for tiling WM users. Detach and reattach to sessions without the overhead of tmux.
 
 ## The Problem
 
-You're running a dev server in one terminal tab. You ask Claude Code to check if it's working. But Claude Code can't see that tab - it only sees its own terminal.
+If you use a tiling window manager (i3, Sway, Aerospace, yabai), you already have window tiling. Running tmux means two competing systems: tmux tiles inside the terminal, your WM tiles windows. This creates:
+
+- Conflicting keybindings (is `Ctrl+b` for tmux or your WM?)
+- Nested navigation (WM to window, then tmux to pane)
+- Redundant concepts (tmux panes vs terminal windows)
+
+But tmux has one killer feature: **session persistence**. You can detach from a running process and reattach later. That's worth the overhead for some people.
 
 ## The Solution
 
+`tap` gives you session persistence without the tiling overhead.
+
 ```sh
-tap
+tap                    # start a session
+# ... run your dev server ...
+# close the terminal (or press Ctrl+\ to detach)
+
+tap attach             # reattach from any terminal
 ```
 
-Your shell works exactly the same - you won't notice any difference. But now Claude Code can see and type into this terminal in the background.
+Your window manager handles tiling. `tap` handles persistence. No conflicts.
 
-## Example
+## Features
 
-```sh
-# Terminal 1
-tap              # starts your normal shell, nothing changes
-npm run dev      # use it like normal
-
-# Meanwhile, Claude Code can:
-# - See "Server running on :3000"
-# - Run "curl localhost:3000" in this terminal
-# - Watch for errors
-```
+- **Detach/Attach** - Close your terminal, reattach later
+- **Background sessions** - Start processes that outlive your terminal
+- **Scrollback capture** - Access terminal output programmatically
+- **AI integration** - Claude Code can see and control tap sessions
+- **Zero config** - Works out of the box, no `.tmux.conf` required
 
 ## Commands
 
 ```sh
-tap                  # start your normal shell
-tap start htop       # or any command
-tap list             # see active sessions
-tap scrollback       # read terminal output
-tap cursor           # get cursor position
-tap size             # get terminal size
-tap inject "ls"      # type into the terminal
-tap subscribe        # stream live output
+tap                      # start interactive session
+tap start htop           # run a command in a new session
+tap list                 # list active sessions
+tap attach [session]     # reattach to a session
+tap detach               # detach from current session (or Ctrl+\)
+tap scrollback [session] # get terminal output
+tap inject "ls" [session] # type into a session
 ```
 
 ## Shell Integration
 
 ### Ghostty
 
-Add to your Ghostty config (`~/.config/ghostty/config`):
+Add to `~/.config/ghostty/config`:
 
 ```
 command = tap
 ```
 
+Now every new terminal window is automatically a tap session.
+
+## Comparison
+
+| Feature | tmux | screen | abduco | tap |
+|---------|------|--------|--------|-----|
+| Session persistence | yes | yes | yes | yes |
+| Window/pane tiling | yes | yes | no | no |
+| Config complexity | high | medium | low | none |
+| Keybind conflicts with WM | yes | yes | minimal | minimal |
+| Scrollback API | no | no | no | yes |
+| AI tool integration | no | no | no | yes |
+
 ## Architecture
 
 ```mermaid

Cargo.lock

@@ -137,9 +137,37 @@ impl Client {
         match response {
             Response::Output { data } => Ok(Some(data)),
             Response::Error { message } => Err(Error::Server(message)),
+            Response::SessionEnded { .. } => Ok(None),
             _ => Err(Error::Server("unexpected response".to_string())),
         }
     }
+
+    /// Attach to the session (take over stdin/stdout).
+    /// Returns the initial scrollback content if successful.
+    pub async fn attach(&mut self, rows: u16, cols: u16) -> Result<String> {
+        let response = self.send_request(&Request::Attach { rows, cols }).await?;
+        match response {
+            Response::Attached { scrollback } => Ok(scrollback),
+            Response::Error { message } => Err(Error::Server(message)),
+            _ => Err(Error::Server("unexpected response".to_string())),
+        }
+    }
+
+    /// Send input to the PTY (for attached clients).
+    pub async fn send_input(&mut self, data: Vec<u8>) -> Result<()> {
+        let request = Request::Input { data };
+        let request_bytes = serde_json::to_vec(&request)?;
+        self.stream.get_mut().write_all(&request_bytes).await?;
+        Ok(())
+    }
+
+    /// Resize the PTY (for attached clients).
+    pub async fn resize(&mut self, rows: u16, cols: u16) -> Result<()> {
+        let request = Request::Resize { rows, cols };
+        let request_bytes = serde_json::to_vec(&request)?;
+        self.stream.get_mut().write_all(&request_bytes).await?;
+        Ok(())
+    }
 }
 
 #[cfg(test)]

README.md

@@ -3,6 +3,7 @@
 use eyre::WrapErr as _;
 
 const DEFAULT_EDITOR_KEYBIND: &str = "Alt-e";
+const DEFAULT_DETACH_KEYBIND: &str = "Ctrl-\\";
 const DEFAULT_ESCAPE_TIMEOUT_MS: u64 = 50;
 const DEFAULT_EDITOR: &str = "vi";
 
@@ -27,6 +28,9 @@ pub struct KeybindConfig {
     /// Keybind to open scrollback in editor.
     /// Format: "Alt-e", "Ctrl-e", etc.
     pub editor: String,
+    /// Keybind to detach from session.
+    /// Format: "Ctrl-\\", etc.
+    pub detach: String,
 }
 
 #[derive(Debug, Clone, serde::Deserialize, serde::Serialize)]
@@ -40,6 +44,7 @@ impl Default for KeybindConfig {
     fn default() -> Self {
         Self {
             editor: DEFAULT_EDITOR_KEYBIND.to_string(),
+            detach: DEFAULT_DETACH_KEYBIND.to_string(),
         }
     }
 }
@@ -94,8 +99,13 @@ pub enum Keybind {
 }
 
 impl Keybind {
-    /// Parse a keybind string like "Alt-e" or "Ctrl-e".
+    /// Parse a keybind string like "Alt-e" or "Ctrl-e" or "Ctrl-\\".
     pub fn parse(s: &str) -> eyre::Result<Self> {
+        // Handle special case of Ctrl-\ (backslash)
+        if s == "Ctrl-\\" || s == "ctrl-\\" {
+            return Ok(Keybind::Ctrl('\\'));
+        }
+
         let parts: Vec<&str> = s.split('-').collect();
         if parts.len() != 2 {
             eyre::bail!("invalid keybind format '{s}' — expected 'Alt-<key>' or 'Ctrl-<key>'");
@@ -265,4 +275,20 @@ mod tests {
         let kitty_seq = b"\x1b[101;5u";
         assert_eq!(kb.matches(kitty_seq), None);
     }
+
+    #[test]
+    fn test_keybind_parse_ctrl_backslash() {
+        let kb = Keybind::parse("Ctrl-\\").unwrap();
+        assert_eq!(kb, Keybind::Ctrl('\\'));
+        // Ctrl-\ is 0x1C (ASCII FS - File Separator)
+        assert_eq!(kb.matches(&[0x1c]), Some(1));
+    }
+
+    #[test]
+    fn test_default_detach_keybind() {
+        let config = Config::default();
+        assert_eq!(config.keybinds.detach, "Ctrl-\\");
+        let kb = Keybind::parse(&config.keybinds.detach).unwrap();
+        assert_eq!(kb, Keybind::Ctrl('\\'));
+    }
 }

crates/tap-client/src/lib.rs

@@ -7,6 +7,9 @@ pub struct Session {
     pub pid: u32,
     pub started: String,
     pub command: Vec<String>,
+    /// Whether a client is currently attached to this session.
+    #[serde(default)]
+    pub attached: bool,
 }
 
 /// Client requests to the server.
@@ -23,6 +26,17 @@ pub enum Request {
     GetSize,
     /// Subscribe to live output.
     Subscribe,
+    /// Attach to the session (take over stdin/stdout).
+    Attach {
+        /// Terminal rows.
+        rows: u16,
+        /// Terminal columns.
+        cols: u16,
+    },
+    /// Send input from attached client to PTY.
+    Input { data: Vec<u8> },
+    /// Resize the PTY from attached client.
+    Resize { rows: u16, cols: u16 },
 }
 
 /// Server responses.
@@ -39,6 +53,13 @@ pub enum Response {
     Output { data: Vec<u8> },
     /// Subscription confirmed.
     Subscribed,
+    /// Attach confirmed - client now owns stdin/stdout.
+    Attached {
+        /// Current scrollback content for initial display.
+        scrollback: String,
+    },
+    /// Session has ended (child process exited).
+    SessionEnded { exit_code: i32 },
     /// Success.
     Ok,
     /// Error.

crates/tap-config/src/lib.rs

@@ -12,6 +12,7 @@ pub struct InputProcessor {
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum KeybindAction {
     OpenEditor,
+    Detach,
 }
 
 #[derive(Debug)]
@@ -31,6 +32,9 @@ impl InputProcessor {
         let editor_keybind = tap_config::Keybind::parse(&config.keybinds.editor)?;
         keybinds.push((editor_keybind, KeybindAction::OpenEditor));
 
+        let detach_keybind = tap_config::Keybind::parse(&config.keybinds.detach)?;
+        keybinds.push((detach_keybind, KeybindAction::Detach));
+
         Ok(Self {
             keybinds,
             escape_timeout: std::time::Duration::from_millis(config.timing.escape_timeout_ms),