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:
Frontend entrypoint
Your frontend entrypoint file must build to scripts/renderer/rendererEntry.mjs as an ES module and export InitialExtensions:
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.
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 below).
getAppManager(): Promise<MainWindowManager>
Resolves to the window manager controller (see MainWindowManager below).
getModuleManager(): Promise<ModuleManager>
Resolves to the card modules controller (see 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): voidhome.replace.searchResult(component: FC<{searchValue: string}>): voidhome.replace.categories(component: FC): voidhome.add.top(component: FC): void / bottom / scrollTop / scrollBottomhome.add.pinCategory(component: FC): void / recentlyCategoryhome.add.allCategory(component: FC<CardDataProps>): voidaudio | image | text | agents | others | tools | games - Sub-pages:
add.top(component: FC): void / bottom / scrollTop / scrollBottom / cardsContainer
settings.add.navButton(component: FC): void / contentdashboard.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>): voidcustomize.body(component: FC<CardDataProps>): voidcustomize.footer(component: FC<CardDataProps>): voidcustomize.menu.replace(component: FC<CardDataProps>): voidcustomize.menu.addSection(sections: {index: number; components: FC<CardDataProps>[]}[]): voidcustomize.menu.addModal(modals: {key: string; component: FC<CardDataProps>}[]): voidregisterToolsCard(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): () => voidoff(event: string, callback: (payload: any) => void): voidemit(event: string, payload: any): voidgetListenerCount(event: string): number
ipcEvents
Allows intercepting or hooking into all renderer IPC events.
modulesData
allModules: CardModulesallCards: CardData[]useGetArgumentsByID(id: string): ArgumentsData | undefineduseGetCardsByPath(path: string): LoadedCardData[] | undefinedgetCardMethod(cards: CardData[], id: string, method: string): Function | undefined
toast
top(message: string, options?: any): voidbottom(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.
Last modified on July 7, 2026
