pterm

Persistent terminal sessions for Neovim.

Processes survive Neovim restarts. Terminal rendering is delegated to Neovim's native terminal (jobstart(..., { term = true })) while pterm keeps PTY processes alive.

CLI

# Create a new persistent session (forks into background)
pterm new mysession
pterm new mysession -- /bin/zsh        # custom command

# Attach bridge mode (for terminal clients)
pterm attach mysession

# Attach if exists, otherwise create and attach
pterm open mysession
pterm open mysession -- /bin/zsh

# List active sessions (optionally filter by prefix)
pterm list
pterm list myprefix

# Get socket path for a session
pterm socket mysession

# Redraw terminal (resend snapshot to all clients)
pterm redraw mysession

# Print diagnostic state dump as JSON
pterm dump mysession

# Print the visible screen as plain text
pterm snapshot-text mysession

# Print the visible screen with ANSI colors/attributes preserved
pterm snapshot-ansi mysession

# Kill a session
pterm kill mysession

Session names may contain / for hierarchical sessions. Killing a parent session also kills all children.

pterm new parent
pterm new parent/child
pterm kill parent          # kills parent and parent/child

Neovim Usage

:Pterm new dev      " opens/creates named session
:Pterm new dev zsh  " opens/creates session with custom command
:Pterm list         " list sessions
:Pterm redraw dev   " redraw a session
:Pterm dump dev     " open diagnostic state dump as JSON
:Pterm kill dev     " kill a session

pterm opens a terminal buffer backed by jobstart({ "pterm", "attach", <name> }, { term = true }).

The Lua module also exports functions for programmatic use: open, attach, detach, list, kill, redraw, dump.

Requirements

• Neovim 0.10+
• Nix (with flakes enabled)
• Linux / macOS

Install

This plugin is designed to be installed via Nix flakes. Add pterm as a flake input and include it in your Neovim plugin list.

Flake input

{
  inputs = {
    pterm.url = "github:ttak0422/pterm";
  };
}

Neovim plugin

Add inputs.pterm.packages.${system}.pterm to your Neovim plugin list and call setup().

require("pterm").setup()


-- Default configuration:
require("pterm").setup({
  -- Default shell command
  shell = vim.env.SHELL or "/bin/sh",
  -- Socket directory (nil = let daemon decide)
  socket_dir = nil,
  -- Automatically redraw on BufEnter / TermEnter to recover from rendering
  -- corruption that can occur during mode or window focus switches.
  auto_redraw = true,
  -- Cooldown window in milliseconds for automatic redraws. The first
  -- BufEnter / TermEnter redraw fires immediately; repeated events are
  -- suppressed until the cooldown expires.
  auto_redraw_delay_ms = 1000,
})

Telescope Extension

pterm provides an optional Telescope extension for fuzzy-finding sessions.

-- Call after telescope.setup()
require("telescope").load_extension("pterm")

:Telescope pterm sessions

Each session is shown as <name> (<directory>), where the directory is the basename of the session shell's current working directory. The daemon tracks cd inside the session and refreshes it periodically. Connected sessions are marked with a ✔ prefix. The preview pane shows the tail of each session's current terminal screen, trimmed to the preview width, with colors and attributes preserved as highlighting. If no existing session matches the current Telescope query, pressing Enter creates or opens a session using the prompt text as the session name.

For full-text search across every session's contents — scrollback history included — use:

:Telescope pterm grep

Each non-empty line is shown as <session>: <line>; pressing Enter opens the session containing the selected line. Lines that wrapped in the terminal are re-joined before matching, so text spanning a wrap point stays searchable. Sessions currently showing a full-screen TUI (the alternate screen, e.g. less or htop) contribute only their visible screen, not their shell scrollback.

License

MIT