---
name: Lynx Hub
description: Use when building plugins (extensions or modules) for LynxHub, configuring AI tool integrations, managing launch configurations, or troubleshooting the desktop application. Reach for this skill when agents need to extend LynxHub's functionality, integrate new AI engines, customize the UI, or help users configure their workspace.
metadata:
    mintlify-proj: lynxhub
    version: "1.0"
---

# LynxHub Skill

## Product summary

LynxHub is a desktop application that consolidates AI workflows into a unified workspace. It allows users to configure, manage, and run local AI interfaces (like Stable Diffusion, ComfyUI, llama.cpp) with integrated terminal and browser tabs. Agents use this skill to build plugins that extend LynxHub's capabilities, configure module integrations, or help users troubleshoot their setup.

**Key files and paths:**
- Plugin directory: `<AppData>/Plugins/<plugin-id>/` (Windows: `%USERPROFILE%\Documents\LynxHub\Plugins`)
- Extension template: `https://github.com/KindaBrazy/LynxHub-Extension-Template` (source branch)
- Module template: `https://github.com/KindaBrazy/LynxHub-Module-Template` (source branch)
- Build commands: `npm run build:extension` or `npm run build:module`
- Configuration files: `metadata.json`, `versioning.json`, `icon.png` (on `metadata` branch)

**Primary docs:** https://docs.lynxhub.app

---

## When to use

Reach for this skill when:

- **Building plugins**: Creating extensions (UI customization, global hooks, tray widgets) or modules (AI tool integrations, card-based features)
- **Configuring modules**: Setting up launch arguments, pre-launch commands, browser viewports, or address detection for card modules
- **Troubleshooting**: Resolving startup loops, rendering issues, terminal failures, or plugin conflicts
- **Publishing plugins**: Preparing extensions or modules for distribution with proper metadata, versioning, and build artifacts
- **Integrating AI tools**: Helping users install, configure, and run local AI models (ComfyUI, Stable Diffusion, etc.) through the LynxHub interface
- **Customizing the workspace**: Adding custom pages, routes, Redux state, or system tray integration via extensions

---

## Quick reference

### Plugin types comparison

| Feature | Extensions | Modules |
|---------|-----------|---------|
| **Purpose** | UI customization, global hooks, tray widgets | Standalone AI tools, card-based features |
| **UI Integration** | React components in predefined slots (title bar, status bar, settings, sidebar) | Standardized cards in category routes |
| **Build tool** | Vite + Webpack Module Federation | Rollup + ES modules |
| **Lifecycle** | Runs continuously in background | Started/stopped by user |
| **State** | Can inject Redux reducers | Host manages state via Zustand/Redux |
| **Terminal** | Manual subprocess management | Built-in stream output to host terminal |

### Plugin directory structure

**Extension (production):**
```
Plugins/<extension-id>/
├── metadata.json
└── scripts/
    ├── main/mainEntry.cjs
    └── renderer/rendererEntry.mjs
```

**Module (production):**
```
Plugins/<module-id>/
├── metadata.json
└── scripts/
    ├── main.mjs
    └── renderer.mjs
```

### Essential build commands

```bash
# Clone templates into host repo
git clone https://github.com/KindaBrazy/LynxHub
cd LynxHub
git clone -b source https://github.com/KindaBrazy/LynxHub-Extension-Template extension
git clone -b source https://github.com/KindaBrazy/LynxHub-Module-Template module

# Build plugins
npm run build:extension
npm run build:module

# Validate code
npm run validate:ext  # Extensions
npm run typecheck    # Modules

# Run in development
npm run dev
```

### Launch configuration options

Access via card's **3 dots menu → Launch Config**:

- **Presets**: Save/load argument configurations
- **Custom arguments**: Toggle flags like `--use-cpu`, `--lowvram`, `--xformers`
- **Pre-launch commands**: Run shell commands before startup (e.g., `conda activate myenv`)
- **Custom launch command**: Override default run command
- **Launch behavior**: Split View (default), Terminal Only, Browser Only, None
- **Browser load delay**: Milliseconds before browser loads (default: 0ms)
- **Address detection**: Automatic, custom port override, or regex pattern

---

## Decision guidance

### When to build an extension vs. a module

| Scenario | Choose Extension | Choose Module |
|----------|-----------------|---------------|
| Adding a new top-level tab or custom route | ✓ | |
| Modifying main frame layout (title bar, tray) | ✓ | |
| Hooking into global app lifecycle events | ✓ | |
| Integrating an existing AI tool (ComfyUI, Stable Diffusion) | | ✓ |
| Managing installation, updates, and process execution | | ✓ |
| Fitting into standardized card interface | | ✓ |
| Adding custom menu items or system tray widgets | ✓ | |
| Running isolated CLI scripts or backend commands | | ✓ |

### When to use different launch behaviors

| Behavior | Use when |
|----------|----------|
| **Split View** | User needs to see both terminal output and web interface simultaneously |
| **Terminal Only** | Monitoring logs or debugging without needing the web UI |
| **Browser Only** | Full-screen web interface; terminal runs invisibly |
| **None** | Background process with no visible output |

---

## Workflow

### Building and publishing an extension

1. **Clone the template** into the host repo's `/extension` directory:
   ```bash
   git clone -b source https://github.com/KindaBrazy/LynxHub-Extension-Template extension
   ```

2. **Define package metadata** in `extension/package.json`:
   - Set `name`, `version`, `author`, `homepage`, `repository`
   - Keep `"type": "module"`

3. **Implement main process** (`src/main/lynxExtension.ts`):
   - Export `initialExtension(lynxApi, utils, mainIpc)` function
   - Register lifecycle callbacks: `onAppReady()`, `listenForChannels()`, `onReadyToShow()`
   - Handle system tray, IPC events, background processes

4. **Implement renderer process** (`src/renderer/Extension.tsx`):
   - Export `InitialExtensions(lynxAPI, rendererIpc, extensionId)` function
   - Inject React components into slots: `titleBar.addEnd()`, `statusBar`, `settings`, `sidebar`
   - Add custom routes or Redux reducers

5. **Test locally** with `npm run dev`:
   - Verify UI elements appear in correct slots
   - Check backend logs with `F12` or `Ctrl+Shift+I`
   - Run `npm run validate:ext` for type checking

6. **Build for production** with `npm run build:extension`:
   - Outputs to `extension_out/main/` and `extension_out/renderer/`

7. **Create metadata branch** with:
   - `metadata.json`: id, title, description, type="extension"
   - `versioning.json`: versions array with semver, commit hash, engines.extensionApi, stage, platforms
   - `icon.png`: 512x512 PNG square image

8. **Push to repository**:
   - Commit source to `source` branch
   - Copy compiled `scripts/` to `main` branch
   - Push both branches

### Building and publishing a module

1. **Clone the template** into the host repo's `/module` directory:
   ```bash
   git clone -b source https://github.com/KindaBrazy/LynxHub-Module-Template module
   ```

2. **Define package metadata** in `module/package.json`:
   - Set `name`, `version`, `author`, `homepage`, `repository`
   - Keep `"type": "module"`

3. **Implement main process** (`src/main.ts`):
   - Export default function `initialModule(utils)` returning array of `MainModules`
   - Each module object has `id` and `methods()` function
   - Implement methods: `getRunCommands()`, `readArgs()`, `saveArgs()`, `isInstalled()`, `uninstall()`, `mainIpc()`

4. **Implement renderer process** (`src/renderer.ts`):
   - Export default `CardModules` array
   - Define `routePath` (e.g., 'imageGen_page', 'textGen_page')
   - Configure card properties: id, title, description, repoUrl, type, arguments, methods
   - Implement methods: `catchAddress()`, `parseArgsToString()`, `parseStringToArgs()`, `cardInfo()`, `manager.startInstall()`

5. **Test locally** with `npm run dev`:
   - Locate card on dashboard
   - Click launch button to test execution
   - Verify terminal output and browser loading
   - Run `npm run typecheck` for validation

6. **Build for production** with `npm run build:module`:
   - Outputs to `module_out/scripts/` (main.mjs and renderer.mjs)

7. **Create metadata branch** with:
   - `metadata.json`: id, title, description, type="module"
   - `versioning.json`: versions array with semver, commit hash, engines.moduleApi, stage, platforms
   - `icon.png`: 512x512 PNG square image

8. **Push to repository**:
   - Commit source to `source` branch
   - Copy compiled `scripts/` to `main` branch
   - Push both branches

### Configuring a module for launch

1. **Open launch config**: Click card's **3 dots menu → Launch Config**

2. **Set arguments**:
   - Choose preset or toggle individual flags
   - Enable **Custom Arguments UI** if needed

3. **Add pre-launch commands**:
   - Click **Add Command** for each shell command
   - Examples: `conda activate myenv`, `set CUDA_VISIBLE_DEVICES=0`

4. **Configure custom run**:
   - Enable **Custom launch command** to override defaults
   - Set **Launch behavior** (Split View, Terminal Only, Browser Only, None)
   - Set **Browser load delay** if needed (milliseconds)

5. **Configure address detection**:
   - Use **Automatic detection** for standard ports
   - Or set **Custom port override** for specific address
   - Or use **Regex catch pattern** for custom parsing

6. **Save preset** for quick switching between configurations

---

## Common gotchas

- **Missing metadata branch**: Extensions and modules require `metadata.json`, `versioning.json`, and `icon.png` on a separate `metadata` branch, not the source branch. This causes publication failures.

- **Incorrect build output location**: Extensions output to `extension_out/main/` and `extension_out/renderer/` (separate directories). Modules output to `module_out/scripts/` (single directory). Copying to wrong location breaks production loading.

- **Shared packages not declared**: Extensions must treat `react`, `react-dom`, `react-redux`, `@heroui/react`, `@heroui/styles`, `react-aria` as peer dependencies and configure them as shared in Vite config. Bundling them causes duplicate instances.

- **Startup loop from bad plugin**: If LynxHub crashes on startup or shows blank screen, a corrupted plugin is likely. Delete all plugins from `<AppData>/Plugins/` and restart to isolate the issue.

- **Terminal spawning failures on Windows**: If terminal crashes immediately, go to **Settings → Terminal** and toggle **Use Conpty (Windows)** to **No**.

- **Hardware acceleration causing freezes**: If UI freezes or lags, disable hardware acceleration in **Settings → Performance**.

- **Git or PowerShell 7+ not installed**: Repository operations and terminal commands fail silently. Ensure both are installed and in system PATH.

- **Regex pattern for address detection too broad**: If browser loads wrong address, test regex pattern carefully. Use `http://127.0.0.1:7860` as fallback.

- **Module methods not returning promises**: All main process methods must be async and return promises. Synchronous returns cause execution failures.

- **Extension not injecting into correct slot**: Verify slot name matches host API (e.g., `titleBar.addEnd()`, `statusBar.addStart()`). Wrong slot names silently fail.

- **Versioning.json missing commit hash**: Publish fails if commit hash is not exact Git commit SHA. Use `git rev-parse HEAD` to get correct hash.

---

## Verification checklist

Before submitting plugin work:

- [ ] **Metadata files created**: `metadata.json`, `versioning.json`, `icon.png` on `metadata` branch
- [ ] **Metadata valid**: id uses lowercase alphanumeric + hyphens, type is "extension" or "module", platforms array includes target OS
- [ ] **Versioning valid**: commit hash is exact Git SHA, engines range uses semver (e.g., `^2.0.0`), stage is "public", "early_access", or "insider"
- [ ] **Icon correct**: PNG format, 512x512 pixels, square dimensions
- [ ] **Build succeeds**: `npm run build:extension` or `npm run build:module` completes without errors
- [ ] **Output structure correct**: Extension has `scripts/main/mainEntry.cjs` and `scripts/renderer/rendererEntry.mjs`; Module has `scripts/main.mjs` and `scripts/renderer.mjs`
- [ ] **Local testing passes**: Plugin loads in development mode (`npm run dev`) without errors
- [ ] **Production testing passes**: Compiled files copied to `<AppData>/Plugins/<id>/` and LynxHub loads plugin after restart
- [ ] **Type checking passes**: `npm run validate:ext` (extensions) or `npm run typecheck` (modules) returns no errors
- [ ] **Source branch clean**: All raw source files committed to `source` branch
- [ ] **Main branch has compiled assets**: `scripts/` directory pushed to `main` branch with compiled bundles
- [ ] **Both branches pushed**: Both `source` and `main` branches pushed to remote repository

---

## Resources

**Comprehensive page listing:** https://docs.lynxhub.app/llms.txt

**Critical documentation pages:**
- [Plugin System Overview](https://docs.lynxhub.app/plugins/overview) — Understand extension vs. module architecture
- [Extension Quick Start](https://docs.lynxhub.app/plugins/extensions/quick-start) — Build your first extension
- [Module Quick Start](https://docs.lynxhub.app/plugins/modules/quick-start) — Build your first module
- [Launch Configuration](https://docs.lynxhub.app/application/launch-configuration) — Configure module arguments and behavior
- [Troubleshooting](https://docs.lynxhub.app/application/troubleshooting) — Resolve common issues

---

> For additional documentation and navigation, see: https://docs.lynxhub.app/llms.txt