### Run Pan UI Quick Start

Source: https://github.com/euraika-labs/pan-ui/wiki/Home

Execute this command to start the Pan UI setup wizard. After setup, access the dashboard at localhost:3199.

```bash
npx @euraika-labs/pan-ui
```

--------------------------------

### Run Pan-UI from Source

Source: https://github.com/euraika-labs/pan-ui/wiki/Development

Clone the repository, install dependencies, and start the development server. Access the application at localhost:3199.

```bash
git clone https://github.com/Euraika-Labs/pan-ui.git
cd pan-ui
npm install
npm run dev
```

--------------------------------

### List All Skills

Source: https://context7.com/euraika-labs/pan-ui/llms.txt

Use GET to retrieve a list of all installed skills. Cookies are required for authentication.

```bash
curl -X GET http://localhost:3199/api/skills \
  -b cookies.txt
```

--------------------------------

### Pan UI CLI setup and daemon mode

Source: https://github.com/euraika-labs/pan-ui/blob/main/docs/architecture.md

Explains the functionalities handled by the Pan UI CLI, including first-run setup, starting the standalone Next.js server, and managing daemon mode with PID and log files.

```bash
# CLI entry point
# First-run setup wizard (detects Hermes, writes .env.local)
# Starting the standalone Next.js server
# Daemon mode (fork, PID file, log file)
# Systemd service install/remove
```

--------------------------------

### List Installed Skills

Source: https://context7.com/euraika-labs/pan-ui/llms.txt

Use GET with the 'installed=true' query parameter to filter and retrieve only the skills that are currently installed. Cookies are required.

```bash
curl -X GET "http://localhost:3199/api/skills?installed=true" \
  -b cookies.txt
```

--------------------------------

### Browse Skill Hub

Source: https://context7.com/euraika-labs/pan-ui/llms.txt

Use GET to discover skills available in the marketplace, excluding those already installed. Cookies are required.

```bash
curl -X GET http://localhost:3199/api/skills/hub \
  -b cookies.txt
```

--------------------------------

### Install Plugin

Source: https://github.com/euraika-labs/pan-ui/blob/main/docs/internal/sprint-tickets.md

Installs a new plugin from a specified repository. This operation is asynchronous.

```APIDOC
## POST /api/plugins/install

### Description
Installs a plugin from a given owner and repository. This is an asynchronous operation.

### Method
POST

### Endpoint
/api/plugins/install

### Parameters
#### Request Body
- **identifier** (string) - Required - The identifier of the plugin in the format 'owner/repo'.

### Request Example
```json
{
  "identifier": "hermes/plugin-example"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the installation process has started.

#### Response Example
{
  "message": "Plugin installation initiated for owner/repo."
}
```

--------------------------------

### Install Pan UI as a Systemd Service (Linux)

Source: https://github.com/euraika-labs/pan-ui/wiki/Installation

Commands to install and remove Pan UI as a systemd user service on Linux. The service starts on login and survives logout.

```bash
npx @euraika-labs/pan-ui service install
```

```bash
npx pan-ui service remove
```

--------------------------------

### Install Skill from Hub

Source: https://context7.com/euraika-labs/pan-ui/llms.txt

Use POST to install a skill from the marketplace. Requires skill identifier and category. Use 'force: true' to override security scan blocks.

```bash
curl -X POST http://localhost:3199/api/skills/hub/install \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"identifier": "python-expert", "category": "development"}'
```

```bash
curl -X POST http://localhost:3199/api/skills/hub/install \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"identifier": "community-skill", "force": true}'
```

--------------------------------

### Search Skill Hub

Source: https://context7.com/euraika-labs/pan-ui/llms.txt

Use GET with a query parameter 'q' to search for specific skills in the marketplace. Excludes installed skills. Cookies are required.

```bash
curl -X GET "http://localhost:3199/api/skills/hub?q=python" \
  -b cookies.txt
```

--------------------------------

### Install MCP Server via API

Source: https://github.com/euraika-labs/pan-ui/blob/main/docs/internal/sprint-tickets.md

Provides an API endpoint to install an MCP server from the hub. It includes input validation and uses `execFile` for asynchronous execution of installation commands, ensuring the event loop is not blocked.

```typescript
app.post('/api/extensions/hub/install', async (req, res) => {
  const { serverId } = req.body;
  const serverIdentifierRegex = /^[a-zA-Z0-9\-._~%]+$/;
  if (!serverId || !serverIdentifierRegex.test(serverId)) {
    return res.status(400).json({ error: 'Invalid server ID format' });
  }

  try {
    // TODO: check if already installed
    const installCommand = `eemeli-cli install ${serverId}`;
    await util.promisify(execFile)(installCommand, { shell: true });
    res.status(200).json({ message: 'Server installed successfully' });
  } catch (error) {
    console.error('Failed to install server:', error);
    res.status(500).json({ error: 'Failed to install server' });
  }
});

app.get('/api/extensions/hub', async (req, res) => {
  const query = req.query.q as string | undefined;
  try {
    const searchResults = await searchHubMcpServers(query || '');
    // TODO: filter out already-installed servers
    res.json(searchResults);
  } catch (error) {
    console.error('Failed to search hub servers:', error);
    res.status(500).json({ error: 'Failed to retrieve hub servers' });
  }
});

```

--------------------------------

### Install MCP Server from Registry

Source: https://context7.com/euraika-labs/pan-ui/llms.txt

Installs an MCP server from the registry. Requires the server's identifier and optionally environment variables for configuration. Authentication via cookies.

```bash
# Install MCP server
curl -X POST http://localhost:3199/api/extensions/hub/install \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{ 
    "identifier": "@modelcontextprotocol/server-github",
    "env": {
      "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
    }
  }'

# Response:
# {
#   "success": true,
#   "identifier": "@modelcontextprotocol/server-github",
#   "extensionId": "server-github"
# }
```

--------------------------------

### MCP Hub API POST Install Handler

Source: https://github.com/euraika-labs/pan-ui/blob/main/docs/internal/engineering-task-breakdown.md

Handles POST requests for installing an MCP server. Validates the identifier, derives the install command, and executes it asynchronously with a timeout. Writes configuration to config.yaml preserving comments.

```typescript
import { NextResponse } from "next/server";
import { execFile } from "child_process";
import { promisify } from "util";
import { parseDocument, YAML } from "eemeli/yaml";
import fs from "fs";

const execFileAsync = promisify(execFile);
const CONFIG_PATH = "./config.yaml";
const IDENTIFIER_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9._-]*/[a-zA-Z0-9._-]*$/;

export async function POST(request: Request) {
  const { packages } = await request.json();

  if (!packages || !Array.isArray(packages) || packages.length === 0) {
    return NextResponse.json({ error: "Invalid packages data" }, { status: 400 });
  }

  const { identifier, version } = packages[0];

  if (!IDENTIFIER_REGEX.test(identifier)) {
    return NextResponse.json({ error: "Invalid identifier format" }, { status: 400 });
  }

  try {
    const installCommand = `npx @euraika/cli install ${identifier}@${version}`;
    await execFileAsync("bash", ["-c", installCommand], { timeout: 30000 });

    const config = parseDocument(fs.readFileSync(CONFIG_PATH, "utf-8"));
    // ... modify config.yaml to add installed package ...
    fs.writeFileSync(CONFIG_PATH, YAML.stringify(config));

    return NextResponse.json({ success: true });
  } catch (error: any) {
    console.error("Install failed:", error);
    return NextResponse.json({ error: `Install failed: ${error.message}` }, { status: 500 });
  }
}
```

--------------------------------

### Rerun Pan UI Setup Wizard

Source: https://context7.com/euraika-labs/pan-ui/llms.txt

Re-runs the initial setup wizard for Pan UI, allowing reconfiguration of Hermes connection settings.

```bash
npx pan-ui setup
```

--------------------------------

### Install Pan UI as Systemd Service

Source: https://context7.com/euraika-labs/pan-ui/llms.txt

Installs Pan UI as a systemd user service on Linux. This ensures Pan UI starts automatically on login and persists across logouts.

```bash
npx pan-ui service install
```

--------------------------------

### Install Hermes Plugin from GitHub

Source: https://context7.com/euraika-labs/pan-ui/llms.txt

Installs a plugin from a specified GitHub repository. Requires the plugin identifier. Authentication via cookies. Handles success and error responses.

```bash
# Install plugin
curl -X POST http://localhost:3199/api/plugins/install \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"identifier": "github-user/hermes-plugin-name"}'

# Response: {"success": true, "identifier": "github-user/hermes-plugin-name"}

# Error for invalid repository:
# {"error": "Repository must contain plugin.yaml and __init__.py"}
```

--------------------------------

### MCP Install Wizard Component

Source: https://github.com/euraika-labs/pan-ui/blob/main/docs/internal/sprint-tickets.md

Component for the one-click MCP server installation flow. Handles environment variable configuration, validation, and installation confirmation.

```typescript
src/features/extensions/components/mcp-install-dialog.tsx
```

--------------------------------

### Load Skill into Session

Source: https://context7.com/euraika-labs/pan-ui/llms.txt

Use POST to load an installed skill into an active chat session. Requires the skill ID and session ID.

```bash
curl -X POST http://localhost:3199/api/skills/code-review/load \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"sessionId": "sess_abc123"}'
```

--------------------------------

### Start Pan UI on Custom Port

Source: https://context7.com/euraika-labs/pan-ui/llms.txt

Starts the Pan UI application on a specified port. Useful for avoiding port conflicts.

```bash
npx @euraika-labs/pan-ui start --port 8080
```

--------------------------------

### Install Plugin Dialog Component

Source: https://github.com/euraika-labs/pan-ui/blob/main/docs/internal/sprint-tickets.md

Component for handling the installation of plugins from GitHub repositories. It validates input and communicates with the backend API.

```typescript
import React, { useState } from "react";

interface InstallPluginDialogProps {
  onClose: () => void;
  onInstallSuccess: () => void;
}

export function InstallPluginDialog({ onClose, onInstallSuccess }: InstallPluginDialogProps) {
  const [repo, setRepo] = useState("");
  const [error, setError] = useState<string | null>(null);
  const [installing, setInstalling] = useState(false);

  const handleInstall = async () => {
    if (!repo) {
      setError("Repository cannot be empty.");
      return;
    }
    setInstalling(true);
    setError(null);
    try {
      const response = await fetch("/api/plugins/install", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ repo }),
      });

      if (!response.ok) {
        const errorData = await response.json();
        throw new Error(errorData.message || "Failed to install plugin");
      }

      onInstallSuccess();
      onClose();
    } catch (err: any) {
      setError(err.message);
    } finally {
      setInstalling(false);
    }
  };

  return (
    <div>
      <h2>Install Plugin</h2>
      <input
        type="text"
        value={repo}
        onChange={(e) => setRepo(e.target.value)}
        placeholder="GitHub owner/repo or URL"
      />
      {error && <p style={{ color: "red" }}>{error}</p>}
      <button onClick={handleInstall} disabled={installing}>
        {installing ? "Installing..." : "Install"}
      </button>
      <button onClick={onClose}>Cancel</button>
    </div>
  );
}
```

--------------------------------

### List All Plugins

Source: https://github.com/euraika-labs/pan-ui/blob/main/docs/internal/sprint-tickets.md

Retrieves a list of all installed plugins, including user-installed and built-in plugins, along with their metadata and enabled/disabled status.

```APIDOC
## GET /api/plugins

### Description
Retrieves a list of all plugins, including their metadata and enabled/disabled status.

### Method
GET

### Endpoint
/api/plugins

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **plugins** (array) - A list of plugin objects.
  - **id** (string) - The unique identifier of the plugin.
  - **name** (string) - The name of the plugin.
  - **version** (string) - The version of the plugin.
  - **description** (string) - A brief description of the plugin.
  - **provides_tools** (array) - A list of tools provided by the plugin.
  - **requires_env** (object) - Environment variables required by the plugin.
  - **enabled** (boolean) - Indicates if the plugin is currently enabled.

#### Response Example
{
  "plugins": [
    {
      "id": "plugin-id-1",
      "name": "Example Plugin",
      "version": "1.0.0",
      "description": "An example plugin.",
      "provides_tools": ["tool1"],
      "requires_env": {},
      "enabled": true
    }
  ]
}
```

--------------------------------

### List MCP Extensions and Tools

Source: https://context7.com/euraika-labs/pan-ui/llms.txt

Use this endpoint to retrieve a list of all installed MCP extensions and the tools they provide. Requires authentication via cookies.

```bash
# List extensions and tools
curl -X GET http://localhost:3199/api/extensions \
  -b cookies.txt

# Response:
# {
#   "extensions": [
#     {
#       "id": "filesystem",
#       "name": "Filesystem",
#       "status": "connected",
#       "tools": ["read_file", "write_file", "list_directory"]
#     }
#   ],
#   "tools": [
#     {"name": "read_file", "extensionId": "filesystem", "description": "Read file contents"}
#   ]
# }
```

--------------------------------

### Check Pan UI Version

Source: https://context7.com/euraika-labs/pan-ui/llms.txt

Displays the currently installed version of Pan UI.

```bash
npx pan-ui version
```

--------------------------------

### Browse MCP Hub for Servers

Source: https://context7.com/euraika-labs/pan-ui/llms.txt

Browse the MCP registry to discover available servers for installation. Supports searching with a query parameter. Requires authentication via cookies.

```bash
# Browse MCP hub
curl -X GET http://localhost:3199/api/extensions/hub \
  -b cookies.txt

# Response:
# {
#   "servers": [
#     {
#       "name": "github",
#       "description": "GitHub API integration",
#       "author": "official",
#       "downloads": 50000
#     }
#   ],
#   "total": 13000,
#   "filtered": 12950
# }

# Search MCP hub
curl -X GET "http://localhost:3199/api/extensions/hub?q=database" \
  -b cookies.txt
```

--------------------------------

### MCP Hub API GET Handler

Source: https://github.com/euraika-labs/pan-ui/blob/main/docs/internal/engineering-task-breakdown.md

Handles GET requests for the MCP Hub API. Parses the 'q' query parameter, searches MCP servers, and excludes already installed extensions.

```typescript
import { NextResponse } from "next/server";
import { searchHubMcpServers } from "@/server/hermes/hub-mcp";
import { listRealExtensions } from "@/server/extensions/extensions";

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const query = searchParams.get("q");

  const installed = await listRealExtensions();
  const servers = await searchHubMcpServers(query ?? "");

  const filteredServers = servers.filter(
    server => !installed.find(ext => ext.name === server.name)
  );

  return NextResponse.json(filteredServers);
}
```

--------------------------------

### Run Verification Suite

Source: https://github.com/euraika-labs/pan-ui/blob/main/CONTRIBUTING.md

Execute the full verification suite, including linting, unit tests, and building the production version.

```bash
npm run lint && npm run test && npm run build
```

--------------------------------

### Create Plugin API Routes

Source: https://github.com/euraika-labs/pan-ui/blob/main/docs/internal/engineering-task-breakdown.md

Sets up CRUD endpoints for plugin management. All `execFile` calls are asynchronous with a 30-second timeout. Handles plugin installation, removal (user plugins only), and enabling/disabling by modifying `config.yaml` while preserving comments.

```typescript
import { execFile } from 'child_process';
import { parseDocument, visit } from 'yaml';
import { readFile, writeFile } from 'fs/promises';

// ... other imports

export async function POST(request: Request) {
  const { owner, repo } = await request.json();
  const identifier = `${owner}/${repo}`;

  try {
    await execFilePromise('hermes', ['plugins', 'install', identifier], {
      timeout: 30000,
    });
    return new Response(null, { status: 204 });
  } catch (error) {
    // Handle error
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }
}

async function execFilePromise(file: string, args: string[], options?: any): Promise<string> {
  return new Promise((resolve, reject) => {
    execFile(file, args, options, (error, stdout, stderr) => {
      if (error) {
        reject(new Error(`execFile error: ${error.message}\n${stderr}`));
      } else {
        resolve(stdout);
      }
    });
  });
}

export async function PUT(request: Request) {
  const { id, enabled } = await request.json();
  const configFile = await readFile('config.yaml', 'utf-8');
  const config = parseDocument(configFile);

  let disabledPlugins = config.plugins?.disabled ?? [];
  if (enabled) {
    disabledPlugins = disabledPlugins.filter((p: string) => p !== id);
  } else {
    if (!disabledPlugins.includes(id)) {
      disabledPlugins.push(id);
    }
  }

  // Preserve comments and formatting when writing back
  config.plugins = { ...config.plugins, disabled: disabledPlugins };
  await writeFile('config.yaml', config.toString());

  return new Response(null, { status: 204 });
}
```

--------------------------------

### Install Pan UI Systemd User Service

Source: https://github.com/euraika-labs/pan-ui/blob/main/docs/deployment.md

Installs, enables, and starts Pan UI as a systemd user service for persistent background operation. This ensures the service survives user logout. Includes commands for checking status, restarting, and viewing logs via journalctl.

```bash
npx @euraika-labs/pan-ui service install
systemctl --user status pan-ui
systemctl --user restart pan-ui
journalctl --user -u pan-ui -f
npx pan-ui service remove
```

--------------------------------

### Next.js Instrumentation for Startup Hooks

Source: https://github.com/euraika-labs/pan-ui/wiki/Architecture

Utilizes Next.js instrumentation for bootstrapping the gateway manager on application startup.

```typescript
instrumentation.ts
```

--------------------------------

### Get Skill Categories

Source: https://context7.com/euraika-labs/pan-ui/llms.txt

Use GET to retrieve a list of all available skill categories. Cookies are required for authentication.

```bash
curl -X GET http://localhost:3199/api/skills/categories \
  -b cookies.txt
```

--------------------------------

### Build Project

Source: https://github.com/euraika-labs/pan-ui/blob/main/docs/internal/alpha-release-checklist.md

Compile and bundle the project for deployment or distribution. This command is part of the engineering quality checks.

```bash
npm run build
```

--------------------------------

### Unified Marketplace Page

Source: https://github.com/euraika-labs/pan-ui/blob/main/docs/internal/engineering-task-breakdown.md

Creates a single `/marketplace` entry point with tabs for Skills, MCP Servers, and Plugins. Features a unified search bar that dispatches parallel queries and merges results, with a 300ms debounce on input.

```typescript
import { useState, useEffect, useCallback } from 'react';
import { useDebounce } from 'usehooks-ts';

// Assume useSkillsSearch, useMcpServersSearch, usePluginsSearch are defined elsewhere

function MarketplaceScreen() {
  const [searchQuery, setSearchQuery] = useState('');
  const debouncedSearchQuery = useDebounce(searchQuery, 300);

  const skills = useSkillsSearch(debouncedSearchQuery);
  const mcpServers = useMcpServersSearch(debouncedSearchQuery);
  const plugins = usePluginsSearch(debouncedSearchQuery);

  // Effect to trigger searches when debounced query changes
  useEffect(() => {
    // Trigger refetches or updates for each search hook
  }, [debouncedSearchQuery]);

  const handleSearchChange = useCallback((event: React.ChangeEvent<HTMLInputElement>) => {
    setSearchQuery(event.target.value);
  }, []);

  return (
    <div>
      <input type="text" placeholder="Search marketplace..." value={searchQuery} onChange={handleSearchChange} />
      {/* Tab components for Skills, MCP Servers, Plugins would go here */}
      {/* Merged and ranked results displayed below tabs */}
    </div>
  );
}

export default MarketplaceScreen;
```

--------------------------------

### List Installed Hermes Plugins

Source: https://context7.com/euraika-labs/pan-ui/llms.txt

Retrieves a list of all installed Hermes plugins, including their ID, name, enabled status, and version. Requires authentication via cookies.

```bash
# List plugins
curl -X GET http://localhost:3199/api/plugins \
  -b cookies.txt

# Response:
# {
#   "plugins": [
#     {
#       "id": "web-search",
#       "name": "Web Search Plugin",
#       "enabled": true,
#       "version": "1.2.0"
#     }
#   ]
# }
```

--------------------------------

### Run Pan UI as a Daemon

Source: https://github.com/euraika-labs/pan-ui/blob/main/docs/deployment.md

Starts Pan UI as a background process. Includes commands to check status, view logs, and stop the daemon cleanly. PID and log files are located in ~/.pan-ui.

```bash
npx @euraika-labs/pan-ui --daemon
npx pan-ui status                    # Check state
npx pan-ui logs                      # Tail output
npx pan-ui stop                      # Stop cleanly
```

--------------------------------

### Get Plugin Details

Source: https://github.com/euraika-labs/pan-ui/blob/main/docs/internal/sprint-tickets.md

Retrieves detailed information about a specific plugin by its ID.

```APIDOC
## GET /api/plugins/[id]

### Description
Retrieves detailed information for a specific plugin.

### Method
GET

### Endpoint
/api/plugins/[id]

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the plugin.

### Request Example
None

### Response
#### Success Response (200)
- **plugin** (object) - The details of the requested plugin.
  - **id** (string) - The unique identifier of the plugin.
  - **name** (string) - The name of the plugin.
  - **version** (string) - The version of the plugin.
  - **description** (string) - A brief description of the plugin.
  - **provides_tools** (array) - A list of tools provided by the plugin.
  - **requires_env** (object) - Environment variables required by the plugin.
  - **enabled** (boolean) - Indicates if the plugin is currently enabled.

#### Response Example
{
  "plugin": {
    "id": "plugin-id-1",
    "name": "Example Plugin",
    "version": "1.0.0",
    "description": "An example plugin.",
    "provides_tools": ["tool1"],
    "requires_env": {},
    "enabled": true
  }
}
```

--------------------------------

### Run Pan UI in Docker (Connect to Host Gateway)

Source: https://github.com/euraika-labs/pan-ui/blob/main/docs/deployment.md

Runs the Pan UI Docker container, connecting it to the host's gateway and Hermes Agent. This configuration is for connecting to a host gateway and requires specific environment variables and volume mounts.

```bash
# Run (connect to host gateway)
docker run -p 3199:3000 \
  --add-host=host.docker.internal:host-gateway \
  -v ~/.hermes:/home/node/.hermes \
  -e HERMES_MOCK_MODE=false \
  -e HOME=/home/node \
  -e HERMES_HOME=/home/node/.hermes/profiles/<your-profile> \
  -e HERMES_API_BASE_URL=http://host.docker.internal:8642 \
  pan-ui
```

--------------------------------

### System Overview Diagram

Source: https://github.com/euraika-labs/pan-ui/blob/main/docs/architecture.md

Illustrates the communication flow between the Browser, Pan (Next.js server), Hermes Gateway, Hermes Filesystem, and Hermes Agent sessions.

```text
  Browser ──── fetch / SSE ────▶ Pan (Next.js standalone server)
                                    │             │
                                    ▼             ▼
                              Hermes Gateway   Hermes Filesystem
                              :8642            ~/.hermes/
                              (auto-managed)   (skills, memory, profiles, state.db)
                                    │
                                    ▼
                              Hermes Agent sessions
                              (tools, memory, streaming)
```

--------------------------------

### Update Pan UI

Source: https://context7.com/euraika-labs/pan-ui/llms.txt

Checks for and installs the latest available updates for Pan UI.

```bash
npx pan-ui update
```

--------------------------------

### Check for Required Tools

Source: https://github.com/euraika-labs/pan-ui/blob/main/docs/internal/engineering-task-breakdown.md

Performs pre-flight checks to ensure required tools (e.g., npx, uv, docker) are installed on the system. Uses `execFile` to asynchronously probe for tool existence.

```typescript
import { execFile } from "child_process";
import { promisify } from "util";

const execFileAsync = promisify(execFile);

async function checkTool(tool: string): Promise<boolean> {
  try {
    await execFileAsync("which", [tool]);
    return true;
  } catch (error) {
    return false;
  }
}

export async function preflightChecks() {
  const requiredTools = ["npx", "uv", "docker"];
  const missingTools = [];

  for (const tool of requiredTools) {
    if (!(await checkTool(tool))) {
      missingTools.push(tool);
    }
  }

  if (missingTools.length > 0) {
    throw new Error(`Missing required tools: ${missingTools.join(', ')}`);
  }
}
```

--------------------------------

### Plugins API

Source: https://context7.com/euraika-labs/pan-ui/llms.txt

Endpoints for managing Hermes plugins, including listing, installing, enabling, and disabling.

```APIDOC
## GET /api/plugins

### Description
Lists all installed Hermes plugins.

### Method
GET

### Endpoint
/api/plugins

### Response
#### Success Response (200)
- **plugins** (array) - List of installed plugins with their details.

### Request Example
```bash
curl -X GET http://localhost:3199/api/plugins -b cookies.txt
```

### Response Example
```json
{
  "plugins": [
    {
      "id": "web-search",
      "name": "Web Search Plugin",
      "enabled": true,
      "version": "1.2.0"
    }
  ]
}
```
```

```APIDOC
## POST /api/plugins/install

### Description
Installs a plugin from a GitHub repository.

### Method
POST

### Endpoint
/api/plugins/install

### Request Body
- **identifier** (string) - Required - The GitHub repository identifier for the plugin (e.g., "github-user/hermes-plugin-name").

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the installation was successful.
- **identifier** (string) - The identifier of the installed plugin.

#### Error Response
- **error** (string) - Description of the error if installation fails (e.g., "Repository must contain plugin.yaml and __init__.py").

### Request Example
```json
{"identifier": "github-user/hermes-plugin-name"}
```

### Response Example
```json
{"success": true, "identifier": "github-user/hermes-plugin-name"}
```
```

```APIDOC
## POST /api/plugins/:id/enable

### Description
Enables or disables an installed plugin.

### Method
POST

### Endpoint
/api/plugins/:id/enable

### Path Parameters
- **id** (string) - Required - The ID of the plugin to enable or disable.

### Request Body
- **enabled** (boolean) - Required - Set to `true` to enable the plugin, `false` to disable.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **id** (string) - The ID of the plugin.
- **enabled** (boolean) - The new enabled state of the plugin.

### Request Example
```json
# Enable plugin
{"enabled": true}

# Disable plugin
{"enabled": false}
```

### Response Example
```json
{"success": true, "id": "web-search", "enabled": true}
```
```

--------------------------------

### Sync Hermes Agent Version

Source: https://context7.com/euraika-labs/pan-ui/llms.txt

Synchronizes the installed Hermes Agent to a version pinned by Pan UI.

```bash
npx pan-ui sync-hermes
```

--------------------------------

### Run Pan UI in Docker (Standalone Mock Mode)

Source: https://github.com/euraika-labs/pan-ui/blob/main/docs/deployment.md

Runs the Pan UI Docker container in standalone mode with mock data enabled. Port 3199 on the host is mapped to port 3000 in the container.

```bash
# Run (standalone, mock mode)
docker run -p 3199:3000 -e HERMES_MOCK_MODE=true pan-ui
```

--------------------------------

### MCP Extensions API

Source: https://context7.com/euraika-labs/pan-ui/llms.txt

Endpoints for managing MCP extensions, including listing, browsing the hub, installing, and testing.

```APIDOC
## GET /api/extensions

### Description
Lists all installed MCP extensions and their available tools.

### Method
GET

### Endpoint
/api/extensions

### Response
#### Success Response (200)
- **extensions** (array) - List of installed extensions with their tools.
- **tools** (array) - List of available tools across all extensions.

### Request Example
```bash
curl -X GET http://localhost:3199/api/extensions -b cookies.txt
```

### Response Example
```json
{
  "extensions": [
    {
      "id": "filesystem",
      "name": "Filesystem",
      "status": "connected",
      "tools": ["read_file", "write_file", "list_directory"]
    }
  ],
  "tools": [
    {"name": "read_file", "extensionId": "filesystem", "description": "Read file contents"}
  ]
}
```
```

```APIDOC
## GET /api/extensions/hub

### Description
Browses the MCP registry for available servers to install. Supports searching via query parameters.

### Method
GET

### Endpoint
/api/extensions/hub

### Query Parameters
- **q** (string) - Optional - Search query for filtering servers.

### Response
#### Success Response (200)
- **servers** (array) - List of available servers in the registry.
- **total** (integer) - Total number of servers in the registry.
- **filtered** (integer) - Number of servers matching the search query.

### Request Example
```bash
# Browse MCP hub
curl -X GET http://localhost:3199/api/extensions/hub -b cookies.txt

# Search MCP hub
curl -X GET "http://localhost:3199/api/extensions/hub?q=database" -b cookies.txt
```

### Response Example
```json
{
  "servers": [
    {
      "name": "github",
      "description": "GitHub API integration",
      "author": "official",
      "downloads": 50000
    }
  ],
  "total": 13000,
  "filtered": 12950
}
```
```

```APIDOC
## POST /api/extensions/hub/install

### Description
Installs an MCP server from the registry.

### Method
POST

### Endpoint
/api/extensions/hub/install

### Request Body
- **identifier** (string) - Required - The identifier of the MCP server to install (e.g., "@modelcontextprotocol/server-github").
- **env** (object) - Optional - Environment variables to set for the installed server.
  - **GITHUB_TOKEN** (string) - Example environment variable.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the installation was successful.
- **identifier** (string) - The identifier of the installed server.
- **extensionId** (string) - The ID assigned to the installed extension.

### Request Example
```json
{
  "identifier": "@modelcontextprotocol/server-github",
  "env": {
    "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
  }
}
```

### Response Example
```json
{
  "success": true,
  "identifier": "@modelcontextprotocol/server-github",
  "extensionId": "server-github"
}
```
```

```APIDOC
## POST /api/extensions/:id/test

### Description
Tests connectivity to an installed MCP server.

### Method
POST

### Endpoint
/api/extensions/:id/test

### Path Parameters
- **id** (string) - Required - The ID of the extension to test.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the test was successful.
- **responseTime** (integer) - The time taken for the test in milliseconds.
- **tools** (array) - List of tools available for the tested extension.

### Request Example
```bash
curl -X POST http://localhost:3199/api/extensions/filesystem/test -b cookies.txt
```

### Response Example
```json
{
  "success": true,
  "responseTime": 45,
  "tools": ["read_file", "write_file", "list_directory"]
}
```
```

--------------------------------

### Run Project Tests

Source: https://github.com/euraika-labs/pan-ui/blob/main/CONTRIBUTING.md

Commands to run different types of tests and builds for the project: ESLint for linting, Vitest for unit tests, and Playwright for end-to-end tests.

```bash
npm run lint          # ESLint
```

```bash
npm run test          # Vitest unit tests
```

```bash
npm run build         # Production build
```

```bash
npm run test:e2e      # Playwright e2e (requires running dev server)
```

--------------------------------

### Project Structure Overview

Source: https://github.com/euraika-labs/pan-ui/blob/main/docs/architecture.md

Details the directory layout of the Pan UI project, highlighting key directories like app, features, server, components, and lib.

```text
src/
├── app/                  # Next.js App Router
│   ├── api/              # Server-side API routes (Route Handlers)
│   │   ├── chat/         # Chat streaming, session CRUD
│   │   ├── skills/       # Skills CRUD, hub search, categories
│   │   ├── memory/       # User/agent memory, context inspector
│   │   ├── profiles/     # Profile CRUD and config editing
│   │   ├── extensions/   # MCP extension management
│   │   └── runtime/      # Health, approvals, runs, telemetry, export
│   ├── chat/             # Chat page
│   ├── skills/           # Skills browser page
│   ├── extensions/       # Extensions page
│   ├── memory/           # Memory page
│   ├── profiles/         # Profiles page
│   ├── settings/         # Settings and operations pages
│   └── login/            # Login page
├── features/             # UI feature modules (components + hooks per feature)
│   ├── chat/             # Chat screen, composer, message rendering
│   └── sessions/         # Session sidebar, source badges, source filtering
├── server/               # Server-side Hermes bridge (filesystem reads, API calls)
│   └── hermes/
│       ├── gateway-manager.ts  # Auto-start and monitor the Hermes gateway
│       ├── client.ts           # HTTP client for Hermes API
│       ├── config.ts           # Gateway URL, API key, timeout config
│       └── ...
├── components/           # Shared layout and UI components
├── lib/                  # Types, schemas, Zustand stores, utilities
└── styles/               # CSS custom properties and theme tokens
instrumentation.ts        # Next.js startup hook — bootstraps gateway manager
middleware.ts             # Auth middleware (cookie check, redirect to /login)
bin/
└── pan-ui.mjs            # CLI entry point: setup wizard, standalone server, daemon, systemd
```

--------------------------------

### Pan-UI Development Commands

Source: https://github.com/euraika-labs/pan-ui/wiki/Development

Common npm scripts for development tasks including building, testing, and linting.

```bash
npm run dev
```

```bash
npm run build
```

```bash
npm run start
```

```bash
npm run lint
```

```bash
npm run test
```

```bash
npm run test:e2e
```