Skip to content
Atuin

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. See Supported platforms for support tiers.

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, pty-proxy restores the output successfully.

Because pty-proxy sits between your terminal and your shell, it can also record what each command printed. It reads special escape sequences1 emitted by Atuin’s shell integration to tell where one command’s output ends and the next begins. It then hands each captured block to the daemon, which holds it on disk, keyed by the command’s Atuin history ID.

That capture is what lets AI tools see what actually happened, rather than guessing from the command alone:

  • Agents such as Claude Code and Cursor can answer “why did that fail?” by reading the real error through Atuin’s MCP server

Output capture needs both pty-proxy and the daemon running. Nothing is captured by default. See Capturing Command Output for setup, retention limits, and privacy.

The simplest way to enable pty-proxy is via your Atuin config (~/.atuin/config.toml) — no extra shell config needed:

[pty_proxy]
enabled = true

With this set, your existing atuin init line starts the proxy automatically.

Alternatively, you can initialize pty-proxy explicitly in your shell config. Place the init line shown below as high in the document as possible, before your normal atuin init call. Both methods can coexist safely — the proxy only starts once.

Terminal window
eval "$(atuin pty-proxy init zsh)"

If the atuin binary isn’t in your PATH by default, you should initialize pty-proxy as soon as it’s set. For example, for a bash user with Atuin installed in ~/.atuin/bin/atuin, a config file might look like this:

Terminal window
export PATH=$HOME/.atuin/bin:$PATH
eval "$(atuin pty-proxy init bash)"
# ... other shell configuration ...
eval "$(atuin init bash)"
  1. Atuin uses custom OSC escape sequences that begin with OSC 18188735. 18188735 is atuin interpreted as a base-36 number; it was chosen to minimize conflicts with other programs and terminals. ↩