How Splice works

Shell (PTY)

Writes ANSI escape sequences and UTF-8 text to the PTY master. E.g. ESC[32mHello ESC[0m means "green text, then reset".

Rust — VTE parser (term.rs)

VTE calls GridPerformer for each byte sequence. Prints characters, moves cursor, applies colour/style attributes to the cell grid.

Rust — emitter.rs (~120fps)

Rate-limited thread wakes every ~8ms. If the grid changed, serialises it to a compact binary frame and base64-encodes it.

Header (20 bytes): cols, rows, cursor pos/style,
  mode flags, scrollback length, first visible row
Cells  (12 bytes each): codepoint u32, fg RGB,
  bg RGB, style flags, char width

Tauri event: terminal:grid:<id>

Frame emitted to the webview as a base64 string, targeted to the specific terminal ID.

renderer.ts — dirty-rect diff

Decodes base64 → Uint8Array. Compares each cell to the previous frame. Only repaints cells that changed — a huge win when most of the screen is static.

CanvasTerminal.svelte — canvas 2D

Paints changed cells using a colour string cache and ASCII char cache. Handles cursor blink, selection overlay, search highlights, scrollbar.

App.svelte — global keydown

⌘S fires the "save" action. Calls workspaceManager.saveActiveFile().

workspace-file-ops.ts

Resolves active workspace → active pane → active file path → OpenFile object. Reads file.content (kept in sync by CodeMirror on every keystroke). Marks file.dirty = false optimistically.

invoke("write_file") or invoke("sftp_write_file")

Local: write_file(path, content). SSH remote: sftp_write_file(workspaceId, path, content).

Rust — fs/write.rs

Validates path is within allowed roots. Writes to disk. The file watcher fires an fs:change event — the frontend ignores it if the content matches what was just saved.

CodeMirrorEditor.svelte

On file open, calls lspClient.ensureReady(filePath, content, wsRoot).

lspClient — lazy start + dedup

Maps file extension → language ID. Calls lsp_start if not running. A startPromises map ensures concurrent opens for the same language only start the server once.

Rust — lsp/mod.rs

Spawns e.g. typescript-language-server --stdio. Writer task → stdin, reader task parses stdout JSON-RPC:

Response (has id)       → wake the invoke() caller
Notification (push)     → emit as lsp:diagnostics event
Server request (both)   → answer inline

Tauri event: lsp:diagnostics

Frontend updates diagnosticsStore. CodeMirror's linter extension re-renders squiggles.

lsp-extensions.ts — CodeMirror

Completions via buildLspCompletionSource() calling textDocument/completion. Hover tooltips via buildHoverExtension().

Rust — on app startup

Generates or loads a 128-bit auth token. Binds a random TCP port; writes it to ~/.config/Splice/.attention_port. Installs versioned Python hook scripts into ~/.claude/settings.json.

Rust — PTY spawn

Every terminal gets SPLICE_TERMINAL_ID=<n> injected into its shell environment. This propagates to all child processes, including Claude.

Claude Code — hook fires

The installed Python script reads SPLICE_TERMINAL_ID from its env and the port from the file. POSTs to Splice's local HTTP server:

POST http://127.0.0.1:<port>/attention
Authorization: Bearer <token>
{ "terminal_id": 3, "type": "permission" }
{ "terminal_id": 3, "type": "idle" }

Tauri event: attention:notify

Rust validates the token and emits the payload to the frontend.

attentionStore + terminal tab UI

Stored by terminal ID. Terminal tab gets a badge. Permission requests show inline allow/deny. Idle shows a "done" indicator.

App.svelte — onMount

Calls workspaceManager.restoreWorkspaceImpl().

invoke("get_workspaces")

Rust reads the per-window JSON: workspaces.json for main, workspaces-{label}.json for secondary windows.

workspace-session.ts — deserialise

Remaps snake_case → camelCase. Reconstructs layout tree, pane configs, open file list. Reads each file from disk, detecting external edits.

invoke("spawn_terminal") per terminal

Respawns each saved terminal. waitForShellReady() polls terminal frames until cursor position is stable for 3 consecutive frames — the shell prompt has appeared. Then sends claude --resume <session_id>.

UI renders

Full layout restored: pinned tabs, split panes, expanded file tree folders, active pane, Claude sessions resuming.

SshConnectForm.svelte

User enters host/user/port/key/remotePath. Calls invoke("ssh_connect").

Rust — ssh.rs

Opens a persistent ControlMaster SSH session via the openssh crate. Stored in AppState::ssh_sessions[workspace_id]. All SFTP operations reuse this one TCP connection.

File ops via SFTP

sftp_list_dir runs a remote find command. sftp_read_file and sftp_write_file transfer full file contents over the existing SSH connection.

Terminal via SSH binary

spawn_terminal is called with extra args built from the SSH config. The shell is /usr/bin/ssh (on the allowed list). Same PTY + canvas renderer as local.

"cd '/remote/path' && exec $SHELL -l"