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.
TUI Rendering
Section titled “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, pty-proxy restores the output successfully.
Capturing command output
Section titled “Capturing command output”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.
Initialization
Section titled “Initialization”The simplest way to enable pty-proxy is via your Atuin config (~/.atuin/config.toml) — no extra shell config needed:
[pty_proxy]enabled = trueWith 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.
eval "$(atuin pty-proxy init zsh)"eval "$(atuin pty-proxy init bash)"Add
atuin pty-proxy init fish | sourceto your is-interactive block in your ~/.config/fish/config.fish file
Run in Nushell:
mkdir ~/.atuin/atuin pty-proxy init nu | save -f ~/.atuin/pty-proxy-init.nuAdd to config.nu, before the regular atuin init:
source ~/.atuin/pty-proxy-init.nuNushell’s source command requires a static file path, so you must
pre-generate the file.
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:
export PATH=$HOME/.atuin/bin:$PATHeval "$(atuin pty-proxy init bash)"
# ... other shell configuration ...
eval "$(atuin init bash)"