/extension-development

name: extension-development
description: Build, install, and hot-reload Nimbalyst extensions using MCP tools. Use when developing, testing, or iterating on Nimbalyst extensions.

Extension Development in Nimbalyst

Nimbalyst provides MCP tools for building, installing, and hot-reloading extensions directly from within the running app. This enables rapid iteration on extension development without manually running build commands.

The recommended in-app scaffold flow uses `File > New Extension Project`, `Developer > New Extension Project`, or the Extension Developer Kit's `/new-extension` command. Enable Extension Dev Tools in Settings > Advanced before using the build/install workflow.

Available MCP Tools

Build Extension

mcp__nimbalyst-extension-dev__extension_build

Runs the project's `build` script (usually vite build) with pnpm if the project uses pnpm, npm otherwise.

**Parameters:**

• `path`: Absolute path to the extension project root (directory containing package.json and manifest.json)

**Returns:** Build output including any errors or warnings.

Install Extension

mcp__nimbalyst-extension-dev__extension_install

Installs a built extension into the running Nimbalyst instance. The extension must be built first.

**Parameters:**

• `path`: Absolute path to the extension project root

**Returns:** Installation status and any validation warnings.

Hot Reload Extension

mcp__nimbalyst-extension-dev__extension_reload

Rebuilds and reinstalls an extension in one step. This is the most common tool for iterating on extension development.

**Parameters:**

• `extensionId`: The extension ID from manifest.json (e.g., "com.nimbalyst.my-extension")
• `path`: Absolute path to the extension project root

**Returns:** Build and reload status.

Uninstall Extension

mcp__nimbalyst-extension-dev__extension_uninstall

Removes an installed extension from the running Nimbalyst instance.

**Parameters:**

• `extensionId`: The extension ID to uninstall

Get Extension Status

mcp__nimbalyst-extension-dev__extension_get_status

Gets the current status of an installed extension, including whether it loaded successfully and what it contributes.

**Parameters:**

• `extensionId`: The extension ID to query

Restart Nimbalyst

mcp__nimbalyst-extension-dev__restart_nimbalyst

Restarts the entire Nimbalyst application. **Only use when explicitly requested by the user.**

Testing Tools

Run Playwright Tests

mcp__nimbalyst-extension-dev__extension_test_run

Execute Playwright scripts against the running Nimbalyst instance via CDP. Supports inline scripts or `.spec.ts` file paths.

**Parameters:**

• `script`: Inline Playwright code (runs inside an async test with `page` connected to Nimbalyst)
• `testFile`: Absolute path to a `.spec.ts` file
• `timeout`: Max execution time in ms (default: 30000)

Provide either `script` or `testFile`, not both.

Open File for Testing

mcp__nimbalyst-extension-dev__extension_test_open_file

Opens a file in Nimbalyst and waits for the editor to mount. Use before running tests that need a specific file open.

**Parameters:**

• `filePath`: Absolute path to the file to open
• `waitForExtension`: Extension ID to wait for (waits until the extension's editor container renders)
• `timeout`: Max wait time in ms (default: 5000)

Test AI Tool Handler

mcp__nimbalyst-extension-dev__extension_test_ai_tool

Execute an extension's AI tool handler directly and return the result. Bypasses full MCP routing.

**Parameters:**

• `extensionId`: The extension ID
• `toolName`: Tool name without extension prefix (e.g., "get_elements")
• `args`: Arguments object to pass to the handler
• `filePath`: For editor-scoped tools: file path for context

Development Workflow

Initial Setup

1. Create extension project with `/new-extension <path> <name> [file-patterns]` 2. Implement the extension code 3. Build with `extension_build` 4. Install with `extension_install` 5. Test in Nimbalyst

Iteration Loop with Testing

1. Make code changes 2. Run `extension_reload` to rebuild and reinstall 3. Run `extension_get_status` to verify it loaded 4. Run `extension_test_open_file` to open a sample file 5. Run `extension_test_run` with Playwright scripts to verify behavior 6. Use `capture_editor_screenshot` for visual verification 7. Check `get_renderer_debug_logs` for runtime errors 8. Fix issues and repeat from step 1

**Inline test example:**

extension_test_run({
  script: `
    const editor = page.locator('[data-extension-id="com.nimbalyst.my-ext"]');
    await expect(editor).toBeVisible();
    await editor.locator('.save-btn').click();
    await expect(editor.locator('.status')).toHaveText('Saved');
  `
})

**Test file example:**

extension_test_run({ testFile: "/path/to/extension/tests/basics.spec.ts" })

Debugging

1. Check extension status with `extension_get_status` 2. Read logs with `mcp__nimbalyst-extension-dev__get_main_process_logs` (filter by component: "EXTENSION") 3. Check renderer logs with `mcp__nimbalyst-extension-dev__get_renderer_debug_logs`

Important Notes

• **Always build before install** - `extension_install` requires a pre-built extension
• **Use `extension_reload` for iteration** - It combines build + reinstall in one step
• **Check manifest validation** - Build and install tools validate manifest.json and report warnings
• **Extensions load on app start** - For full reload, user may need to restart Nimbalyst
• **Never restart without permission** - Only use `restart_nimbalyst` when the user explicitly asks

Common Issues

"Extension not found" after install

• Check that the extension ID in manifest.json matches what you're querying
• Verify the build output exists in `dist/index.js`

Build fails

• Check that dependencies were installed in the extension directory (`pnpm install` or `npm install`, matching its lockfile)
• Verify vite.config.ts is properly conf