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

Get the user configuration directory path Returns the absolute path to the directory where user config and themes are stored. e.g. ~/.config/fresh/ on Linux or ~/Library/Application Support/fresh/ on macOS.

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

Get the byte offset of the primary cursor in the active buffer Returns 0 if no cursor exists. For multi-cursor scenarios, use getAllCursors to get all cursor positions with selection info. Note: This is a byte offset, not a character index (UTF-8 matters).

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:

Name	Type	Description
buffer_id	number	Target buffer ID

getBufferLength

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

getBufferLength(buffer_id: number): number

Parameters:

Name	Type	Description
buffer_id	number	Target buffer ID

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:

Name	Type	Description
buffer_id	number	Target buffer ID

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:

Name	Type	Description
process_id	number	ID returned from spawnBackgroundProcess

getHighlights

Compute syntax highlighting for a buffer range

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

Parameters:

Name	Type	Description
buffer_id	number	-
start	number	-
end	number	-

getBufferSavedDiff

Get diff vs last saved snapshot for a buffer

getBufferSavedDiff(buffer_id: number): TsBufferSavedDiff | null

Parameters:

Name	Type	Description
buffer_id	number	-

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:

Name	Type	Description
buffer_id	number	Buffer ID
start	number	Start byte offset
end	number	End byte offset

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:

Name	Type	Description
buffer_id	number	Buffer ID

listBuffers

List all open buffers

listBuffers(): BufferInfo[]

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:

Name	Type	Description
label	string	Label to display (e.g., "Git grep: ")
prompt_type	string	Type identifier (e.g., "git-grep")

setPromptSuggestions

Set suggestions for the current prompt

setPromptSuggestions(suggestions: PromptSuggestion[]): boolean

Parameters:

Name	Type	Description
suggestions	PromptSuggestion[]	Array of suggestions to display

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:

Name	Type	Description
theme_name	string	Name of the theme to apply (e.g., "dark", "light", "my-custom-theme")

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:

Name	Type	Description
message	string	Error message

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:

Name	Type	Description
message	string	Warning message

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:

Name	Type	Description
message	string	Info message

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:

Name	Type	Description
text	string	Text to copy to clipboard

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:

Name	Type	Description
buffer_id	number	Target buffer ID
position	number	Byte offset where text will be inserted (must be at char boundary)
text	string	UTF-8 text to insert

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:

Name	Type	Description
buffer_id	number	Target buffer ID
start	number	Start byte offset (inclusive)
end	number	End byte offset (exclusive)

clearNamespace

Clear all overlays in a namespace

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

Parameters:

Name	Type	Description
buffer_id	number	The buffer ID
namespace	string	The namespace to clear

setLineNumbers

Enable/disable line numbers for a buffer

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

Parameters:

Name	Type	Description
buffer_id	number	The buffer ID
enabled	boolean	Whether to show line numbers

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:

Name	Type	Description
buffer_id	number	The buffer ID
position	number	Byte position to anchor the virtual line to
text	string	The text content of the virtual line
fg_r	number	Foreground red color component (0-255)
fg_g	number	Foreground green color component (0-255)
fg_b	number	Foreground blue color component (0-255)
bg_r	number	Background red color component (0-255), -1 for transparent
bg_g	number	Background green color component (0-255), -1 for transparent
bg_b	number	Background blue color component (0-255), -1 for transparent
above	boolean	Whether to insert above (true) or below (false) the line
namespace	string	Namespace for bulk removal (e.g., "git-blame")
priority	number	Priority for ordering multiple lines at same position

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:

Name	Type	Description
buffer_id	number	The buffer ID
line	number	Line number (0-indexed)
namespace	string	Namespace for grouping (e.g., "git-gutter", "breakpoints")
symbol	string	Symbol to display (e.g., "│", "●", "★")
r	number	Red color component (0-255)
g	number	Green color component (0-255)
b	number	uffer_id - The buffer ID
priority	number	Priority for display when multiple indicators exist (higher wins)

clearLineIndicators

Clear all line indicators for a specific namespace

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

Parameters:

Name	Type	Description
buffer_id	number	The buffer ID
namespace	string	Namespace to clear (e.g., "git-gutter")

setFileExplorerDecorations

Set file explorer decorations for a namespace

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

Parameters:

Name	Type	Description
namespace	string	Namespace for grouping (e.g., "git-status")
decorations	FileExplorerDecoration[]	Decoration entries

clearFileExplorerDecorations

Clear file explorer decorations for a namespace

clearFileExplorerDecorations(namespace: string): boolean

Parameters:

Name	Type	Description
namespace	string	Namespace to clear (e.g., "git-status")

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:

Name	Type	Description
buffer_id	number	Buffer to apply the transform to
split_id	`number	null` (optional)
start	number	Viewport start byte
end	number	Viewport end byte
tokens	ViewTokenWire[]	Array of tokens with source offsets
layout_hints	`LayoutHints	null` (optional)

clearViewTransform

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

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

Parameters:

Name	Type	Description
buffer_id	number	Buffer ID
split_id	`number	null` (optional)

insertAtCursor

Insert text at the current cursor position in the active buffer

insertAtCursor(text: string): boolean

Parameters:

Name	Type	Description
text	string	The text to insert

pluginTranslate

Translate a string for a plugin using the current locale

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

Parameters:

Name	Type	Description
plugin_name	string	-
key	string	-
args	Record<string, unknown>	-

registerCommand

Register a custom command that can be triggered by keybindings or the command palette

registerCommand(name: string, description: string, action: string, contexts: string, source: string): boolean

Parameters:

Name	Type	Description
name	string	-
description	string	-
action	string	-
contexts	string	-
source	string	-

unregisterCommand

Unregister a custom command by name

unregisterCommand(name: string): boolean

Parameters:

Name	Type	Description
name	string	The name of the command to unregister

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:

Name	Type	Description
name	string	Context name (e.g., "config-editor")
active	boolean	Whether the context is active (true = set, false = unset)

openFile

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

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

Parameters:

Name	Type	Description
path	string	File path to open
line	number	Line number to jump to (0 for no jump)
column	number	Column number to jump to (0 for no jump)

openFileInSplit

Open a file in a specific split pane

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

Parameters:

Name	Type	Description
split_id	number	The split ID to open the file in
path	string	File path to open
line	number	Line number to jump to (0 for no jump)
column	number	Column number to jump to (0 for no jump)

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. const proc = await editor.spawnBackgroundProcess("asciinema", ["rec", "output.cast"]); // Later... await editor.killProcess(proc.process_id);

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

Parameters:

Name	Type	Description
command	string	Program name (searched in PATH) or absolute path
args	string[]	Command arguments (each array element is one argument)
cwd	`string	null` (optional)

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:

Name	Type	Description
process_id	number	ID returned from spawnBackgroundProcess or spawnProcessStart

spawnProcessWait

Wait for a cancellable process to complete and get its result

spawnProcessWait(process_id: number): Promise<SpawnResult>

Parameters:

Name	Type	Description
process_id	number	ID returned from spawnProcessStart

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:

Name	Type	Description
ms	number	Number of milliseconds to delay

Example:

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

findBufferByPath

Find a buffer ID by its file path

findBufferByPath(path: string): number

Parameters:

Name	Type	Description
path	string	-

startPromptWithInitial

Start a prompt with pre-filled initial value

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

Parameters:

Name	Type	Description
label	string	Label to display (e.g., "Git grep: ")
prompt_type	string	Type identifier (e.g., "git-grep")
initial_value	string	Initial text to pre-fill in the prompt

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:

Name	Type	Description
name	string	Theme name (without .json extension)

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: CreateCompositeBufferOptions): Promise<number>

Parameters:

Name	Type	Description
options	CreateCompositeBufferOptions	Configuration for the composite buffer

updateCompositeAlignment

Update line alignment for a composite buffer

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

Parameters:

Name	Type	Description
buffer_id	number	The composite buffer ID
hunks	TsCompositeHunk[]	New diff hunks for alignment

closeCompositeBuffer

Close a composite buffer

closeCompositeBuffer(buffer_id: number): boolean

Parameters:

Name	Type	Description
buffer_id	number	The composite buffer ID to close

sendLspRequest

Send an arbitrary LSP request and receive the raw JSON response

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

Parameters:

Name	Type	Description
language	string	Language ID (e.g., "cpp")
method	string	Full LSP method (e.g., "textDocument/switchSourceHeader")
params	`unknown	null` (optional)

setSplitScroll

Set the scroll position of a specific split

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

Parameters:

Name	Type	Description
split_id	number	The split ID
top_byte	number	The byte offset of the top visible line

setSplitRatio

Set the ratio of a split container

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

Parameters:

Name	Type	Description
split_id	number	ID of the split
ratio	number	Ratio between 0.0 and 1.0 (0.5 = equal split)

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:

Name	Type	Description
buffer_id	number	ID of the buffer
position	number	Byte offset position for the cursor

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:

Name	Type	Description
action_name	string	Action name (e.g., "move_word_right", "move_line_end")

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:

Name	Type	Description
actions	ActionSpecJs[]	Array of {action: string, count?: number} objects

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:

Name	Type	Description
mode	`string	null` (optional)

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:

Name	Type	Description
options	TsActionPopupOptions	Popup configuration with id, title, message, and actions

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:

Name	Type	Description
language	string	The language to disable LSP for (e.g., "python", "rust")

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:

Name	Type	Description
group_id	number	-
left_split	number	-
right_split	number	-

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:

Name	Type	Description
group_id	number	-
anchors	[number, number][]	-

removeScrollSyncGroup

Remove a scroll sync group

removeScrollSyncGroup(group_id: number): boolean

Parameters:

Name	Type	Description
group_id	number	-