Buffer API

Buffer Queries

getThemeSchema

Get the theme JSON Schema for the theme editor Returns the raw JSON Schema generated by schemars for ThemeFile. The schema uses standard JSON Schema format with $ref for type references. Plugins are responsible for parsing the schema and resolving $ref references.

getThemeSchema(): unknown

getBuiltinThemes

getBuiltinThemes(): unknown

getConfig

Get the current editor configuration Returns the merged configuration (user config file + compiled-in defaults). This is the runtime config that the editor is actually using, including all default values for LSP servers, languages, keybindings, etc.

getConfig(): unknown

getUserConfig

Get the user's configuration (only explicitly set values) Returns only the configuration from the user's config file. Fields not present here are using default values. Use this with getConfig() to determine which values are defaults.

getUserConfig(): unknown

getConfigDir

Returns the absolute path to the user config directory (e.g., ~/.config/fresh/ on Linux).

getConfigDir(): string

getThemesDir

Get the user themes directory path Returns the absolute path to the directory where user themes are stored. e.g. ~/.config/fresh/themes/

getThemesDir(): string

getActiveBufferId

Get the buffer ID of the focused editor pane Returns 0 if no buffer is active (rare edge case). Use this ID with other buffer operations like insertText.

getActiveBufferId(): number

getCursorPosition

Returns 0 if no cursor. For multi-cursor, use getAllCursors. Note: byte offset, not character index.

getCursorPosition(): number

getBufferPath

Get the absolute file path for a buffer Returns empty string for unsaved buffers or virtual buffers. The path is always absolute. Use this to determine file type, construct related paths, or display to the user.

getBufferPath(buffer_id: number): string

Parameters:

getBufferLength

Get the total byte length of a buffer's content Returns 0 if buffer doesn't exist.

getBufferLength(buffer_id: number): number

Parameters:

isBufferModified

Check if a buffer has been modified since last save Returns false if buffer doesn't exist or has never been saved. Virtual buffers are never considered modified.

isBufferModified(buffer_id: number): boolean

Parameters:

getCurrentLocale

Get the currently active locale

getCurrentLocale(): string

getActiveSplitId

Get the ID of the focused split pane Use with focusSplit, setSplitBuffer, or createVirtualBufferInExistingSplit to manage split layouts.

getActiveSplitId(): number

getCursorLine

Get the line number of the primary cursor (1-indexed) Line numbers start at 1. Returns 1 if no cursor exists. For byte offset use getCursorPosition instead.

getCursorLine(): number

getAllCursorPositions

Get byte offsets of all cursors (multi-cursor support) Returns array of positions; empty if no cursors. Primary cursor is typically first. For selection info use getAllCursors instead.

getAllCursorPositions(): number[]

isProcessRunning

Check if a background process is still running

isProcessRunning(process_id: number): boolean

Parameters:

getHighlights

Compute syntax highlighting for a buffer range

getHighlights(buffer_id: number, start: number, end: number): Promise<TsHighlightSpan[]>

Parameters:

getBufferSavedDiff

Get diff vs last saved snapshot for a buffer

getBufferSavedDiff(buffer_id: number): TsBufferSavedDiff | null

Parameters:

getAllDiagnostics

Get all LSP diagnostics across all files

getAllDiagnostics(): TsDiagnostic[]

getBufferText

Get text from a buffer range Used by vi mode plugin for yank operations - reads text without deleting.

getBufferText(buffer_id: number, start: number, end: number): Promise<string>

Parameters:

getEditorMode

Get the current global editor mode

getEditorMode(): string

Buffer Info Queries

getBufferInfo

Get full information about a buffer

getBufferInfo(buffer_id: number): BufferInfo | null

Parameters:

listBuffers

List all open buffers

listBuffers(): BufferInfo[]

listGrammars

List all available grammars with source information. Returns grammars from all sources: built-in, user-installed, language packs, bundles, and plugin-registered.

listGrammars(): GrammarInfoSnapshot[]

Returns: Array of objects with:

getPrimaryCursor

Get primary cursor with selection info

getPrimaryCursor(): CursorInfo | null

getAllCursors

Get all cursors (for multi-cursor support)

getAllCursors(): CursorInfo[]

getViewport

Get viewport information

getViewport(): ViewportInfo | null

Prompt Operations

startPrompt

Start an interactive prompt

startPrompt(label: string, prompt_type: string): boolean

Parameters:

setPromptSuggestions

Set suggestions for the current prompt

setPromptSuggestions(suggestions: PromptSuggestion[]): boolean

Parameters:

setPromptTitle

Set the title shown in a floating-overlay prompt's frame header as styled segments. An empty array clears it and falls back to the prompt-type default.

setPromptTitle(title: StyledText[]): boolean

setPromptFooter

Set the footer chrome row of the floating-overlay prompt's results pane. Plugins use this for hotkey-hint banners — for example, the Orchestrator plugin renders ↑↓ preview Enter dive Esc close. Empty array clears the footer. Has no visible effect on non-overlay prompts.

setPromptFooter(footer: StyledText[]): boolean

Buffer Mutations

applyTheme

Apply a theme by name Loads and applies the specified theme immediately. The theme can be a built-in theme name or a custom theme from the themes directory.

applyTheme(theme_name: string): void

Parameters:

reloadConfig

Reload configuration from file After a plugin saves config changes to the config file, call this to reload the editor's in-memory configuration. This ensures the editor and plugins stay in sync with the saved config.

reloadConfig(): void

error

Log an error message from a plugin Messages appear in log file when running with RUST_LOG=error. Use for critical errors that need attention.

error(message: string): void

Parameters:

warn

Log a warning message from a plugin Messages appear in log file when running with RUST_LOG=warn. Use for warnings that don't prevent operation but indicate issues.

warn(message: string): void

Parameters:

info

Log an info message from a plugin Messages appear in log file when running with RUST_LOG=info. Use for important operational messages.

info(message: string): void

Parameters:

setClipboard

Copy text to the system clipboard Copies the provided text to both the internal and system clipboard. Uses OSC 52 and arboard for cross-platform compatibility.

setClipboard(text: string): void

Parameters:

insertText

Insert text at a byte position in a buffer Text is inserted before the byte at position. Position must be valid (0 to buffer length). Insertion shifts all text after position. Operation is asynchronous; returns true if command was sent successfully.

insertText(buffer_id: number, position: number, text: string): boolean

Parameters:

deleteRange

Delete a byte range from a buffer Deletes bytes from start (inclusive) to end (exclusive). Both positions must be at valid UTF-8 char boundaries. Operation is asynchronous; returns true if command was sent successfully.

deleteRange(buffer_id: number, start: number, end: number): boolean

Parameters:

clearNamespace

Clear all overlays in a namespace

clearNamespace(buffer_id: number, namespace: string): boolean

Parameters:

setLineNumbers

Enable/disable line numbers for a buffer

setLineNumbers(buffer_id: number, enabled: boolean): boolean

Parameters:

addVirtualLine

Add a virtual line above or below a source line

addVirtualLine(buffer_id: number, position: number, text: string, fg_r: number, fg_g: number, fg_b: number, bg_r: number, bg_g: number, bg_b: number, above: boolean, namespace: string, priority: number): boolean

Parameters:

setLineIndicator

Set a line indicator in the gutter's indicator column

setLineIndicator(buffer_id: number, line: number, namespace: string, symbol: string, r: number, g: number, b: number, priority: number): boolean

Parameters:

clearLineIndicators

Clear all line indicators for a specific namespace

clearLineIndicators(buffer_id: number, namespace: string): boolean

Parameters:

setFileExplorerDecorations

Set file explorer decorations for a namespace

setFileExplorerDecorations(namespace: string, decorations: FileExplorerDecoration[]): boolean

Parameters:

clearFileExplorerDecorations

Clear file explorer decorations for a namespace

clearFileExplorerDecorations(namespace: string): boolean

Parameters:

submitViewTransform

Submit a transformed view stream for a viewport

submitViewTransform(buffer_id: number, split_id?: number | null, start: number, end: number, tokens: ViewTokenWire[], layout_hints?: LayoutHints | null): boolean

Parameters:

clearViewTransform

Clear view transform for a buffer/split (returns to normal rendering)

clearViewTransform(buffer_id: number, split_id?: number | null): boolean

Parameters:

insertAtCursor

Insert text at the current cursor position in the active buffer

insertAtCursor(text: string): boolean

Parameters:

pluginTranslate

Translate a string for a plugin using the current locale

pluginTranslate(plugin_name: string, key: string, args: Record<string, unknown>): string

Parameters:

registerCommand

Register a command in the command palette (Ctrl+P).

Usually you should omit context so the command is always visible. If provided, the command is hidden unless your plugin has activated that context with editor.setContext(name, true) or the focused buffer's virtual mode (from defineMode()) matches.

registerCommand(name: string, description: string, handlerName: string, context?: string | null): boolean

Parameters:

unregisterCommand

Unregister a custom command by name

unregisterCommand(name: string): boolean

Parameters:

setContext

Set or unset a custom context for command visibility Custom contexts allow plugins to control when their commands are available. For example, setting "config-editor" context makes config editor commands visible.

setContext(name: string, active: boolean): boolean

Parameters:

openFile

Open a file in the editor, optionally at a specific location

openFile(path: string, line: number, column: number): boolean

Parameters:

openFileInSplit

Open a file in a specific split pane

openFileInSplit(split_id: number, path: string, line: number, column: number): boolean

Parameters:

spawnBackgroundProcess

Spawn a long-running background process Unlike spawnProcess which waits for completion, this starts a process in the background and returns immediately with a process ID. Use killProcess(id) to terminate the process later. Use isProcessRunning(id) to check if it's still running.

spawnBackgroundProcess(command: string, args: string[], cwd?: string | null): Promise<BackgroundProcessResult>

Parameters:

Example:

const proc = await editor.spawnBackgroundProcess("asciinema", ["rec", "output.cast"]);
// Later...
await editor.killProcess(proc.process_id);

killProcess

Kill a background or cancellable process by ID Sends SIGTERM to gracefully terminate the process. Returns true if the process was found and killed, false if not found.

killProcess(process_id: number): Promise<boolean>

Parameters:

spawnProcessWait

Wait for a cancellable process to complete and get its result

spawnProcessWait(process_id: number): Promise<SpawnResult>

Parameters:

delay

Delay execution for a specified number of milliseconds Useful for debouncing user input or adding delays between operations. await editor.delay(100); // Wait 100ms

delay(ms: number): Promise<void>

Parameters:

Example:

await editor.delay(100);  // Wait 100ms

findBufferByPath

Find a buffer ID by its file path

findBufferByPath(path: string): number

Parameters:

startPromptWithInitial

Start a prompt with pre-filled initial value

startPromptWithInitial(label: string, prompt_type: string, initial_value: string): boolean

Parameters:

deleteTheme

Delete a theme file by name Only deletes files from the user's themes directory. This is a safe operation that prevents plugins from deleting arbitrary files.

deleteTheme(name: string): Promise<void>

Parameters:

createCompositeBuffer

Create a composite buffer that displays multiple source buffers Composite buffers allow displaying multiple underlying buffers in a single tab/view area with custom layouts (side-by-side, stacked, unified). This is useful for diff views, merge conflict resolution, etc.

createCompositeBuffer(options: TsCreateCompositeBufferOptions): Promise<number>

Parameters:

updateCompositeAlignment

Update line alignment for a composite buffer

updateCompositeAlignment(buffer_id: number, hunks: TsCompositeHunk[]): boolean

Parameters:

closeCompositeBuffer

Close a composite buffer

closeCompositeBuffer(buffer_id: number): boolean

Parameters:

sendLspRequest

Send an arbitrary LSP request and receive the raw JSON response

sendLspRequest(language: string, method: string, params?: unknown | null): Promise<unknown>

Parameters:

setSplitScroll

Set the scroll position of a specific split

setSplitScroll(split_id: number, top_byte: number): boolean

Parameters:

setSplitRatio

Set the ratio of a split container

setSplitRatio(split_id: number, ratio: number): boolean

Parameters:

distributeSplitsEvenly

Distribute all visible splits evenly This adjusts the ratios of all container splits so each leaf split gets equal space

distributeSplitsEvenly(): boolean

setBufferCursor

Set cursor position in a buffer (also scrolls viewport to show cursor)

setBufferCursor(buffer_id: number, position: number): boolean

Parameters:

executeAction

Execute a built-in editor action by name This is used by vi mode plugin to run motions and then check cursor position. For example, to implement "dw" (delete word), the plugin:

1. Saves current cursor position
2. Calls executeAction("move_word_right") - cursor moves
3. Gets new cursor position
4. Deletes from old to new position

executeAction(action_name: string): boolean

Parameters:

executeActions

Execute multiple actions in sequence, each with an optional repeat count Used by vi mode for count prefix (e.g., "3dw" = delete 3 words). All actions execute atomically with no plugin roundtrips between them.

executeActions(actions: ActionSpecJs[]): boolean

Parameters:

setEditorMode

Set the global editor mode (for modal editing like vi mode) When a mode is set, its keybindings take precedence over normal key handling. Pass null/undefined to clear the mode and return to normal editing.

setEditorMode(mode?: string | null): boolean

Parameters:

showActionPopup

Show an action popup with buttons for user interaction When the user selects an action, the ActionPopupResult hook is fired.

showActionPopup(options: TsActionPopupOptions): boolean

Parameters:

disableLspForLanguage

Disable LSP for a specific language and persist to config This is used by LSP helper plugins to let users disable LSP for languages where the server is not available or not working.

disableLspForLanguage(language: string): boolean

Parameters:

createScrollSyncGroup

Create a scroll sync group for anchor-based synchronized scrolling Used for side-by-side diff views where two panes need to scroll together. The plugin provides the group ID (must be unique per plugin).

createScrollSyncGroup(group_id: number, left_split: number, right_split: number): boolean

Parameters:

setScrollSyncAnchors

Set sync anchors for a scroll sync group Anchors map corresponding line numbers between left and right buffers. Each anchor is a tuple of (left_line, right_line).

setScrollSyncAnchors(group_id: number, anchors: [number, number][]): boolean

Parameters:

removeScrollSyncGroup

Remove a scroll sync group

removeScrollSyncGroup(group_id: number): boolean

Parameters:

Windows / Orchestrator API

A window (modelled on a VS Code window) is a project-rooted bundle of editor state — file explorer, LSP set, file watchers, split layout, and buffer membership — that can be swapped in and out as a unit. The "base" window at startup is WindowId(1). Subsequent windows are created by plugins (typically the first-party Orchestrator plugin, which uses windows to drive parallel-agent worktrees).

Naming note. Internally the editor calls these "windows" to disambiguate from Fresh's pre-existing workspace-recovery and config-layer "session" concepts. Orchestrator's UX still presents them as "agent sessions" because that's the parallel-agents domain language users see. Plugin API names all use Window / windowId.

See docs/internal/orchestrator-sessions-design.md for the full architecture rationale.

createWindow

Allocate a new session rooted at root with the given label. Does not switch to it — call setActiveWindow to dive. Returns the new session's id.

createWindow(root: string, label: string): Promise<number>

setActiveWindow

Make id the active session. The previous active session's state (file explorer, LSP set, splits, view states) is stashed on its Session and the incoming session's stash is swapped into the editor — O(1), no buffer recreation, no LSP restart.

setActiveWindow(id: number): boolean

closeWindow

Close a session. Buffers attached only to this session are dropped; shared buffers stay open. Closing the active session falls back to the base session.

closeWindow(id: number): boolean

listWindows

Snapshot of every session with its id, label, and root.

listWindows(): WindowInfo[]

activeWindow

Return the currently active session id.

activeWindow(): number

prewarmWindow

Spin up the session's LSP set + split layout in the background, without diving. The first dive into a prewarmed session is then instant. Useful when a plugin knows the user will likely visit a session soon.

prewarmWindow(id: number): boolean

previewWindowInRect

Render the entire stashed UI of session id (splits, terminals, syntax-highlighted buffers, decorations) into the floating-overlay prompt's preview pane on the next frame. Cleared automatically when the prompt closes; call clearWindowPreview to clear earlier.

This is Primitive #1 of the Orchestrator design and is the mechanism the Orchestrator plugin uses to show a live preview of the highlighted session as the user moves the selection in the session list.

previewWindowInRect(id: number): boolean

clearWindowPreview

Clear an earlier previewWindowInRect so the preview pane falls back to the prompt's default behaviour.

clearWindowPreview(): boolean

setWindowState / getWindowState

Per-session, per-plugin state map. Like setGlobalState but scoped to a single session — useful for plugin state that should follow a session across saves/restores rather than applying globally. Persists to .fresh/sessions.json.

setWindowState(key: string, value: unknown): boolean
getWindowState(key: string): unknown | null

openFileInBackground

Open a file without switching to it. With opts.windowId, the buffer is attached to that session's stashed tab strip instead of the active session's. Pairs with createTerminal's windowId for setting up an inactive session's contents without diving.

openFileInBackground(path: string, opts?: { windowId?: number }): Promise<number>

watchPath / unwatchPath

Subscribe to filesystem changes under path. Returns a handle. Each change fires a path_changed hook with the handle id, the changed path, and the change kind. Releases via unwatchPath(handle).

watchPath(path: string): Promise<number>
unwatchPath(handle: number): boolean

Terminal API

createTerminal

Create a new terminal in a split. Returns a TerminalResult with buffer, terminal, and split IDs.

When opts.windowId is set the terminal attaches to that session's stashed split tree without diving — the user's current view stays put and the terminal becomes visible only when the user dives into the named session. This is how Orchestrator spawns agents into background worktrees without disturbing the foreground session.

createTerminal(opts?: CreateTerminalOptions): Promise<TerminalResult>

Parameters:

sendTerminalInput

Send input data to a terminal by its terminal ID.

sendTerminalInput(terminalId: number, data: string): boolean

Parameters:

closeTerminal

Close a terminal by its terminal ID.

closeTerminal(terminalId: number): boolean

Parameters: