CLI control plane

Voktty bundles a small native helper exposed as the voktty command inside application terminal panes. The app must already be running.

Commands

voktty <file> [--line <n>] [--no-focus] [--json]
voktty open <file> [--line <n>] [--no-focus] [--json]
voktty ping [--json]
voktty capabilities [--json]
voktty identify [--json]

When a command is launched inside a Voktty pane, the caller pane's space and workspace are the target. An external client without pane context falls back to the active UI context.

Transport

The app binds an ephemeral loopback TCP listener and writes a discovery descriptor under the user cache directory at voktty/control.json. The descriptor contains protocol version, address, process id, app version and a random 256-bit token.

Requests are newline-delimited JSON. The control server binds only to 127.0.0.1, limits messages to 64 KiB, caps active connections and applies bounded read, write and UI response timeouts. Every request carries the token and unauthenticated requests are rejected with constant-time comparison.

File paths are canonicalized and must point to a regular file inside an authorized workspace before the editor opens them.

Shell discovery

The packaged helper is named voktty-cli because the macOS application executable is already named voktty. At startup, Voktty creates a private per-process bin/voktty link or copy and prepends that directory to the PTY PATH. Shell integration also exposes a voktty function that calls the helper.

Current limits

  • WSL panes do not yet receive the control credentials and launcher.
  • The CLI does not start a stopped Voktty process.
  • There is no global installer for external terminals.
  • Split, tab, agent, screen-read and input commands are not part of protocol version 1.

Unsupported paths fail as unavailable rather than silently targeting a different pane.

Extending the protocol

  1. Add typed method and parameter definitions to src-tauri/crates/voktty-control-protocol.
  2. Validate authentication, protocol version, bounds and paths in Rust.
  3. Keep OS-only work in Rust and route only React state changes to the frontend.
  4. Resolve the explicit caller pane before falling back to active UI state.
  5. Keep --json responses structured and stable.
  6. Add parser, routing, platform and size tests.