Buffer API

Query and manipulate buffer content, cursors, and metadata

The Buffer API provides methods for working with editor buffers - the in-memory representation of text files and virtual content.

Buffer Queries

getActiveBufferId

Get the buffer ID of the focused editor pane.

getActiveBufferId(): number

returns · number

The active buffer ID, or 0 if no buffer is active (rare edge case)

Example:

const bufferId = editor.getActiveBufferId();
editor.info(`Active buffer: ${bufferId}`);

getBufferPath

Get the absolute file path for a buffer.

getBufferPath(buffer_id: number): string

buffer_id · number · required

Target buffer ID

returns · string

Absolute file path, or empty string for unsaved buffers or virtual buffers

Example:

const path = editor.getBufferPath(bufferId);
if (path) {
  editor.info(`Buffer path: ${path}`);
}

getBufferLength

Get the total byte length of a buffer’s content.

getBufferLength(buffer_id: number): number

buffer_id · number · required

Target buffer ID

returns · number

Buffer length in bytes, or 0 if buffer doesn’t exist

isBufferModified

Check if a buffer has been modified since last save.

isBufferModified(buffer_id: number): boolean

buffer_id · number · required

Target buffer ID

returns · boolean

true if buffer has unsaved changes, false otherwise. Virtual buffers are never considered modified.

getBufferInfo

Get full information about a buffer.

getBufferInfo(buffer_id: number): BufferInfo | null

buffer_id · number · required

Buffer ID to query

returns · BufferInfo | null

Buffer information object, or null if buffer doesn’t exist

BufferInfo Type:

interface BufferInfo {
  id: number;           // Unique buffer ID
  path: string;         // File path (empty string if no path)
  modified: boolean;    // Whether buffer has unsaved changes
  length: number;       // Buffer length in bytes
}

listBuffers

List all open buffers.

listBuffers(): BufferInfo[]

returns · BufferInfo[]

Array of all open buffers

Example:

const buffers = editor.listBuffers();
editor.info(`Open buffers: ${buffers.length}`);
for (const buf of buffers) {
  editor.debug(`Buffer ${buf.id}: ${buf.path}`);
}

getBufferText

Get text from a buffer range.

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

buffer_id · number · required

Buffer ID

start · number · required

Start byte offset

end · number · required

End byte offset

returns · Promise<string>

Text content from the specified range

Example:

// Get first 100 bytes of buffer
const text = await editor.getBufferText(bufferId, 0, 100);
editor.debug(`First 100 bytes: ${text}`);

findBufferByPath

Find a buffer ID by its file path.

findBufferByPath(path: string): number

path · string · required

File path to search for

returns · number

Buffer ID if found, or 0 if not found

Cursor Operations

getCursorPosition

Get the byte offset of the primary cursor.

getCursorPosition(): number

returns · number

Byte offset of cursor, or 0 if no cursor. For multi-cursor, use getAllCursors.

This returns a byte offset, not a character index. Use this with insertText and deleteRange.

getCursorLine

Get the line number of the primary cursor (1-indexed).

getCursorLine(): number

returns · number

Line number starting at 1. Returns 1 if no cursor exists.

getPrimaryCursor

Get primary cursor with selection info.

getPrimaryCursor(): CursorInfo | null

returns · CursorInfo | null

Cursor information including position and selection, or null if no cursor

CursorInfo Type:

interface CursorInfo {
  position: number;                           // Byte position of the cursor
  selection: { start: number; end: number } | null;  // Selection range if text is selected
}

getAllCursors

Get all cursors (for multi-cursor support).

getAllCursors(): CursorInfo[]

returns · CursorInfo[]

Array of all cursors with position and selection info

getAllCursorPositions

Get byte offsets of all cursors.

getAllCursorPositions(): number[]

returns · number[]

Array of cursor positions. Empty if no cursors. Primary cursor is typically first.

setBufferCursor

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

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

buffer_id · number · required

ID of the buffer

position · number · required

Byte offset position for the cursor

returns · boolean

true if successful

Buffer Mutations

insertText

Insert text at a byte position in a buffer.

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

buffer_id · number · required

Target buffer ID

position · number · required

Byte offset where text will be inserted (must be at char boundary)

text · string · required

UTF-8 text to insert

returns · boolean

true if command was sent successfully. Operation is asynchronous.

Text is inserted before the byte at position. Position must be valid (0 to buffer length). Insertion shifts all text after position.

Example:

const bufferId = editor.getActiveBufferId();
const pos = editor.getCursorPosition();
editor.insertText(bufferId, pos, "Hello, world!");

insertAtCursor

Insert text at the current cursor position in the active buffer.

insertAtCursor(text: string): boolean

text · string · required

The text to insert

returns · boolean

true if successful

Example:

editor.insertAtCursor("// TODO: Implement this");

deleteRange

Delete a byte range from a buffer.

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

buffer_id · number · required

Target buffer ID

start · number · required

Start byte offset (inclusive)

end · number · required

End byte offset (exclusive)

returns · boolean

true if command was sent successfully. Operation is asynchronous.

Deletes bytes from start (inclusive) to end (exclusive). Both positions must be at valid UTF-8 char boundaries.

Buffer Display

showBuffer

Switch the current split to display a buffer.

showBuffer(buffer_id: number): boolean

buffer_id · number · required

ID of the buffer to show

returns · boolean

true if successful

closeBuffer

Close a buffer and remove it from all splits.

closeBuffer(buffer_id: number): boolean

buffer_id · number · required

ID of the buffer to close

returns · boolean

true if successful

openFile

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

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

path · string · required

File path to open

line · number · required

Line number to jump to (0 for no jump)

column · number · required

Column number to jump to (0 for no jump)

returns · boolean

true if successful

Example:

// Open file at specific line
editor.openFile("/path/to/file.rs", 42, 0);

// Just open file without jumping
editor.openFile("/path/to/file.rs", 0, 0);

openFileInSplit

Open a file in a specific split pane.

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

split_id · number · required

The split ID to open the file in

path · string · required

File path to open

line · number · required

Line number to jump to (0 for no jump)

column · number · required

Column number to jump to (0 for no jump)

returns · boolean

true if successful

Configuration

getConfig

Get the current editor configuration.

getConfig(): unknown

returns · unknown

Merged configuration (user config file + compiled-in defaults). This is the runtime config that the editor is actually using.

getUserConfig

Get the user’s configuration (only explicitly set values).

getUserConfig(): unknown

returns · unknown

Configuration from the user’s config file only. Fields not present here are using default values.

getConfigDir

Get the absolute path to the user config directory.

getConfigDir(): string

returns · string

Absolute path to config directory (e.g., ~/.config/fresh/ on Linux)

reloadConfig

Reload configuration from file.

reloadConfig(): void

After a plugin saves config changes to the config file, call this to reload the editor’s in-memory configuration.

Diagnostics

getAllDiagnostics

Get all LSP diagnostics across all files.

getAllDiagnostics(): TsDiagnostic[]

returns · TsDiagnostic[]

Array of all LSP diagnostics

TsDiagnostic Type:

interface TsDiagnostic {
  uri: string;          // File URI (e.g., "file:///path/to/file.rs")
  severity: number;     // 1=Error, 2=Warning, 3=Info, 4=Hint
  message: string;      // Diagnostic message
  source?: string | null;  // Source (e.g., "rust-analyzer")
  range: TsDiagnosticRange;  // Location range
}

Actions

executeAction

Execute a built-in editor action by name.

executeAction(action_name: string): boolean

action_name · string · required

Action name (e.g., “move_word_right”, “move_line_end”)

returns · boolean

true if successful

Example:

// Move cursor to end of word
editor.executeAction("move_word_right");

executeActions

Execute multiple actions in sequence, each with an optional repeat count.

executeActions(actions: ActionSpecJs[]): boolean

actions · ActionSpecJs[] · required

Array of action specifications

returns · boolean

true if successful

ActionSpecJs Type:

interface ActionSpecJs {
  action: string;
  count?: number | null;
}

Example:

// Delete 3 words
editor.executeActions([
  { action: "move_word_right", count: 3 },
  { action: "delete_selection" }
]);

Clipboard

setClipboard

Copy text to the system clipboard.

setClipboard(text: string): void

text · string · required

Text to copy to clipboard

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

Example:

const text = await editor.getBufferText(bufferId, start, end);
editor.setClipboard(text);
editor.setStatus("Copied to clipboard");