API Reference

API Reference

Extensions access the runtime through the global sigma object after activation.

Lifecycle

Code-based extensions export activate(context) and may optionally export deactivate().

API extensions that run code use standard ESM exports. Manifest-only theme and icon theme extensions can omit the entry module.

Activation Events

Event	Description
onStartup	Runs when the app starts and the extension is enabled
onInstall	Runs after installation
onUninstall	Runs before removal
onEnable	Runs when the extension is enabled
onDisable	Runs when the extension is disabled
onUpdate	Runs after an update
onLocaleChange	Runs when the app UI language changes
onCommand:commandId	Runs when a specific command triggers activation

Activation Context

Property	Description
extensionId	Unique extension identifier
extensionPath	Absolute path to the extension directory
storagePath	Extension-specific persistent storage directory
activationEvent	The event that triggered activation

Most registration methods return a Disposable. Disposables are cleaned up automatically when the extension is disabled or uninstalled.

API Surface

Namespace	Purpose
sigma.commands	Register and execute commands
sigma.contextMenu	Add file browser context menu items
sigma.sidebar	Add custom sidebar pages
sigma.toolbar	Add toolbar dropdown actions
sigma.context	Read navigation state and open external resources
sigma.ui	Build extension UI and show feedback
sigma.dialog	Open native file and save dialogs
sigma.fs	Work with files, extension storage, and scoped directories
sigma.shell	Run executables and stream process output
sigma.binary	Read manifest-managed binary paths and metadata
sigma.settings	Read and update extension settings
sigma.storage	Persist arbitrary extension data
sigma.platform	Detect OS, architecture, and path behavior
sigma.path	Parse file paths without platform calls
sigma.i18n	Contribute and use translations

Namespace Reference

sigma.commands

Use commands for Command Palette entries and programmatic execution.

Method	Returns	Notes
registerCommand(command, handler)	Disposable	Requires commands permission
executeCommand(commandId, ...args)	Promise<unknown>	Can call built-in commands or commands registered by the same extension
getBuiltinCommands()	BuiltinCommandInfo[]	Lists commands exposed by the app

Command definitions support id, title, description, icon, and shortcut.

sigma.contextMenu

Adds items to the file browser context menu.

Method	Returns	Notes
registerItem(item, handler)	Disposable	Requires contextMenu permission

The handler receives a ContextMenuContext object:

Field	Type	Description
selectedEntries[].path	string	Absolute path
selectedEntries[].name	string	File or folder name
selectedEntries[].isDirectory	boolean	Whether the entry is a directory
selectedEntries[].size	number?	Size in bytes
selectedEntries[].extension	string?	File extension

Context menu items support group, order, and when filters such as selectionType, entryType, and fileExtensions.

sigma.sidebar

Adds pages to the application sidebar.

Method	Returns	Notes
registerPage(page)	Disposable	Requires sidebar permission

Sidebar page fields:

Field	Description
id	Unique page identifier within the extension
title	Sidebar label
icon	Lucide icon name
order	Optional sort order
url	Optional page path relative to the extension root, typically used by iframe-based pages

sigma.toolbar

Adds dropdown menus to the main toolbar.

Method	Returns	Notes
registerDropdown(dropdown, handlers)	Disposable	Requires toolbar permission

Toolbar dropdowns define items, and the handlers object maps item IDs to click handlers.

sigma.context

Provides read access to the current app state and a small set of convenience helpers.

Method	Returns	Notes
getCurrentPath()	string | null	Current directory
getSelectedEntries()	ExtensionContextEntry[]	Current file and folder selection
getAppVersion()	Promise<string>	Installed Sigma File Manager version
getDownloadsDir()	Promise<string>	User downloads directory
getPicturesDir()	Promise<string>	User pictures directory
openUrl(url)	Promise<void>	Opens a URL with the system handler. Requires openUrl permission
onPathChange(callback)	Disposable	Fires on navigation changes
onSelectionChange(callback)	Disposable	Fires on selection changes

sigma.ui

Provides feedback APIs and declarative building blocks for extension UI.

Method	Returns	Notes
showNotification(options)	void	Requires notifications permission
showDialog(options)	Promise<DialogResult>	Requires dialogs permission
copyText(text)	Promise<void>	Requires clipboard permission
clipboardWrite(items)	Promise<void>	Writes rich clipboard data. Requires clipboard permission
withProgress(options, task)	Promise<T>	Runs cancellable long-running tasks
createModal(options)	ModalHandle	Creates a dynamic custom modal
showModal(options)	Promise<Record<string, unknown> | null>	Opens a modal and resolves on submit or close
input() / select() / checkbox() / textarea()	UIElement	Form elements for modals
separator() / text() / image() / button()	UIElement	Layout and display elements
alert() / previewCard() / previewCardSkeleton() / skeleton()	UIElement	Status blocks and loading placeholders
renderToolbar(container, elements, onButtonClick?)	ToolbarRenderHandle	Renders a toolbar inside an extension embed page

See UI Reference for option shapes, modal lifecycle hooks, and usage patterns.

sigma.dialog

Provides native open and save dialogs.

Method	Returns	Notes
openFile(options?)	Promise<string | string[] | null>	Requires dialogs permission. Options may include title, defaultPath, filters, multiple, and directory
saveFile(options?)	Promise<string | null>	Requires dialogs permission

sigma.fs

Provides three different file access models.

Core File APIs

These methods work with absolute paths within directories the user has navigated to or selected entries from. The host scopes access to paths the user has interacted with during the current session; arbitrary absolute paths outside that scope will be rejected.

Method	Returns	Permissions
readFile(path)	Promise<Uint8Array>	fs.read
writeFile(path, data)	Promise<void>	fs.write
readDir(path)	Promise<ExtensionDirEntry[]>	fs.read
exists(path)	Promise<boolean>	fs.read
downloadFile(url, path)	Promise<void>	fs.write

sigma.fs.private

Use this namespace for files stored inside the extension directory.

Method	Returns	Permissions
readFile(relativePath)	Promise<Uint8Array>	fs.read
writeFile(relativePath, data)	Promise<void>	fs.write
readDir(relativePath?)	Promise<ExtensionDirEntry[]>	fs.read
exists(relativePath)	Promise<boolean>	fs.read
resolvePath(relativePath)	Promise<string>	none

Paths are relative to the extension root and cannot contain . or .. segments.

sigma.fs.storage

Use this namespace for extension-owned persistent files.

Method	Returns	Permissions
readFile(relativePath)	Promise<Uint8Array>	fs.read
writeFile(relativePath, data)	Promise<void>	fs.write
readDir(relativePath?)	Promise<ExtensionDirEntry[]>	fs.read
exists(relativePath)	Promise<boolean>	fs.read
resolvePath(relativePath)	Promise<string>	none
importFile(sourcePath, targetRelativePath)	Promise<string>	fs.read and fs.write
deleteFile(relativePath)	Promise<void>	fs.write

This namespace is the best default choice for caches, generated files, and imported user data owned by the extension.

sigma.fs.scoped

Use this namespace when the extension needs access to user-selected directories outside its own storage.

Method	Returns	Permissions
requestDirectoryAccess(options?)	Promise<{ granted, path?, permissions? }>	dialogs plus fs.read and/or fs.write
getDirectories()	Promise<ExtensionScopedDirectory[]>	none
readFile(path)	Promise<Uint8Array>	fs.read
writeFile(path, data)	Promise<void>	fs.write
readDir(path)	Promise<ExtensionDirEntry[]>	fs.read
exists(path)	Promise<boolean>	fs.read

requestDirectoryAccess() accepts:

Option	Description
permission	read, write, or readWrite
title	Dialog title
defaultPath	Initial folder shown in the picker

Use getDirectories() to inspect the scoped directories the user has already granted.

sigma.shell

Runs executables and captures output.

Method	Returns	Permissions
run(commandPath, args?)	Promise<{ code, stdout, stderr }>	shell
runWithProgress(commandPath, args, onProgress?)	Promise<{ taskId, result, cancel }>	shell. result is itself a Promise<{ code, stdout, stderr }> that resolves when the process exits. cancel is () => Promise<void>
renamePartFilesToTs(directory)	Promise<number>	Renames .mp4.part files to .ts in directory; returns how many files were renamed. shell

runWithProgress() is the best choice when you need streaming output, cancellation, or UI progress updates.

sigma.binary

Reads binary dependencies declared in the manifest under package.json > binaries. The host installs and verifies those binaries during extension installation and update.

Method	Returns	Permissions
getPath(id)	Promise<string | null>	shell
isInstalled(id)	Promise<boolean>	shell
getInfo(id)	Promise<BinaryInfo | null>	shell

Declare binaries in the manifest, not in extension code. See Manifest Reference for the binaries schema.

getPath() resolves the installed executable path for a declared binary ID.

getInfo() returns BinaryInfo, which includes metadata such as the installed path, pinned version, source download URL, and latest-known version information shown in the app.

sigma.runtime

Method	Returns	Permissions
isExtensionInstallCancelledError(error)	boolean	(none)

sigma.settings

Reads and writes settings declared in the manifest under contributes.configuration.

Method	Returns	Notes
get(key)	Promise<T | undefined>	Reads a single setting
set(key, value)	Promise<void>	Persists a value
getAll()	Promise<Record<string, unknown>>	Returns all extension settings
reset(key)	Promise<void>	Restores the default value
onChange(key, callback)	Disposable	Callback receives (newValue, oldValue). Fires when the setting changes

sigma.storage

Stores arbitrary structured values between sessions.

Method	Returns	Notes
get(key)	Promise<T | undefined>	Reads a stored value
set(key, value)	Promise<void>	Persists a stored value
remove(key)	Promise<void>	Deletes a stored value

Use sigma.storage for lightweight structured state. Use sigma.fs.storage for files.

sigma.platform

Exposes platform and path helpers.

Property or Method	Description
os	windows, macos, or linux
arch	x64 or arm64
pathSeparator	Platform path separator
isWindows	Convenience boolean
isMacos	Convenience boolean
isLinux	Convenience boolean
joinPath(...segments)	Joins path segments using the current platform rules

sigma.path

Pure string utilities for parsing file paths. These do not require platform calls and work identically on all platforms by normalizing separators internally.

Method	Returns	Notes
dirname(filePath)	string	Parent directory path
basename(filePath, suffix?)	string	File name with optional suffix removal
extname(filePath)	string	File extension including the dot

sigma.i18n

Extensions contribute translations merged into the app i18n. No separate i18n library is required in the extension.

Method	Returns	Notes
t(key, params?)	string	Translates app-wide keys (e.g. extensions.loadingExtension)
mergeMessages(messages)	void	Merges { locale: { key: value } } at runtime
mergeFromPath(basePath)	Promise<void>	Loads basePath/{locale}.json for each app locale
extensionT(key, params?, fallback?)	string	Extension keys (auto-namespaced). Returns fallback when missing, otherwise the original key
formatMessage(template, params?)	string	Replaces {name} placeholders in a string template

Recommended pattern — merge every locale from the extension root and alias extensionT:

const t = sigma.i18n.extensionT;

export async function activate() {
  await sigma.i18n.mergeFromPath('locales');
}

Then use t('myKey', { name: 'value' }) for user-visible strings.

Locale files (locales/en.json, locales/de.json, …): same keys across files; load with mergeFromPath('locales') during activate.

Inline messages (no JSON files):

sigma.i18n.mergeMessages({
  en: { loading: 'Loading...', openWebsite: 'Open website' },
  de: { loading: 'Laden...', openWebsite: 'Website öffnen' },
});

Runtime Model

Current app builds load API extensions in an isolated worker and load extension page embeds in a sandboxed iframe bridge. Use Sigma APIs instead of direct browser globals for clipboard, storage, dialogs, and app integration.

Continue

← Previous: Manifest Reference

Next: UI Reference →