Buffer API - Fresh

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");

API Reference

Guides

​Buffer Queries

​getActiveBufferId

​getBufferPath

​getBufferLength

​isBufferModified

​getBufferInfo

​listBuffers

​getBufferText

​findBufferByPath

​Cursor Operations

​getCursorPosition

​getCursorLine

​getPrimaryCursor

​getAllCursors

​getAllCursorPositions

​setBufferCursor

​Buffer Mutations

​insertText

​insertAtCursor

​deleteRange

​Buffer Display

​showBuffer

​closeBuffer

​openFile

​openFileInSplit

​Configuration

​getConfig

​getUserConfig

​getConfigDir

​reloadConfig

​Diagnostics

​getAllDiagnostics

​Actions

​executeAction

​executeActions

​Clipboard

​setClipboard

Build docs developers (and LLMs) love

Buffer Queries

getActiveBufferId

getBufferPath

getBufferLength

isBufferModified

getBufferInfo

listBuffers

getBufferText

findBufferByPath

Cursor Operations

getCursorPosition

getCursorLine

getPrimaryCursor

getAllCursors

getAllCursorPositions

setBufferCursor

Buffer Mutations

insertText

insertAtCursor

deleteRange

Buffer Display

showBuffer

closeBuffer

openFile

openFileInSplit

Configuration

getConfig

getUserConfig

getConfigDir

reloadConfig

Diagnostics

getAllDiagnostics

Actions

executeAction

executeActions

Clipboard

setClipboard