# Building Your Own Extensions

Build your own Nimbalyst extension with custom editors, AI tools, panels, and themes, packaged with a manifest that declares what it adds.

This section is the developer documentation for building Nimbalyst extensions: custom editors, AI tools, panels, themes, and more. It is written for developers comfortable with React and TypeScript.

Extensions are self-contained packages with a `manifest.json` that declares their contributions. Nimbalyst is open source, and the built-in extensions live alongside the app source in [github.com/nimbalyst](https://github.com/nimbalyst); the fastest way to learn the extension API is to read those built-in extensions.

The [extensions feature page](https://nimbalyst.com/features/extensions/) covers what extensions can contribute to the app.

## What Can Extensions Do?

- **Custom Editors**: new ways to view and edit file types (spreadsheets, diagrams, 3D models)
- **AI Tools**: tools that Claude can use to interact with your extension
- **AI Completions**: call chat models (Claude, OpenAI, LM Studio) directly from your extension
- **Panels**: sidebar panels, fullscreen views, floating windows, or bottom panels
- **Settings Pages**: application- or project-scoped settings with repository context
- **Project Filesystem Access**: read and update related project files from a custom editor
- **Tracker References**: typed item pickers and live tracker reference chips
- **Themes**: custom color themes
- **Slash Commands**: commands users can invoke from the chat
- **File Icons**: custom icons for file types in the sidebar
- **New File Types**: entries in the "New File" menu

## Quick Start

The recommended workflow is to create and iterate on extensions from inside Nimbalyst:

1. Enable **Extension Dev Tools** in **Settings > Application > Advanced**
2. Use `File > New Extension Project` or ask Claude to run `/new-extension`
3. Describe the extension you want Claude to build from the starter scaffold
4. Ask Claude to build and install the extension with `extension_build` and `extension_install`
5. Use `extension_reload` for rebuild plus reinstall during iteration

See [Getting Started](https://nimbalyst.com/docs/extensions/building-extensions/getting-started/) for a step-by-step walkthrough.

## Project Structure

A typical extension project:

```
my-extension/
  manifest.json       # Extension metadata and contributions
  package.json        # npm dependencies
  tsconfig.json       # TypeScript configuration
  vite.config.ts      # Build configuration
  src/
    index.ts          # Extension entry point (activate/deactivate)
    components/       # React components
    styles.css        # Scoped styles
```

## Development Workflow

1. **Create**: use `/new-extension` inside Nimbalyst or copy a starter project
2. **Develop**: edit files in your extension project
3. **Build**: Claude uses `extension_build` to compile
4. **Install**: Claude uses `extension_install` to load it
5. **Test**: open a file with your extension's file type
6. **Iterate**: Claude uses `extension_reload` for hot updates

## Core Concepts

### The Extension Manifest

Every extension needs a `manifest.json` that describes what it provides. At minimum:

```json
{
  "id": "com.example.my-editor",
  "name": "My Editor",
  "version": "1.0.0",
  "main": "dist/index.js"
}
```

See [Manifest Reference](https://nimbalyst.com/docs/extensions/building-extensions/manifest-reference/) for the complete schema.

### The EditorHost Contract

Custom editors receive a `host` prop that handles all communication with Nimbalyst: loading and saving files, tracking dirty state, theme changes, and AI diff mode. The `useEditorLifecycle` hook wraps the host into a single, clean API.

See [Custom Editors](https://nimbalyst.com/docs/extensions/building-extensions/custom-editors/) for the full guide.

### AI Tool Integration

AI tools let Claude interact with your editor programmatically. Define tools with a name, description, input schema, and handler function. Claude reads the description to decide when to call your tool.

See [AI Tools](https://nimbalyst.com/docs/extensions/building-extensions/ai-tools/) for examples and best practices.

### Permissions

Extensions declare the capabilities they need:

| Permission | What It Grants |
| --- | --- |
| `filesystem` | Read and write files in the workspace |
| `ai` | Register AI tools and call chat/completion models directly |
| `network` | Make network requests to external services |

## Documentation

| Document | Description |
| --- | --- |
| [Getting Started](https://nimbalyst.com/docs/extensions/building-extensions/getting-started/) | Create your first extension in 10 minutes |
| [Custom Editors](https://nimbalyst.com/docs/extensions/building-extensions/custom-editors/) | Build editors for new file types |
| [AI Tools](https://nimbalyst.com/docs/extensions/building-extensions/ai-tools/) | Add tools that Claude can use |
| [Manifest Reference](https://nimbalyst.com/docs/extensions/building-extensions/manifest-reference/) | Complete manifest.json schema |
| [API Reference](https://nimbalyst.com/docs/extensions/building-extensions/api-reference/) | TypeScript types and interfaces |

## Prerequisites

- Nimbalyst with Extension Dev Tools enabled (**Settings > Application > Advanced**)
- Node.js 18+
- Basic knowledge of React and TypeScript

## Built-in Extension Examples

Study the built-in extensions for patterns and best practices:

| Extension | File Types | Notable Patterns |
| --- | --- | --- |
| Excalidraw | `.excalidraw` | Imperative API via refs, 19 AI tools |
| CSV Spreadsheet | `.csv`, `.tsv` | RevoGrid with custom save, formula support |
| DataModelLM | `.prisma` | Zustand store, screenshot export |
| MockupLM | `.mockup.html` | iframe preview, AI generation |
| SQLite Browser | `.db`, `.sqlite` | Read-only binary editor, 9 AI tools |

These are all in `packages/extensions/` in the [Nimbalyst repository on GitHub](https://github.com/nimbalyst).