User guide / Workspaces and persistent sessions

External editor requests (`--wait`)

Development reference · View source

For tools that need an editor process to stay open until you finish, use runyte --wait:

git config core.editor 'runyte --wait'

That gives Git commit and rebase message files this lifecycle. On Unix, persistent hosting and --wait use a private, versioned local protocol: a bundled-client contract, not a public automation API.

On Unix

runyte --wait file… opens the files in a persistent session and returns success only after every requested buffer is closed or completed.

Where the file appears:

• It reuses a matching buffer in an existing host. A clean buffer left by an earlier completed wait is refreshed from disk first. Unsaved text and buffers owned by a pending wait are never replaced.
• If the host already has a TUI, the file appears there while the caller waits. If that TUI detaches first, the calling terminal takes over.
• If no host exists, Runyte starts one and attaches the calling terminal, so the request is never invisible.
• The buffer opens in Normal mode, even if the session was in Insert mode, so : commands work at once.
• If the pane was showing an integrated terminal — usually the one running the program that asked — the terminal is covered, not given up. Finishing with :q, :q!, :wq, :close, or :wbc shows that terminal again in the same pane. Navigating the pane to another document first ends the detour, after which :q closes the pane as usual.

Finishing:

• Dirty buffers keep the usual save/discard protection.
• Detaching the wait-owned TUI cancels the request.
• Losing the calling terminal or process cancels it, whether the client is queued behind another TUI or has taken over.
• Lifecycle loss, explicit cancellation, and host failure all exit nonzero.

On Windows

From an ordinary shell, runyte --wait opens the files in the current project’s persistent session, starting it if needed.

• With no attached TUI, the calling terminal attaches. With another TUI active, the caller waits for its buffers there and can take over after that TUI detaches.
• Each requested buffer must complete before the caller resumes. :wbc saves and closes one buffer; :q can finish a clean wait.
• Discard, detach, terminal loss, or loss of the launching process cancels it.
• The session is held by its exact publication throughout, so a second live publication for the same path is refused as ambiguous.

From an integrated terminal

Programs in an integrated terminal can use EDITOR='runyte --wait' and VISUAL='runyte --wait'. Their files open as ordinary buffers in the parent persistent session, even from another working directory or a temporary path.

• Relative files resolve from the calling terminal’s directory.
• The origin terminal is covered while the edit is active and restored after.
• The caller resumes only after every requested file completes; closing one of several keeps it waiting.
• The parent host authenticates the exact terminal process and attachment. A copied, stale, or ide-mode parent marker is refused.
• Completion and refusal never submit Enter or approve an editor prompt.

• A failed save leaves the edit open.
• Navigation and splits keep request ownership; unrelated buffers keep ordinary quit behavior.
• Switching sessions keeps the request pending in its host. Explicit detach or loss of the caller cancels it; buffers are kept and no nested TUI takes over the terminal.

Environment in new terminals. New persistent terminals add --wait to inherited EDITOR and VISUAL values that name bare runyte (including a quoted executable path). Other editors, and commands with explicit arguments, keep their setting. Existing shells and programs keep their old environment: set both variables to runyte --wait before restarting such a program, or open a new terminal. Ordinary runyte <file> commands in a shell launch as usual.