> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lynxhub.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Extension API reference

> Complete API reference guide for frontend, backend, and shared IPC namespaces.

This page provides the full API specifications for building LynxHub extensions.

***

## Extension entrypoints

An extension must define separate entry points for the backend (Electron Main) and frontend (Electron Renderer) processes.

### Backend entrypoint

Your backend entrypoint file must build to `scripts/main/mainEntry.cjs` as a CommonJS module and export `initialExtension`:

```typescript theme={null}
export async function initialExtension(lynxApi: ExtensionMainApi, utils: MainExtensionUtils, mainIpc: MainIpcApi): Promise<void>;
```

### Frontend entrypoint

Your frontend entrypoint file must build to `scripts/renderer/rendererEntry.mjs` as an ES module and export `InitialExtensions`:

```typescript theme={null}
export function InitialExtensions(lynxAPI: ExtensionRendererApi, rendererIpc: RendererIpcApi, extensionId: string): void;
```

***

## Backend API reference

The backend process handles Node.js integrations, local execution, and database persistence.

### ExtensionMainApi

Use `lynxApi` to listen to system events, hook into IPC cycles, or insert system tray menu items.

#### `listenForChannels(callback: () => void): void`

Registers a callback to execute custom IPC channel listeners (`ipcMain.on` / `ipcMain.handle`).

#### `onAppReady(callback: () => Promise<void>): void`

Registers an asynchronous callback executing when Electron is fully booted (`app.whenReady()`).

#### `onReadyToShow(callback: () => void): void`

Registers a callback executing when the main BrowserWindow is ready to show.

#### `trayMenu_AddItem(callback: () => { item: MenuItemConstructorOptions; index: number }): void`

Appends a menu item to the host's system tray dropdown.

#### `ipcEvents`

Accesses the main process IPC hook registry to intercept channel transactions.

#### `initNodeSentry(dsn: string): Scope`

Initializes Sentry error tracking for the backend Node process. Returns the active Sentry scope.

***

### MainExtensionUtils

Use `utils` to resolve class singletons or spawn native pseudo-terminals.

#### `getStorageManager(): Promise<StorageManager>`

Resolves to the application storage controller (see [StorageManager](#storagemanager) below).

#### `getAppManager(): Promise<MainWindowManager>`

Resolves to the window manager controller (see [MainWindowManager](#mainwindowmanager) below).

#### `getModuleManager(): Promise<ModuleManager>`

Resolves to the card modules controller (see [ModuleManager](#modulemanager) below).

#### `nodePty`

Exposes the native `node-pty` module. Use this to spawn pseudo-terminal processes.

***

### StorageManager

The persistent storage controller exposes methods to query settings or save custom settings.

#### `getCustomData(id: string): any`

Queries custom data values. Keys beginning with `moduleName::` (e.g. `python::envPath`) automatically redirect reads to the dedicated configuration file: `moduleName.config`.

#### `setCustomData(id: string, data: any): void`

Saves custom data values. Scoped keys using `::` are persisted to their respective config files.

#### `getData<K extends keyof AppStorageData>(key: K): AppStorageData[K]`

Queries core application configuration fields (e.g. `app`, `terminal`, `browser`, `performance`, `plugin`, `cards`, `cardsConfig`).

#### `updateData<K extends keyof AppStorageData>(key: K, updateData: Partial<AppStorageData[K]>): void`

Updates core configuration fields partially.

#### `write(): void`

Commits current storage cache to disk.

#### `decryptBrowserData(): void`

Decrypts stored browser addresses and caches them in memory.

#### `getBrowserDataSecurely(): BrowserHistoryData`

Retrieves decrypted browser history, addresses, favorites, and favicons from the memory cache.

#### `updateBrowserDataSecurely(data: Partial<BrowserHistoryData>): void`

Updates decrypted cache values. The manager automatically encrypts values on disk.

#### `addInstalledCard(card: InstalledCard): void`

Adds a card definition to the local card registry.

#### `removeInstalledCard(id: string): void`

Removes a card definition from the card registry.

#### `addPinnedCard(cardId: string): void`

Pins a card on the home page dashboard.

#### `removePinnedCard(cardId: string): void`

Unpins a card from the home page.

#### `updateRecentlyUsedCards(id: string): void`

Moves a card ID to the front of the recently used list.

#### `setCardTerminalPreCommands(id: string, commands: string[]): void`

Saves pre-commands executed in the terminal prior to card startups.

#### `unassignCard(id: string, clearConfigs: boolean): void`

Removes a card registry and optionally purges its associated configs.

***

### MainWindowManager

Controls the main application window lifecycle.

#### `getMainWindow(): BrowserWindow | undefined`

Retrieves the main Electron `BrowserWindow` instance.

#### `getWebContent(): WebContents | undefined`

Retrieves the `WebContents` instance of the main window.

#### `sendMessage(channel: string, ...args: any[]): void`

Dispatches an IPC message directly to the renderer process.

#### `restart(): void`

Relaunches the host application.

***

### ModuleManager

Controls the lifecycle of card modules.

#### `getMethodsById(id: string): any`

Queries public methods exported by a module.

#### `uninstallCardByID(id: string): Promise<void>`

Triggers a module's custom uninstallation routine.

#### `checkCardUpdate(card: InstalledCard, type: 'git' | 'stepper' | undefined): Promise<boolean>`

Checks if a card has updates available on its remote repository.

***

## Frontend API reference

The frontend process handles page rendering, styles, and UI events.

### ExtensionRendererApi

Use `lynxAPI` to inject custom components, manage client routes, or dispatch actions.

#### `titleBar`

* `addStart(component: FC): void` - Injects component to start of title bar.
* `addCenter(component: FC): void` - Injects component to center of title bar.
* `addEnd(component: FC): void` - Injects component to end of title bar.
* `replaceCenter(component: FC): void` - Replaces center elements.
* `replaceEnd(component: FC): void` - Replaces end elements.

#### `statusBar`

* `addStart(component: FC): void` - Injects component to start of status bar.
* `addCenter(component: FC): void` - Injects component to center of status bar.
* `addEnd(component: FC): void` - Injects component to end of status bar.
* `replaceContainer(component: FC): void` - Replaces status bar container.

#### `runningAI`

* `container(component: FC): void` - Replaces entire running viewport.
* `terminal(component: FC): void` - Replaces terminal panel.
* `browser(component: FC): void` - Replaces browser panel.

#### `router`

* `add(routeObject: RouteObject[]): void` - Appends routes to the router.
* `addPage(page: ExtensionPage): void` - Registers a custom page component to the router and sidebar navigation.
* `replace` - Replaces default page views (`homePage`, `imageGenerationPage`, `textGenerationPage`, `audioGenerationPage`, `toolsPage`, `gamesPage`, `dashboardPage`, `modulesPage`, `extensionsPage`, `settingsPage`).

##### `ExtensionPage` properties:

* `id` (string): Unique identifier.
* `title` (string): Title of page.
* `icon` (ReactNode, optional): Page icon elements.
* `component` (FC): The page React component.
* `position` (`'top' | 'bottom' | 'hidden'`, optional): Sidebar layout position.

#### `tabs`

* `setActivePage(pageID: string, title?: string, isTerminal?: boolean): void` - Sets the active page for the current tab.

#### `navBar`

* `replace.container(component: FC): void` - Replaces entire sidebar.
* `replace.contentBar(component: FC): void` - Replaces upper menu list.
* `replace.settingsBar(component: FC): void` - Replaces lower menu list.
* `addButton.contentBar(component: FC): void` - Appends link to content menu.
* `addButton.settingsBar(component: FC): void` - Appends link to settings menu.

#### `addModal(component: FC): void`

Appends a custom modal component to the overlay tree.

#### `replaceModals`

Replaces built-in host modals (`updateApp`, `launchConfig`, `cardExtensions`, `updatingNotification`, `cardInfo`, `installUi`, `uninstallCard`, `unassignCard`, `warning`, `cardReadme`, `gitManager`).

#### `replaceMarkdownViewer(component: FC<{repoPath: string; rounded?: boolean}>): void`

Replaces the default Markdown renderer.

#### `addCustomHook(hook: FC): void`

Mounts a React hook component at the tree root.

#### `replaceBackground(component: FC): void`

Replaces the window background component.

#### `customizePages`

* `home.replace.searchAndFilter(component: FC): void`
* `home.replace.searchResult(component: FC<{searchValue: string}>): void`
* `home.replace.categories(component: FC): void`
* `home.add.top(component: FC): void` / `bottom` / `scrollTop` / `scrollBottom`
* `home.add.pinCategory(component: FC): void` / `recentlyCategory`
* `home.add.allCategory(component: FC<CardDataProps>): void`
* `audio` | `image` | `text` | `agents` | `others` | `tools` | `games` - Sub-pages:
  * `add.top(component: FC): void` / `bottom` / `scrollTop` / `scrollBottom` / `cardsContainer`
* `settings.add.navButton(component: FC): void` / `content`
* `dashboard.add.navButton(component: FC): void` / `content`

#### `addReducer(reducers: {name: string; reducer: Reducer}[]): void`

Registers Redux slices to the central application store.

#### `cards`

* `replace(component: FC<{cards: LoadedCardData[]}>): void` - Replaces card grid.
* `replaceComponent(component: FC<CardDataProps>): void` - Replaces single card layout.
* `customize.header(component: FC<CardDataProps>): void`
* `customize.body(component: FC<CardDataProps>): void`
* `customize.footer(component: FC<CardDataProps>): void`
* `customize.menu.replace(component: FC<CardDataProps>): void`
* `customize.menu.addSection(sections: {index: number; components: FC<CardDataProps>[]}[]): void`
* `customize.menu.addModal(modals: {key: string; component: FC<CardDataProps>}[]): void`
* `registerToolsCard(card: ToolsCardConfig): void` - Registers a custom card directly inside the Tools page.

##### `ToolsCardConfig` properties:

* `id` (string): Unique identifier.
* `title` (string): Title of card.
* `description` (string): Subtitle / description of card.
* `icon` (string | ReactNode, optional): Custom icon element.
* `onPress` (() => void, optional): Interactive click callback.
* `component` (ComponentType, optional): The custom React component representing the card.
* `where` (string, optional): Target category routing slot (e.g., `"tools_page"`).

#### `setCards_TerminalPreCommands(id: string, preCommands: string[]): void`

Defines commands running before launching terminal processes.

#### `events`

* `on(event: string, callback: (payload: any) => void): () => void`
* `off(event: string, callback: (payload: any) => void): void`
* `emit(event: string, payload: any): void`
* `getListenerCount(event: string): number`

#### `ipcEvents`

Allows intercepting or hooking into all renderer IPC events.

#### `modulesData`

* `allModules: CardModules`
* `allCards: CardData[]`
* `useGetArgumentsByID(id: string): ArgumentsData | undefined`
* `useGetCardsByPath(path: string): LoadedCardData[] | undefined`
* `getCardMethod(cards: CardData[], id: string, method: string): Function | undefined`

#### `toast`

* `top(message: string, options?: any): void`
* `bottom(message: string, options?: any): void`

***

## Shared IPC APIs

Both process entry points receive IPC wrappers (`MainIpcApi` and `RendererIpcApi`) providing typed namespaces for communication.

### `files` (filesIpc)

Handles native filesystem operations.

* `openDlg(option: OpenDialogOptions): Promise<string | undefined>` - Show file dialog.
* `openDlgMany(option: OpenDialogOptions): Promise<string[]>` - Show file dialog for multiple selections.
* `openPath(dir: string): void` - Open path in system file explorer.
* `saveToFile(content: string): Promise<string | null>` - Show save dialog and save text.
* `getAppDirectories(name: FolderNames): Promise<string>` - Retrieve app folder paths.
* `removeDir(dir: string): Promise<void>` - Permanently delete directory.
* `trashDir(dir: string): Promise<void>` - Move directory to trash.
* `listDir(dirPath: string, relatives: string[]): Promise<FolderListData[]>` - List directory items.
* `checkFilesExist(dir: string, fileNames: string[]): Promise<boolean>` - Confirm file existence.
* `calcFolderSize(dir: string): Promise<number>` - Query folder size in bytes.
* `getRelativePath(base: string, target: string): Promise<string>` - Calculate relative path.
* `getAbsolutePath(base: string, target: string): Promise<string>` - Calculate absolute path.
* `isEmptyDir(dir: string): Promise<boolean>` - Check if folder is empty.
* `isAbsolute(dir: string): Promise<boolean>` - Check if path is absolute.

***

### `git` (gitIpc)

Handles repository management operations.

* `cloneShallow(options: ShallowCloneOptions): void` - Shallow clones repository.
* `cloneShallowPromise(options: ShallowCloneOptions): Promise<void>` - Clones repository asynchronously.
* `getRepoInfo(dir: string): Promise<RepositoryInfo>` - Queries branch and remote URL.
* `changeBranch(dir: string, branch: string): Promise<void>` - Switch local branch.
* `unShallow(dir: string): Promise<void>` - Fetch full repository history.
* `resetHard(dir: string): Promise<string>` - Hard reset local changes.
* `getCommits(dir: string, max?: number): Promise<CommitItem[]>` - Retrieve git commit logs.
* `validateGitDir(dir: string, url: string): Promise<boolean>` - Confirm directory is valid repository matching URL.
* `onProgress(callback: GitProgressCallback): () => void` - Listen for clone/pull progress.
* `pull(repoDir: string, id: string): void` - Pull changes.
* `stashDrop(dir: string): Promise<Result>` - Drop stash records.

***

### `pty` (ptyIpc)

Handles pseudo-terminal process spawning.

* `process(id: string, cardId: string): void` - Launch card shell process.
* `customProcess(id: string, dir?: string, file?: string): void` - Spawn file executable in PTY.
* `emptyProcess(id: string, dir?: string): void` - Spawn empty shell process.
* `customCommands(id: string, commands?: string | string[], dir?: string): void` - Execute custom inputs.
* `stop(id: string): void` - Kill terminal process.
* `write(id: string, data: string): void` - Write string to stdin.
* `clear(id: string): void` - Clear PTY buffer screen.
* `resize(id: string, cols: number, rows: number): void` - Change PTY size.
* `onData(callback: (id: string, data: string) => void): () => void` - Listen to stdout.
* `onTitle(callback: (id: string, title: string) => void): () => void` - Listen to title changes.
* `onExit(callback: (id: string) => void): () => void` - Listen to PTY process termination.

***

### `storage` (storageIpc)

Direct database storage operations.

* `getCustom<T>(key: string): Promise<T>` - Get custom settings value.
* `setCustom<T>(key: string, data: T): void` - Set custom settings value.
* `get<K>(key: K): Promise<AppStorageData[K]>` - Get typed database field.
* `getAll(): Promise<AppStorageData>` - Get full settings database.
* `update<K>(key: K, data: Partial<AppStorageData[K]>): Promise<void>` - Partally update database.
* `clear(): Promise<void>` - Full factory reset database.

***

### `utils` (utilsIpc)

Exposes general helpers and image cache managers.

* `updateAllExtensions(data: ExtensionsUpdateRequest): void` - Sequentially check/pull extensions.
* `onUpdateAllExtensions(callback: (info: OnUpdatingExtensions) => void): () => void` - Listen to extension updates progress.
* `getExtensionsDetails(dir: string): Promise<ExtensionsData>` - List details of extensions in folder.
* `getExtensionsUpdateStatus(dir: string): Promise<ExtensionsUpdateStatus>` - Query updates status.
* `disableExtension(disable: boolean, dir: string): Promise<string>` - Toggle extension folder (prefixes folder with `.`).
* `cancelExtensionsData(): void` - Stop querying extension summaries.
* `downloadFile(url: string): void` - Trigger file download.
* `cancelDownload(): void` - Terminate download process.
* `onDownloadFile(callback: (prog: DownloadProgress) => void): () => void` - Listen to download status.
* `decompressFile(filePath: string): Promise<string>` - Extract archive to path.
* `isResponseValid(url: string): Promise<boolean>` - Confirm URL responds with status 200.
* `getImageAsDataURL(url: string): Promise<string | null>` - Fetch image and convert to data URI.
* `getImageCacheStats(): Promise<ImageCacheStats>` - Retrieve size of image cache folders.
* `clearImageCache(): Promise<ClearImageCacheResult>` - Purge cache.
* `triggerImageCacheCleanup(): Promise<SuccessResult>` - Remove expired cache entries.