Building Your Own Extensions

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; the fastest way to learn the extension API is to read those built-in extensions.

The extensions feature page 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 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:

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

See 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 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 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	Create your first extension in 10 minutes
Custom Editors	Build editors for new file types
AI Tools	Add tools that Claude can use
Manifest Reference	Complete manifest.json schema
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.