chore: Rename 'atuin hex' to 'atuin pty-proxy' (#3473)

.atuin/skills/release/SKILL.md

@@ -187,7 +187,7 @@ hasn't indexed a freshly-published dependency yet):
 atuin-common, atuin-client, atuin-ai, atuin-dotfiles, atuin-history,
 atuin-nucleo/matcher, atuin-nucleo, atuin-daemon, atuin-kv,
 atuin-scripts, atuin-server-database, atuin-server-postgres,
-atuin-server-sqlite, atuin-server, atuin-hex, atuin
+atuin-server-sqlite, atuin-server, atuin-pty-proxy, atuin
 ```
 
 For each crate, run from `crates/<name>`:

.claude/skills/release/SKILL.md

@@ -243,7 +243,7 @@ hasn't indexed a freshly-published dependency yet):
 atuin-common, atuin-client, atuin-ai, atuin-dotfiles, atuin-history,
 atuin-nucleo/matcher, atuin-nucleo, atuin-daemon, atuin-kv,
 atuin-scripts, atuin-server-database, atuin-server-postgres,
-atuin-server-sqlite, atuin-server, atuin-hex, atuin
+atuin-server-sqlite, atuin-server, atuin-pty-proxy, atuin
 ```
 
 For each crate, run from `crates/<name>`:

Cargo.lock

@@ -223,10 +223,10 @@ dependencies = [
  "atuin-common",
  "atuin-daemon",
  "atuin-dotfiles",
- "atuin-hex",
  "atuin-history",
  "atuin-kv",
  "atuin-nucleo-matcher",
+ "atuin-pty-proxy",
  "atuin-scripts",
  "atuin-server",
  "atuin-server-database",
@@ -446,18 +446,6 @@ dependencies = [
  "tokio",
 ]
 
-[[package]]
-name = "atuin-hex"
-version = "18.16.0"
-dependencies = [
- "clap",
- "crossterm",
- "eyre",
- "portable-pty",
- "signal-hook",
- "vt100",
-]
-
 [[package]]
 name = "atuin-history"
 version = "18.16.0"
@@ -514,6 +502,18 @@ dependencies = [
  "unicode-segmentation",
 ]
 
+[[package]]
+name = "atuin-pty-proxy"
+version = "18.16.0"
+dependencies = [
+ "clap",
+ "crossterm",
+ "eyre",
+ "portable-pty",
+ "signal-hook",
+ "vt100",
+]
+
 [[package]]
 name = "atuin-scripts"
 version = "18.16.0"

crates/atuin-pty-proxy/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
-name = "atuin-hex"
+name = "atuin-pty-proxy"
 edition = "2024"
-description = "a terminal emulator for atuin"
+description = "a PTY proxy for atuin"
 
 version = { workspace = true }
 authors = { workspace = true }

crates/atuin-pty-proxy/src/lib.rs

@@ -4,7 +4,7 @@ use clap::{Args, Subcommand, ValueEnum};
 
 #[derive(Subcommand, Debug)]
 pub enum Cmd {
-    /// Print shell code to initialize atuin-hex on shell startup
+    /// Print shell code to initialize atuin pty-proxy on shell startup
     Init(Init),
 }
 
@@ -42,7 +42,7 @@ pub fn run(cmd: Option<Cmd>) {
     match cmd {
         Some(Cmd::Init(init)) => {
             if let Err(err) = init.run() {
-                eprintln!("atuin hex: {err}");
+                eprintln!("atuin pty-proxy: {err}");
                 std::process::exit(1);
             }
         }
@@ -95,55 +95,57 @@ fn render_init(shell: Shell) -> &'static str {
     match shell {
         Shell::Bash | Shell::Zsh => {
             r#"if [[ "$-" == *i* ]] && [[ -t 0 ]] && [[ -t 1 ]]; then
-  _atuin_hex_tmux_current="${TMUX:-}"
-  _atuin_hex_tmux_previous="${ATUIN_HEX_TMUX:-}"
+  _atuin_pty_proxy_tmux_current="${TMUX:-}"
+  _atuin_pty_proxy_tmux_previous="${ATUIN_PTY_PROXY_TMUX:-${ATUIN_HEX_TMUX:-}}"
 
-  if [[ -z "${ATUIN_HEX_ACTIVE:-}" ]] || [[ "$_atuin_hex_tmux_current" != "$_atuin_hex_tmux_previous" ]]; then
-    export ATUIN_HEX_ACTIVE=1
-    export ATUIN_HEX_TMUX="$_atuin_hex_tmux_current"
-    exec atuin hex
+  if [[ -z "${ATUIN_PTY_PROXY_ACTIVE:-${ATUIN_HEX_ACTIVE:-}}" ]] || [[ "$_atuin_pty_proxy_tmux_current" != "$_atuin_pty_proxy_tmux_previous" ]]; then
+    export ATUIN_PTY_PROXY_ACTIVE=1
+    export ATUIN_PTY_PROXY_TMUX="$_atuin_pty_proxy_tmux_current"
+    exec atuin pty-proxy
   fi
 
-  unset _atuin_hex_tmux_current _atuin_hex_tmux_previous
+  unset _atuin_pty_proxy_tmux_current _atuin_pty_proxy_tmux_previous
 fi
 "#
         }
         Shell::Fish => {
             r#"if status is-interactive; and test -t 0; and test -t 1
-    set -l _atuin_hex_tmux_current ""
+    set -l _atuin_pty_proxy_tmux_current ""
     if set -q TMUX
-        set _atuin_hex_tmux_current "$TMUX"
+        set _atuin_pty_proxy_tmux_current "$TMUX"
     end
 
-    set -l _atuin_hex_tmux_previous ""
-    if set -q ATUIN_HEX_TMUX
-        set _atuin_hex_tmux_previous "$ATUIN_HEX_TMUX"
+    set -l _atuin_pty_proxy_tmux_previous ""
+    if set -q ATUIN_PTY_PROXY_TMUX
+        set _atuin_pty_proxy_tmux_previous "$ATUIN_PTY_PROXY_TMUX"
+    else if set -q ATUIN_HEX_TMUX
+        set _atuin_pty_proxy_tmux_previous "$ATUIN_HEX_TMUX"
     end
 
-    if not set -q ATUIN_HEX_ACTIVE
-        set -gx ATUIN_HEX_ACTIVE 1
-        set -gx ATUIN_HEX_TMUX "$_atuin_hex_tmux_current"
-        exec atuin hex
-    else if test "$_atuin_hex_tmux_current" != "$_atuin_hex_tmux_previous"
-        set -gx ATUIN_HEX_ACTIVE 1
-        set -gx ATUIN_HEX_TMUX "$_atuin_hex_tmux_current"
-        exec atuin hex
+    if not set -q ATUIN_PTY_PROXY_ACTIVE; and not set -q ATUIN_HEX_ACTIVE
+        set -gx ATUIN_PTY_PROXY_ACTIVE 1
+        set -gx ATUIN_PTY_PROXY_TMUX "$_atuin_pty_proxy_tmux_current"
+        exec atuin pty-proxy
+    else if test "$_atuin_pty_proxy_tmux_current" != "$_atuin_pty_proxy_tmux_previous"
+        set -gx ATUIN_PTY_PROXY_ACTIVE 1
+        set -gx ATUIN_PTY_PROXY_TMUX "$_atuin_pty_proxy_tmux_current"
+        exec atuin pty-proxy
     end
 end
 "#
         }
         // Nushell cannot dynamically source the output of `atuin init nu`,
-        // so we only output the hex preamble here. Users must also set up
+        // so we only output the pty-proxy preamble here. Users must also set up
         // `atuin init nu` separately.
         Shell::Nu => {
             r#"if (is-terminal --stdin) and (is-terminal --stdout) {
     let tmux_current = ($env.TMUX? | default "")
-    let tmux_previous = ($env.ATUIN_HEX_TMUX? | default "")
+    let tmux_previous = ($env.ATUIN_PTY_PROXY_TMUX? | default ($env.ATUIN_HEX_TMUX? | default ""))
 
-    if ($env.ATUIN_HEX_ACTIVE? | default "" | is-empty) or ($tmux_current != $tmux_previous) {
-        $env.ATUIN_HEX_ACTIVE = "1"
-        $env.ATUIN_HEX_TMUX = $tmux_current
-        exec atuin hex
+    if (($env.ATUIN_PTY_PROXY_ACTIVE? | default ($env.ATUIN_HEX_ACTIVE? | default "")) | is-empty) or ($tmux_current != $tmux_previous) {
+        $env.ATUIN_PTY_PROXY_ACTIVE = "1"
+        $env.ATUIN_PTY_PROXY_TMUX = $tmux_current
+        exec atuin pty-proxy
     }
 }
 "#
@@ -154,7 +156,7 @@ end
 #[cfg(not(unix))]
 mod app {
     pub(crate) fn main() {
-        eprintln!("atuin hex currently supports unix platforms");
+        eprintln!("atuin pty-proxy currently supports unix platforms");
         std::process::exit(1);
     }
 }
@@ -177,14 +179,14 @@ mod app {
     pub(crate) fn main() {
         if let Err(e) = run() {
             let _ = terminal::disable_raw_mode();
-            eprintln!("atuin hex: {e:#}");
+            eprintln!("atuin pty-proxy: {e:#}");
             std::process::exit(1);
         }
     }
 
     fn socket_path() -> std::path::PathBuf {
         let dir = std::env::temp_dir();
-        dir.join(format!("atuin-hex-{}.sock", std::process::id()))
+        dir.join(format!("atuin-pty-proxy-{}.sock", std::process::id()))
     }
 
     /// Wire format written to the Unix socket:
@@ -249,6 +251,7 @@ mod app {
 
         let mut cmd = CommandBuilder::new_default_prog();
         cmd.cwd(std::env::current_dir()?);
+        cmd.env("ATUIN_PTY_PROXY_SOCKET", sock_path.as_os_str());
         cmd.env("ATUIN_HEX_SOCKET", sock_path.as_os_str());
 
         let mut child = pair
@@ -304,7 +307,7 @@ mod app {
                 let listener = match UnixListener::bind(&sock_path_clone) {
                     Ok(l) => l,
                     Err(e) => {
-                        eprintln!("atuin hex: failed to bind socket: {e}");
+                        eprintln!("atuin pty-proxy: failed to bind socket: {e}");
                         return;
                     }
                 };
@@ -445,8 +448,8 @@ mod tests {
     #[test]
     fn posix_init_uses_exec_and_tmux_guard() {
         let script = render_init(Shell::Bash);
-        assert!(script.contains("exec atuin hex"));
-        assert!(script.contains("ATUIN_HEX_TMUX"));
+        assert!(script.contains("exec atuin pty-proxy"));
+        assert!(script.contains("ATUIN_PTY_PROXY_TMUX"));
         assert!(!script.contains("eval \"$(atuin init bash)\""));
     }
 
@@ -459,17 +462,17 @@ mod tests {
     #[test]
     fn fish_init_uses_source() {
         let script = render_init(Shell::Fish);
-        assert!(script.contains("exec atuin hex"));
+        assert!(script.contains("exec atuin pty-proxy"));
         assert!(!script.contains("atuin init fish | source"));
     }
 
     #[test]
     fn nu_init_uses_exec_and_tty_guard() {
         let script = render_init(Shell::Nu);
-        assert!(script.contains("exec atuin hex"));
-        assert!(script.contains("ATUIN_HEX_TMUX"));
+        assert!(script.contains("exec atuin pty-proxy"));
+        assert!(script.contains("ATUIN_PTY_PROXY_TMUX"));
         assert!(script.contains("is-terminal --stdin"));
         assert!(script.contains("is-terminal --stdout"));
-        assert!(script.contains("ATUIN_HEX_ACTIVE"));
+        assert!(script.contains("ATUIN_PTY_PROXY_ACTIVE"));
     }
 }

crates/atuin/Cargo.toml

@@ -33,12 +33,13 @@ buildflags = ["--release"]
 atuin = { path = "/usr/bin/atuin" }
 
 [features]
-default = ["client", "sync", "clipboard", "check-update", "daemon", "ai", "hex"]
+default = ["client", "sync", "clipboard", "check-update", "daemon", "ai", "pty-proxy"]
 client = ["atuin-client"]
 sync = ["atuin-client/sync"]
 daemon = ["atuin-client/daemon", "atuin-daemon"]
 ai = ["atuin-ai"]
-hex = ["atuin-hex"]
+pty-proxy = ["dep:atuin-pty-proxy"]
+hex = ["pty-proxy"]
 clipboard = ["arboard"]
 check-update = ["atuin-client/check-update"]
 
@@ -49,7 +50,7 @@ atuin-common = { workspace = true }
 atuin-dotfiles = { workspace = true }
 atuin-history = { workspace = true }
 atuin-daemon = { path = "../atuin-daemon", version = "18.16.0", optional = true, default-features = false }
-atuin-hex = { path = "../atuin-hex", version = "18.16.0", optional = true, default-features = false }
+atuin-pty-proxy = { path = "../atuin-pty-proxy", version = "18.16.0", optional = true, default-features = false }
 atuin-scripts = { workspace = true }
 atuin-kv = { workspace = true }
 

crates/atuin/src/command/client/search/interactive.rs

@@ -1377,7 +1377,7 @@ impl Drop for TerminalWriter {
     }
 }
 
-/// Screen state captured from atuin-hex's screen server.
+/// Screen state captured from atuin pty-proxy's screen server.
 #[cfg(unix)]
 struct SavedScreen {
     #[allow(dead_code)]
@@ -1390,7 +1390,7 @@ struct SavedScreen {
     rows_data: Vec<Vec<u8>>,
 }
 
-/// Connect to atuin-hex's Unix socket and fetch the current screen state.
+/// Connect to atuin pty-proxy's Unix socket and fetch the current screen state.
 ///
 /// The wire format is:
 /// ```text
@@ -1447,7 +1447,7 @@ fn fetch_screen_state(socket_path: &str) -> Option<SavedScreen> {
 
 /// Restore the screen area that was covered by the popup.
 ///
-/// Writes the pre-formatted per-row ANSI bytes received from atuin-hex
+/// Writes the pre-formatted per-row ANSI bytes received from atuin pty-proxy
 /// directly to stdout, which correctly handles wide characters, colors, and
 /// all text attributes without needing a client-side vt100 parser.
 #[cfg(unix)]
@@ -1629,11 +1629,13 @@ pub async fn history(
         inline_height
     };
 
-    // Popup mode: if running under atuin-hex and inline mode is requested,
+    // Popup mode: if running under atuin pty-proxy and inline mode is requested,
     // fetch the screen state and render as a centered overlay.
     #[cfg(unix)]
     let (saved_screen, popup_rect, popup_scroll_offset) = {
-        let socket_path = std::env::var("ATUIN_HEX_SOCKET").ok();
+        let socket_path = std::env::var("ATUIN_PTY_PROXY_SOCKET")
+            .or_else(|_| std::env::var("ATUIN_HEX_SOCKET"))
+            .ok();
         if let Some(ref path) = socket_path
             && inline_height > 0
         {

crates/atuin/src/command/mod.rs

@@ -21,11 +21,12 @@ pub enum AtuinCmd {
     #[command(flatten)]
     Client(client::Cmd),
 
-    /// Terminal emulator for atuin
-    #[cfg(feature = "hex")]
-    Hex {
+    /// PTY proxy for atuin
+    #[cfg(feature = "pty-proxy")]
+    #[command(alias = "hex")]
+    PtyProxy {
         #[command(subcommand)]
-        cmd: Option<atuin_hex::Cmd>,
+        cmd: Option<atuin_pty_proxy::Cmd>,
     },
 
     /// Generate a UUID
@@ -54,9 +55,9 @@ impl AtuinCmd {
             #[cfg(feature = "client")]
             Self::Client(client) => client.run(),
 
-            #[cfg(feature = "hex")]
-            Self::Hex { cmd } => {
-                atuin_hex::run(cmd);
+            #[cfg(feature = "pty-proxy")]
+            Self::PtyProxy { cmd } => {
+                atuin_pty_proxy::run(cmd);
                 Ok(())
             }
 

docs/docs/guide/installation.md

@@ -260,21 +260,21 @@ After installing, remember to restart your shell.
     source ~/.local/share/atuin/init.nu
     ```
 
-    ??? tip "Optional: Atuin Hex"
-        Hex is a lightweight pty proxy that renders the Atuin popup over
+    ??? tip "Optional: Atuin pty-proxy"
+        pty-proxy is a lightweight pty proxy that renders the Atuin popup over
         your previous output, restoring it when closed — no clearing, no
-        fullscreen. To use Hex with Nushell, generate the init script:
+        fullscreen. To use pty-proxy with Nushell, generate the init script:
 
         ```shell
         mkdir ~/.local/share/atuin/
-        atuin hex init nu | save -f ~/.local/share/atuin/hex-init.nu
+        atuin pty-proxy init nu | save -f ~/.local/share/atuin/pty-proxy-init.nu
         ```
 
         Then source it as early as possible in your `config.nu`, *before*
         the regular atuin init:
 
         ```shell
-        source ~/.local/share/atuin/hex-init.nu
+        source ~/.local/share/atuin/pty-proxy-init.nu
         source ~/.local/share/atuin/init.nu
         ```
 

docs/docs/reference/hex.md

@@ -1,65 +1 @@
-# hex
-
-Atuin Hex is an experimental lightweight PTY proxy, providing new features without needing to replace your existing terminal or shell. Atuin Hex currently supports bash, zsh, fish, and nu.
-
-## TUI Rendering
-
-The search TUI exposes a tradeoff: the UI is either in fullscreen alt-screen mode that takes over your terminal, or inline mode that clears your previous output. Neither is great.
-
-With Hex, we can have our cake AND eat it too. The Atuin popup renders over the top of your previous output, but when it's closed we can restore the output successfully.
-
-## Initialization
-
-Atuin Hex needs to be initialized separately from your existing Atuin config. Place the init line shown below in your shell's init script, as high in the document as possible, *before* your normal `atuin init` call.
-
-=== "zsh"
-
-    ```shell
-    eval "$(atuin hex init zsh)"
-    ```
-
-=== "bash"
-
-    ```shell
-    eval "$(atuin hex init bash)"
-    ```
-
-=== "fish"
-
-    Add
-
-    ```shell
-    atuin hex init fish | source
-    ```
-
-    to your `is-interactive` block in your `~/.config/fish/config.fish` file
-
-=== "Nushell"
-
-    Run in *Nushell*:
-
-    ```shell
-    mkdir ~/.local/share/atuin/
-    atuin hex init nu | save -f ~/.local/share/atuin/hex-init.nu
-    ```
-
-    Add to `config.nu`, **before** the regular `atuin init`:
-
-    ```shell
-    source ~/.local/share/atuin/hex-init.nu
-    ```
-    Nushell's `source` command requires a static file path, so you must
-    pre-generate the file.
-
----
-
-If the `atuin` binary is not in your `PATH` by default, you should initialize Hex as soon as it is set. For example, for a bash user with Atuin installed in `~/.atuin/bin/atuin`, a config file might look like this:
-
-```bash
-export PATH=$HOME/.atuin/bin:$PATH
-eval "$(atuin hex init bash)"
-
-# ... other shell configuration ...
-
-eval "$(atuin init bash)"
-```
+`atuin hex` has been renamed `atuin pty-proxy` as of Atuin v18.17.0.

docs/docs/reference/pty-proxy.md

@@ -0,0 +1,69 @@
+# pty-proxy
+
+Atuin pty-proxy is an experimental lightweight PTY proxy, providing new features without needing to replace your existing terminal or shell. It currently supports bash, zsh, fish, and nu.
+
+!!! Note "Previously `atuin hex`"
+
+    `atuin pty-proxy` is a replacement for the old `atuin hex` command. `atuin hex` still works for backward compatibility reasons, but will eventually be removed.
+
+## TUI Rendering
+
+The search TUI exposes a tradeoff: the UI is either in fullscreen alt-screen mode that takes over your terminal, or inline mode that clears your previous output. Neither is great.
+
+With pty-proxy, the Atuin popup renders over the top of your previous output, but when it's closed we can restore the output successfully.
+
+## Initialization
+
+Atuin pty-proxy needs to be initialized separately from your existing Atuin config. Place the init line shown below in your shell's init script, as high in the document as possible, _before_ your normal `atuin init` call.
+
+=== "zsh"
+
+    ```shell
+    eval "$(atuin pty-proxy init zsh)"
+    ```
+
+=== "bash"
+
+    ```shell
+    eval "$(atuin pty-proxy init bash)"
+    ```
+
+=== "fish"
+
+    Add
+
+    ```shell
+    atuin pty-proxy init fish | source
+    ```
+
+    to your `is-interactive` block in your `~/.config/fish/config.fish` file
+
+=== "Nushell"
+
+    Run in *Nushell*:
+
+    ```shell
+    mkdir ~/.local/share/atuin/
+    atuin pty-proxy init nu | save -f ~/.local/share/atuin/pty-proxy-init.nu
+    ```
+
+    Add to `config.nu`, **before** the regular `atuin init`:
+
+    ```shell
+    source ~/.local/share/atuin/pty-proxy-init.nu
+    ```
+    Nushell's `source` command requires a static file path, so you must
+    pre-generate the file.
+
+---
+
+If the `atuin` binary is not in your `PATH` by default, you should initialize pty-proxy as soon as it is set. For example, for a bash user with Atuin installed in `~/.atuin/bin/atuin`, a config file might look like this:
+
+```bash
+export PATH=$HOME/.atuin/bin:$PATH
+eval "$(atuin pty-proxy init bash)"
+
+# ... other shell configuration ...
+
+eval "$(atuin init bash)"
+```

docs/mkdocs.yml

@@ -75,7 +75,8 @@ plugins:
           - reference/daemon.md: Background daemon for faster writes, auto-sync, and in-memory fuzzy search.
           - reference/doctor.md: Diagnose common problems and dump system info for bug reports.
           - reference/gen-completions.md: Generate shell completions for bash, fish, zsh, nushell, powershell, elvish.
-          - reference/hex.md: Experimental PTY proxy with popup rendering over existing terminal output.
+          - reference/hex.md: The old name for `atuin pty-proxy`
+          - reference/pty-proxy.md: Experimental PTY proxy with popup rendering over existing terminal output.
           - reference/import.md: Import history from bash, fish, zsh, replxx, mcfly, resh, and xonsh.
           - reference/info.md: Show config file paths, env vars, and version info.
           - reference/list.md: List history entries with formatting, filtering by cwd/session, and custom output templates.
@@ -141,7 +142,7 @@ nav:
       - daemon: reference/daemon.md
       - doctor: reference/doctor.md
       - gen-completions: reference/gen-completions.md
-      - hex: reference/hex.md
+      - pty-proxy: reference/pty-proxy.md
       - import: reference/import.md
       - info: reference/info.md
       - history list: reference/list.md

scripts/release.sh

@@ -460,7 +460,7 @@ publish_crates() {
         atuin-server-postgres
         atuin-server-sqlite
         atuin-server
-        atuin-hex
+        atuin-pty-proxy
         atuin
     )