Hello Editor

Editing: {host.filePath}

</div>
  );
}
```

**Key points:**

* `useEditorLifecycle` handles loading, saving, file watching, echo detection, and dirty state
* `applyContent` pushes content into the editor (on load, external changes)
* `getCurrentContent` pulls content from the editor (on save)
* Call `markDirty()` when the user edits; the hook manages `host.setDirty()` for you
* Content lives in a ref, not React state; the textarea uses `defaultValue`

## Step 8: Add Build Script

Update your `package.json` to add a build script:

```json
{
  "scripts": {
    "build": "vite build"
  }
}
```

## Step 9: Build and Install

Now ask Claude to build and install your extension:

> "Build and install my extension from \~/my-first-extension"

Claude will use the `extension_build` and `extension_install` tools to compile and load your extension.

## Step 10: Test It

1. Create a new file with the `.hello` extension
2. Your custom editor should appear instead of the default text editor
3. Make changes and save; they persist to the file

## Next Steps

* Add styling with a `styles.css` file
* Add AI tools so Claude can interact with your editor
* Add a toolbar with actions
* Handle more complex file formats

See the [custom-editors.md](/extensions/building-extensions/custom-editors) guide for more advanced editor development.

## Troubleshooting

### Extension doesn't load

1. Check the console for errors (View > Toggle Developer Tools)
2. Verify your `manifest.json` has a valid `id` field
3. Make sure `dist/index.js` exists after building

### Editor doesn't appear for file type

1. Check that `filePatterns` in the manifest matches your file extension
2. Verify the `component` name matches what you export in `components`

### Changes don't appear after editing

Ask Claude to reload the extension:

> "Reload my hello-editor extension"

This will rebuild and hot-reload without restarting Nimbalyst.

# Custom Editors

Build a custom editor extension for Nimbalyst: the useEditorLifecycle hook, the EditorHost interface, undo and redo, and large file handling.

This guide covers building custom editor extensions: the `useEditorLifecycle` hook, the `EditorHost` interface, styling, and patterns for larger editors. It is for extension developers; read [Getting Started](/extensions/building-extensions/getting-started) first if you have not built an extension yet.

Custom editors are the most powerful extension type. They let you create entirely new ways to view and edit file types, from spreadsheets to diagrams to 3D models.

## How Custom Editors Work

When a user opens a file, Nimbalyst checks if any extension has registered a custom editor for that file type. If found, your React component is rendered instead of the default editor.

Your component receives a single `host` prop from Nimbalyst. The host handles loading, saving, dirty tracking, file change notifications, and optional features like diff mode.

## The useEditorLifecycle Hook

The recommended way to build custom editors is with the `useEditorLifecycle` hook. It replaces all manual `EditorHost` subscription boilerplate (loading, saving, echo detection, file watching, diff mode, theme) with a single hook call.

```tsx
import { useEditorLifecycle } from '@nimbalyst/extension-sdk';
import type { EditorHostProps } from '@nimbalyst/extension-sdk';

export function MyEditor({ host }: EditorHostProps) {
  const editorRef = useRef<MyEditorAPI>(null);

const { isLoading, error, theme, markDirty, diffState } = useEditorLifecycle(host, {
    applyContent: (data) => editorRef.current?.load(data),
    getCurrentContent: () => editorRef.current?.getData() ?? defaultValue,
    parse: (raw) => JSON.parse(raw),
    serialize: (data) => JSON.stringify(data),
  });

if (error) return <div>Failed to load: {error.message}</div>;
  if (isLoading) return <div>Loading...</div>;

return <MyEditorComponent ref={editorRef} onChange={markDirty} theme={theme} />;
}
```

### How It Works

The hook interacts with your editor through pull/push callbacks; content never lives in React state:

* **`applyContent(parsed)`**: Called to push content INTO the editor (on initial load, on external file change). Update your editor's internal state here.
* **`getCurrentContent()`**: Called to pull content FROM the editor (on save). Return the current state. Omit for read-only editors.
* **`parse(raw)`**: Convert raw file string into your editor's format. Omit if your editor works with raw strings.
* **`serialize(data)`**: Convert your editor's format back to a string for saving. Omit if already a string.

### What It Returns

| Field              | Type                        | Description                                   |
| ------------------ | --------------------------- | --------------------------------------------- |
| `isLoading`        | `boolean`                   | `true` until initial content is loaded        |
| `error`            | `Error \| null`             | Error from initial load                       |
| `theme`            | `string`                    | Current theme name (reactive)                 |
| `markDirty`        | `() => void`                | Call when the user makes an edit              |
| `isDirty`          | `boolean`                   | Whether unsaved changes exist                 |
| `diffState`        | `DiffState<T> \| null`      | AI edit diff with `accept`/`reject` callbacks |
| `toggleSourceMode` | `(() => void) \| undefined` | Toggle to Monaco source view                  |
| `isSourceMode`     | `boolean`                   | Whether source mode is active                 |

### Editor Architecture Patterns

The hook supports three common architectures:

**Library-managed** (Excalidraw, Three.js): callbacks talk to the library's imperative API via refs:

```tsx
const apiRef = useRef<ExcalidrawImperativeAPI>(null);
useEditorLifecycle(host, {
  applyContent: (elements) => apiRef.current?.updateScene({ elements }),
  getCurrentContent: () => apiRef.current?.getSceneElements() ?? [],
  parse: (raw) => JSON.parse(raw).elements,
  serialize: (elements) => JSON.stringify({ elements }),
});
```

**Store-managed** (Zustand, custom stores): callbacks talk to a store:

```tsx
const storeRef = useRef(createMyStore());
useEditorLifecycle(host, {
  applyContent: (doc) => storeRef.current.getState().loadDocument(doc),
  getCurrentContent: () => storeRef.current.getState().document,
  parse: parseDocument,
  serialize: serializeDocument,
});
```

**Read-only** (PDF viewer, SQLite browser): only `applyContent`, no save:

```tsx
const dataRef = useRef<ArrayBuffer | null>(null);
const [, forceRender] = useReducer((x) => x + 1, 0);
useEditorLifecycle(host, {
  applyContent: (data) => { dataRef.current = data; forceRender(); },
  binary: true,
});
```

### Additional Options

| Option             | Type                           | Description                                                                                   |
| ------------------ | ------------------------------ | --------------------------------------------------------------------------------------------- |
| `binary`           | `boolean`                      | Use `loadBinaryContent()` instead of `loadContent()`. For PDFs, images, SQLite, etc.          |
| `onLoaded`         | `() => void`                   | Called after initial content is loaded and applied                                            |
| `onExternalChange` | `(content: T) => void`         | Called when an external file change is detected (not from our own save)                       |
| `onSave`           | `() => Promise<void>`          | Replace the default save flow. Use for async content extraction (e.g., RevoGrid)              |
| `onDiffRequested`  | `(config: DiffConfig) => void` | Replace default diff handling. Use for specialized diff rendering (e.g., cell-level CSV diff) |
| `onDiffCleared`    | `() => Promise<void>`          | Replace default diff cleanup. Paired with `onDiffRequested`                                   |

### Echo Detection

The hook automatically ignores file change notifications caused by our own saves. This prevents the editor from reloading content immediately after saving, a common source of bugs in manual implementations.

## EditorHost Interface

The `useEditorLifecycle` hook wraps this interface. You rarely need to use it directly, but it's useful to understand what's available. This is an abbreviated view of the core members; see the [API Reference](/extensions/building-extensions/api-reference) for the full interface, including storage, chat context, and editor API registration.

```typescript
interface EditorHostProps {
  host: EditorHost;
}

interface EditorHost {
  readonly filePath: string;
  readonly fileName: string;
  readonly theme: string;
  readonly isActive: boolean;
  readonly workspaceId?: string;
  readonly fs?: EditorHostFileSystem;

loadContent(): Promise<string>;
  loadBinaryContent(): Promise<ArrayBuffer>;
  onFileChanged(callback: (newContent: string) => void): () => void;
  setDirty(isDirty: boolean): void;
  saveContent(content: string | ArrayBuffer): Promise<void>;
  onSaveRequested(callback: () => void | Promise<void>): () => void;
  onThemeChanged(callback: (theme: string) => void): () => void;
  openHistory(): void;

// Diff mode (AI edits)
  onDiffRequested?(callback: (config: DiffConfig) => void): () => void;
  reportDiffResult?(result: DiffResult): void;
  onDiffCleared?(callback: () => void): () => void;

// Source mode (toggle to Monaco)
  toggleSourceMode?(): void;
  onSourceModeChanged?(callback: (isActive: boolean) => void): () => void;
  isSourceModeActive?(): boolean;
}
```

## Key Concepts

### Content Ownership

Nimbalyst editors use a **host-driven save model** where the editor owns its content state:

1. **Initial load**: The hook calls `host.loadContent()` and passes the result to your `applyContent` callback
2. **Dirty tracking**: Call `markDirty()` when the user makes changes
3. **Saving**: The hook subscribes to save events and calls your `getCurrentContent` to get the data
4. **External changes**: The hook detects external file changes, filters echoes, and calls `applyContent`

### Why Not Pass Content as a Prop?

The `EditorHost` model is more efficient for complex editors:

* Spreadsheets with thousands of cells do not need to serialize on every keystroke
* Diagram editors can maintain rich object graphs internally
* Binary editors can load and save `ArrayBuffer` data without pretending everything is text
* Imperative editor libraries (Excalidraw, RevoGrid, Three.js) cannot be re-rendered anyway

## Accessing Other Project Files

A file-backed custom editor can use the optional `host.fs` service when it needs to read or update project files beyond the document currently open in the editor. This is useful for CAD projects, generated assets, compilers, analyzers, and editors backed by several related files.

```tsx
const snapshots = await host.fs?.read([
  'models/assembly.json',
  'models/materials.json',
]);

const assembly = snapshots?.[0];
if (assembly?.exists && assembly.content && assembly.sha256) {
  await host.fs?.write({
    label: 'Update assembly',
    actor: 'user',
    changes: [
      {
        path: assembly.path,
        expectedSha256: assembly.sha256,
        content: updateAssembly(assembly.content),
      },
    ],
  });
}
```

The service:

* Restricts paths to the active workspace, including protection against symlink escapes.
* Returns a SHA-256 version token with every read.
* Uses the version token for compare-and-swap writes so an editor cannot silently overwrite a newer file.
* Refuses to write a file that has unsaved changes in another open editor.
* Records successful writes in Nimbalyst document history.
* Can observe external project-file changes through `host.fs.onChanged()`.

`host.fs` is optional. It is not present for virtual, embedded, offscreen, or collaborative hosts that cannot provide raw local-disk semantics. Always guard it before use and provide a clear read-only or unavailable state.

Use `loadContent()` and `saveContent()` for the editor's primary file. Use `host.fs` only for additional project files.

## Registering the Editor

In your `manifest.json`:

```json
{
  "contributions": {
    "customEditors": [
      {
        "filePatterns": ["*.mytype", "*.myt"],
        "displayName": "My Type Editor",
        "component": "MyEditor",
        "supportsDiffMode": false,
        "showDocumentHeader": false
      }
    ]
  }
}
```

And export it from your entry point:

```typescript
// src/index.ts
import { MyEditor } from './MyEditor';

export const components = {
  MyEditor,
};
```

## Styling Your Editor

### Using CSS Variables

Nimbalyst provides CSS variables for theming. Always use these instead of hardcoded colors:

```css
.my-editor {
  background: var(--nim-bg);
  color: var(--nim-text);
  border: 1px solid var(--nim-border);
}

.my-editor-toolbar {
  background: var(--nim-bg-secondary);
  border-bottom: 1px solid var(--nim-border);
}

.my-editor-button:hover {
  background: var(--nim-bg-hover);
}
```

### Available CSS Variables

| Variable             | Purpose                   |
| -------------------- | ------------------------- |
| `--nim-bg`           | Main background           |
| `--nim-bg-secondary` | Toolbar/panel background  |
| `--nim-bg-tertiary`  | Nested element background |
| `--nim-bg-hover`     | Hover state background    |
| `--nim-text`         | Main text color           |
| `--nim-text-muted`   | Muted text                |
| `--nim-text-faint`   | Very muted text           |
| `--nim-border`       | Main borders              |
| `--nim-primary`      | Accent/brand color        |

### Including Styles

Create a `styles.css` file and reference it in your manifest:

```json
{
  "styles": "dist/index.css"
}
```

Import it in your entry point:

```typescript
// src/index.ts
import './styles.css';
```

## Handling Large Files

For large files, consider:

### Virtualization

Only render visible rows/items:

```tsx
import { useVirtualizer } from '@tanstack/react-virtual';

function LargeListEditor({ items }) {
  const parentRef = useRef<HTMLDivElement>(null);

const virtualizer = useVirtualizer({
    count: items.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 35,
  });

return (
    <div ref={parentRef} style={{ height: '100%', overflow: 'auto' }}>
      <div style={{ height: virtualizer.getTotalSize() }}>
        {virtualizer.getVirtualItems().map(virtualRow => (
          <div
            key={virtualRow.key}
            style={{
              position: 'absolute',
              top: virtualRow.start,
              height: virtualRow.size,
            }}
          >
            {items[virtualRow.index]}
          </div>
        ))}
      </div>
    </div>
  );
}
```

### Lazy Parsing

Parse content incrementally:

```typescript
function parseContentLazy(content: string) {
  // Return a lightweight wrapper that parses on demand
  return {
    getRow(index: number) {
      // Parse just this row when needed
    },
    get length() {
      // Count rows without full parse
    }
  };
}
```

## Undo/Redo Support

Nimbalyst doesn't provide built-in undo for custom editors. Implement your own:

```tsx
import { useState, useCallback } from 'react';

function useUndoRedo<T>(initialState: T) {
  const [history, setHistory] = useState<T[]>([initialState]);
  const [index, setIndex] = useState(0);

const state = history[index];

const setState = useCallback((newState: T) => {
    const newHistory = history.slice(0, index + 1);
    newHistory.push(newState);
    setHistory(newHistory);
    setIndex(newHistory.length - 1);
  }, [history, index]);

const undo = useCallback(() => {
    if (index > 0) setIndex(index - 1);
  }, [index]);

const redo = useCallback(() => {
    if (index < history.length - 1) setIndex(index + 1);
  }, [index, history.length]);

const canUndo = index > 0;
  const canRedo = index < history.length - 1;

return { state, setState, undo, redo, canUndo, canRedo };
}
```

## Keyboard Shortcuts

Handle keyboard shortcuts in your editor:

```tsx
function MyEditor({ content, onChange }) {
  useEffect(() => {
    const handleKeyDown = (e: KeyboardEvent) => {
      // Cmd/Ctrl + Z for undo
      if ((e.metaKey || e.ctrlKey) && e.key === 'z' && !e.shiftKey) {
        e.preventDefault();
        undo();
      }
      // Cmd/Ctrl + Shift + Z for redo
      if ((e.metaKey || e.ctrlKey) && e.key === 'z' && e.shiftKey) {
        e.preventDefault();
        redo();
      }
    };

window.addEventListener('keydown', handleKeyDown);
    return () => window.removeEventListener('keydown', handleKeyDown);
  }, [undo, redo]);

// ...
}
```

## Example: Simple Table Editor

A complete example using `useEditorLifecycle`:

```tsx
import React, { useRef } from 'react';
import { useEditorLifecycle } from '@nimbalyst/extension-sdk';
import type { EditorHostProps } from '@nimbalyst/extension-sdk';

export function TableEditor({ host }: EditorHostProps) {
  const dataRef = useRef<string[][]>([]);
  const tableRef = useRef<HTMLTableElement>(null);

const parseCSV = (text: string): string[][] =>
    text.split('\n').map(row => row.split(',').map(cell => cell.trim()));

const serializeCSV = (data: string[][]): string =>
    data.map(row => row.join(',')).join('\n');

const { isLoading, error, theme, markDirty } = useEditorLifecycle(host, {
    applyContent: (data: string[][]) => {
      dataRef.current = data;
      renderTable();
    },
    getCurrentContent: () => dataRef.current,
    parse: parseCSV,
    serialize: serializeCSV,
  });

function renderTable() {
    // Re-render table imperatively or use forceUpdate
  }

if (error) return <div>Error: {error.message}</div>;
  if (isLoading) return <div>Loading...</div>;

return (
    <div style={{ padding: '10px', overflow: 'auto', height: '100%' }}>
      <table ref={tableRef} style={{ borderCollapse: 'collapse', width: '100%' }}>
        <tbody>
          {dataRef.current.map((row, rowIndex) => (
            <tr key={rowIndex}>
              {row.map((cell, colIndex) => (
                <td key={colIndex} style={{ border: '1px solid var(--nim-border)' }}>
                  <input
                    defaultValue={cell}
                    onChange={e => {
                      dataRef.current[rowIndex][colIndex] = e.target.value;
                      markDirty();
                    }}
                    style={{
                      width: '100%',
                      padding: '4px',
                      border: 'none',
                      background: 'transparent',
                      color: 'var(--nim-text)'
                    }}
                  />
                </td>
              ))}
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  );
}
```

## Best Practices

### Shared documents

`useEditorLifecycle` handles file-backed editing. A custom editor that opts into shared documents also needs two collaboration pieces:

* `useCollaborativeEditor` binds one mounted editor to the shared Y.Doc for live edits and presence.
* A `CollabContentAdapter` lets the host seed a shared document from a file, export it, build revision snapshots and search text, and apply structured AI edits even when no tab is open.

Register one adapter per `documentType` during `activate()` with `context.services.collab.registerContentAdapter(adapter)`, and declare matching `collaboration` metadata on the custom editor contribution. Implement `toPlainText` for search and AI read access; AI write access also requires `toStructured` and `applyStructuredPatch` so the host has a typed patch contract.

If the Y.Doc layout changes, bump the adapter's `layoutVersion` and provide migrations. Adapters run in the client against an already decrypted Y.Doc; the collaboration server continues to treat document state as opaque encrypted data.

1. **Use `useEditorLifecycle`** - Handles loading, saving, echo detection, file watching, diff mode, and theme
2. **Keep content out of React state** - Use refs or external stores for editor data
3. **Use CSS variables** - Your editor should respect the user's theme
4. **Handle empty content** - The file might be new or empty
5. **Call `markDirty()`** - Not `host.setDirty()` directly -- the hook tracks dirty state for you
6. **Test with large files** - Ensure your editor performs well
7. **Register a collaboration adapter** if the file type can be shared, so history, export, search, re-upload, and AI features can understand it

## Next Steps

* Add [ai-tools.md](/extensions/building-extensions/ai-tools) so Claude can interact with your editor
* See [manifest-reference.md](/extensions/building-extensions/manifest-reference) for all configuration options
* Check the built-in extensions in `packages/extensions/` in the Nimbalyst repository for production examples

# AI Tools

Add AI tools to a Nimbalyst extension so coding agents can read and change your custom file types instead of only seeing raw file content.

AI tools let supported coding agents interact with your extension programmatically. When you add tools, an agent can read structured data, make targeted changes, and help users work with your custom file types.

## Why Add AI Tools?

Without tools, an agent can only:

* Read the raw file content
* Suggest edits to the raw content

With tools, an agent can:

* Query structured data ("What columns are in this spreadsheet?")
* Make targeted changes ("Add a row with these values")
* Perform complex operations ("Sort by the date column")
* Understand your data model ("What entities are defined?")

## Tool Definition Structure

Tools are defined in your extension's entry point:

```typescript
// src/index.ts
import type { ExtensionAITool } from '@nimbalyst/extension-sdk';

export const aiTools: ExtensionAITool[] = [
  {
    name: 'my_tool_name',
    description: 'What this tool does - the agent reads this to decide when to use it',
    inputSchema: {
      type: 'object',
      properties: {
        param1: {
          type: 'string',
          description: 'Description of param1',
        },
        param2: {
          type: 'number',
          description: 'Description of param2',
        },
      },
      required: ['param1'],
    },
    handler: async (args, context) => {
      // Implement tool logic
      return { result: 'success' };
    },
  },
];
```

## Registering Tools in the Manifest

Add tools to your `manifest.json`:

```json
{
  "permissions": {
    "ai": true
  },
  "contributions": {
    "aiTools": [
      "myext.get_data",
      "myext.update_data"
    ]
  }
}
```

## Tool Handler Context

The handler receives a context object with useful information:

```typescript
interface AIToolContext {
  // Path to the current workspace (if any)
  workspacePath?: string;

// Path to the active file (if any)
  activeFilePath?: string;

// Access host services such as filesystem, UI, and AI helpers
  extensionContext: ExtensionContext;

// Imperative API registered by the targeted mounted editor, when available
  editorAPI?: unknown;
}
```

## Example: Spreadsheet Tools

Before implementing a tool, declare how it accesses document state:

```typescript
type ExtensionAIToolAccess =
  | { kind: 'filesystem' }
  | { kind: 'editor-read' }
  | { kind: 'editor-write' };
```

* Use `access: { kind: 'filesystem' }` when the handler can read or write the current file through `context.extensionContext.services.filesystem`. This avoids mounting an editor and reads the latest disk content.
* Use `editor-read` for operations that need a mounted editor API without changing content, such as renderer-backed screenshots or selection inspection.
* Use `editor-write` only when the tool intentionally changes editor state. The host then performs a conflict-aware save after the handler finishes.

Accepting a `filePath` argument does not require editor access. A compiler, analyzer, or converter that works from disk should still declare `filesystem`. The older `readOnly: true` field remains compatible, but new tools should use `access`.

Here's a complete example for a CSV/spreadsheet editor:

```typescript
import type {
  AIToolContext,
  ExtensionAITool,
  ExtensionToolResult,
} from '@nimbalyst/extension-sdk';

async function loadActiveFile(context: AIToolContext): Promise<{
  filePath: string;
  content: string;
} | ExtensionToolResult> {
  if (!context.activeFilePath) {
    return { success: false, error: 'No active file is open.' };
  }

try {
    const content = await context.extensionContext.services.filesystem.readFile(context.activeFilePath);
    return {
      filePath: context.activeFilePath,
      content,
    };
  } catch (error) {
    return {
      success: false,
      error: `Failed to read active file: ${error instanceof Error ? error.message : String(error)}`,
    };
  }
}

// Helper to parse CSV
function parseCSV(content: string): string[][] {
  return content.split('\n').map(row => row.split(','));
}

export const aiTools: ExtensionAITool[] = [
  {
    name: 'csv.get_schema',
    description: 'Get the column names and row count of the current CSV file',
    scope: 'global',
    access: { kind: 'filesystem' },
    inputSchema: {
      type: 'object',
      properties: {},
    },
    handler: async (_args, context) => {
      const loaded = await loadActiveFile(context);
      if ('success' in loaded) {
        return loaded;
      }

const rows = parseCSV(loaded.content);
      const headers = rows[0] || [];

return {
        success: true,
        data: {
          columns: headers,
          rowCount: rows.length - 1,
          filePath: loaded.filePath,
        },
      };
    },
  },

{
    name: 'csv.get_rows',
    description: 'Get rows from the CSV file. Returns data as objects with column names as keys.',
    inputSchema: {
      type: 'object',
      properties: {
        startRow: {
          type: 'number',
          description: 'Starting row index (0-based, excluding header)',
        },
        count: {
          type: 'number',
          description: 'Number of rows to return (default: 10)',
        },
      },
    },
    handler: async (args, context) => {
      const loaded = await loadActiveFile(context);
      if ('success' in loaded) {
        return loaded;
      }

const rows = parseCSV(loaded.content);
      const headers = rows[0] || [];
      const dataRows = rows.slice(1);

const start = typeof args.startRow === 'number' ? args.startRow : 0;
      const count = typeof args.count === 'number' ? args.count : 10;
      const selectedRows = dataRows.slice(start, start + count);

return {
        success: true,
        data: {
          rows: selectedRows.map(row => {
            const obj: Record<string, string> = {};
            headers.forEach((h, i) => {
              obj[h] = row[i] || '';
            });
            return obj;
          }),
          totalRows: dataRows.length,
        },
      };
    },
  },

{
    name: 'csv.add_row',
    description: 'Add a new row to the CSV file',
    inputSchema: {
      type: 'object',
      properties: {
        data: {
          type: 'object',
          description: 'Object with column names as keys and cell values',
        },
      },
      required: ['data'],
    },
    handler: async (args, context) => {
      const loaded = await loadActiveFile(context);
      if ('success' in loaded) {
        return loaded;
      }

const rows = parseCSV(loaded.content);
      const headers = rows[0] || [];

// Build new row from data object
      const values = (args.data as Record<string, string>) || {};
      const newRow = headers.map(h => values[h] || '');
      rows.push(newRow);

const nextContent = rows.map(r => r.join(',')).join('\n');
      await context.extensionContext.services.filesystem.writeFile(
        loaded.filePath,
        nextContent
      );

return {
        success: true,
        message: `Added a row to ${loaded.filePath}.`,
        data: {
          rowIndex: rows.length - 1,
        },
      };
    },
  },
];
```

## Updating File Content

When a tool needs to modify a file, write through the filesystem service:

```typescript
handler: async (args, context) => {
  // ... modify data ...

if (!context.activeFilePath) {
    return { success: false, error: 'No active file is open.' };
  }

await context.extensionContext.services.filesystem.writeFile(
    context.activeFilePath,
    serializedData
  );

return {
    success: true,
    message: 'Row added successfully',
  };
}
```

Nimbalyst will:

1. Persist the updated file content
2. Notify the active editor through file watching
3. Let the editor reload or reconcile its in-memory state

## Tool Naming Conventions

Use a prefix for your tools to avoid conflicts:

```
extensionname.action_name
```

Examples:

* `csv.get_schema`
* `csv.add_row`
* `diagram.add_node`
* `datamodel.get_entities`

## Writing Good Tool Descriptions

The agent uses the description to decide when to use your tool. Be specific:

**Good:**

```typescript
description: 'Get the column names and data types from the current CSV file. Returns an array of column definitions.'
```

**Bad:**

```typescript
description: 'Get schema'  // Too vague
```

## Error Handling

Return errors as objects, not thrown exceptions:

```typescript
handler: async (args, context) => {
  if (!context.activeFilePath) {
    return { success: false, error: 'No active file is open' };
  }

if (!args.columnName) {
    return { success: false, error: 'columnName parameter is required' };
  }

try {
    // ... do work ...
    return { success: true, data: result };
  } catch (e) {
    return {
      success: false,
      error: `Failed to process: ${e instanceof Error ? e.message : String(e)}`,
    };
  }
}
```

## Input Schema

The `inputSchema` follows JSON Schema format:

```typescript
inputSchema: {
  type: 'object',
  properties: {
    // String parameter
    name: {
      type: 'string',
      description: 'The name to use',
    },

// Number parameter
    count: {
      type: 'number',
      description: 'How many items',
    },

// Boolean parameter
    includeHeaders: {
      type: 'boolean',
      description: 'Whether to include header row',
    },

// Enum parameter
    format: {
      type: 'string',
      enum: ['json', 'csv', 'xml'],
      description: 'Output format',
    },

// Array parameter
    columns: {
      type: 'array',
      items: { type: 'string' },
      description: 'List of column names',
    },

// Object parameter
    options: {
      type: 'object',
      properties: {
        sortBy: { type: 'string' },
        ascending: { type: 'boolean' },
      },
    },
  },
  required: ['name'], // Required parameters
}
```

## Best Practices

1. **Keep tools focused** - One tool, one job
2. **Return structured data** - Objects are easier for agents to work with
3. **Include context in responses** - Return relevant metadata
4. **Handle missing files gracefully** - Check if `activeFilePath` exists and read through the filesystem service
5. **Validate inputs** - Check required parameters
6. **Use descriptive names** - `get_column_stats` not `stats`

## Testing Tools

Test your tools by asking an agent to use them:

> "What columns are in this CSV file?"

The agent should invoke your `csv.get_schema` tool and report the results.

## Example: Data Model Tools

For a more complex example, here are tools for a data modeling extension:

```typescript
export const aiTools: ExtensionAITool[] = [
  {
    name: 'datamodel.get_entities',
    description: 'List all entities (tables/models) defined in the data model',
    inputSchema: { type: 'object', properties: {} },
    handler: async (_args, context) => {
      if (!context.activeFilePath) {
        return { success: false, error: 'No active file is open' };
      }

const content = await context.extensionContext.services.filesystem.readFile(
        context.activeFilePath
      );
      const model = parseDataModel(content);

return {
        success: true,
        data: {
          entities: model.entities.map(e => ({
            name: e.name,
            fieldCount: e.fields.length,
          })),
        },
      };
    },
  },

{
    name: 'datamodel.get_entity',
    description: 'Get detailed information about a specific entity',
    inputSchema: {
      type: 'object',
      properties: {
        name: { type: 'string', description: 'Entity name' },
      },
      required: ['name'],
    },
    handler: async (args, context) => {
      if (!context.activeFilePath) {
        return { success: false, error: 'No active file is open' };
      }

const content = await context.extensionContext.services.filesystem.readFile(
        context.activeFilePath
      );
      const model = parseDataModel(content);
      const entity = model.entities.find(e => e.name === args.name);

if (!entity) {
        return { success: false, error: `Entity '${args.name}' not found` };
      }

return {
        success: true,
        data: {
          name: entity.name,
          fields: entity.fields.map(f => ({
            name: f.name,
            type: f.type,
            required: f.required,
          })),
          relations: entity.relations,
        },
      };
    },
  },

{
    name: 'datamodel.add_field',
    description: 'Add a new field to an entity',
    inputSchema: {
      type: 'object',
      properties: {
        entityName: { type: 'string' },
        fieldName: { type: 'string' },
        fieldType: { type: 'string' },
        required: { type: 'boolean' },
      },
      required: ['entityName', 'fieldName', 'fieldType'],
    },
    handler: async (args, context) => {
      if (!context.activeFilePath) {
        return { success: false, error: 'No active file is open' };
      }

if (!entity) {
        return { success: false, error: `Entity '${args.entityName}' not found` };
      }

entity.fields.push({
        name: args.fieldName,
        type: args.fieldType,
        required: args.required ?? false,
      });

await context.extensionContext.services.filesystem.writeFile(
        context.activeFilePath,
        serializeDataModel(model)
      );

return {
        success: true,
        message: `Added ${args.fieldName} to ${args.entityName}.`,
      };
    },
  },
];
```

## Calling AI Models Directly

Extensions can also call configured chat/completion models directly, without creating or driving a coding-agent session. This is useful for summarization, classification, code generation, or any task where the extension itself needs an AI response.

### Prerequisites

Your manifest must declare `permissions.ai: true`.

### Listing Available Models

```typescript
export async function activate(context: ExtensionContext) {
  const models = await context.services.ai!.listModels();
  // => [
  //   { id: "provider:model-id", name: "Model display name", provider: "provider" },
  //   ...
  // ]
}
```

Only models from chat providers the user has enabled and configured are returned (Claude, OpenAI, LM Studio). Agent providers like Claude Code are not included.

### Non-Streaming Completion

```typescript
const result = await context.services.ai!.chatCompletion({
  messages: [
    { role: 'user', content: 'Classify this text as positive or negative: "Great product!"' },
  ],
  model: models[0].id, // optional; use an ID returned by listModels()
  systemPrompt: 'Respond with a single word: positive or negative.',
  temperature: 0,
  maxTokens: 10,
});

console.log(result.content);  // "positive"
console.log(result.model);    // "claude-sonnet-4-6-20250514"
console.log(result.usage);    // { inputTokens: 42, outputTokens: 1 }
```

### Streaming Completion

For longer responses where you want to show results incrementally:

```typescript
const handle = await context.services.ai!.chatCompletionStream({
  messages: [
    { role: 'user', content: 'Write a haiku about programming' },
  ],
  onChunk: (chunk) => {
    if (chunk.type === 'text') {
      // Append text to your UI
      appendToOutput(chunk.content!);
    } else if (chunk.type === 'error') {
      showError(chunk.error!);
    }
    // chunk.type === 'done' means the stream is complete
  },
});

// Optionally abort:
// handle.abort();

// Wait for the full result:
const result = await handle.result;
console.log(result.content); // Full response text
```

### Multi-Turn Conversations

Pass multiple messages for conversation context:

```typescript
const result = await context.services.ai!.chatCompletion({
  messages: [
    { role: 'user', content: 'What is the capital of France?' },
    { role: 'assistant', content: 'The capital of France is Paris.' },
    { role: 'user', content: 'What is its population?' },
  ],
});
```

### Structured Output (JSON Mode)

Use `responseFormat` to constrain the model's output to valid JSON:

```typescript
// Simple JSON mode - model returns valid JSON
const result = await context.services.ai!.chatCompletion({
  messages: [{ role: 'user', content: 'List 3 colors with hex codes' }],
  systemPrompt: 'Respond in JSON format.',
  responseFormat: { type: 'json_object' },
});
const data = JSON.parse(result.content);
```

For stricter control, use `json_schema` to enforce a specific shape:

```typescript
const result = await context.services.ai!.chatCompletion({
  messages: [{ role: 'user', content: 'Classify this issue: login page crashes on Safari' }],
  responseFormat: {
    type: 'json_schema',
    schema: {
      type: 'object',
      properties: {
        category: { type: 'string', enum: ['bug', 'feature', 'question'] },
        severity: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] },
        component: { type: 'string' },
      },
      required: ['category', 'severity', 'component'],
    },
  },
});
const classification = JSON.parse(result.content);
// => { category: "bug", severity: "high", component: "auth" }
```

### Key Points

* **Stateless**: These calls do not create sessions in the session history. Each call is independent.
* **Model selection**: Use `listModels()` to discover available models, then pass an `id` to `chatCompletion()` or `chatCompletionStream()`. If you omit the model, the first available provider's default is used.
* **Chat providers only**: Claude, OpenAI, and LM Studio. Agent providers (Claude Code, Codex) are not available through this API.
* **User configuration**: The API respects the user's provider settings and API keys. If a provider is disabled or unconfigured, its models won't appear in `listModels()`.

## Next Steps

* See [custom-editors.md](/extensions/building-extensions/custom-editors) to build the visual component
* Check [manifest-reference.md](/extensions/building-extensions/manifest-reference) for all configuration options
* Check the built-in extensions in `packages/extensions/` in the Nimbalyst repository for production examples
* See [api-reference.md](/extensions/building-extensions/api-reference) for full type definitions

# Manifest Reference

Full reference for the Nimbalyst extension manifest.json: required fields, permissions, contributions, file pattern syntax, and validation.

The `manifest.json` file declares your extension metadata, permissions, and contributions.

## Basic Structure

```json
{
  "id": "com.example.my-extension",
  "name": "My Extension",
  "version": "1.0.0",
  "main": "dist/index.js",
  "styles": "dist/index.css",
  "apiVersion": "1.0.0",
  "permissions": {},
  "contributions": {}
}
```

## Required Fields

### `id`

Unique identifier for your extension.

```json
"id": "com.yourcompany.extension-name"
```

* Use reverse-domain style identifiers.
* Must start with a letter.
* Can contain letters, numbers, dots, underscores, and hyphens.

### `name`

Human-readable name shown in the UI.

```json
"name": "CSV Spreadsheet Editor"
```

### `version`

Extension version in semver format.

```json
"version": "1.0.0"
```

### `main`

Path to the built JavaScript entry point, relative to the manifest.

```json
"main": "dist/index.js"
```

`main` is required for normal extensions. Claude-plugin-only extensions can omit it if they do not ship runtime code.

## Optional Top-Level Fields

### `description`

Short description of what your extension does.

```json
"description": "Edit CSV files with a spreadsheet interface"
```

### `author`

Author or organization name.

```json
"author": "Nimbalyst"
```

### `styles`

Path to a CSS bundle to load with your extension.

```json
"styles": "dist/index.css"
```

### `apiVersion`

Optional extension API version string.

```json
"apiVersion": "1.0.0"
```

This is currently recommended, not required. Use it so future compatibility checks can warn more precisely.

### `requiredReleaseChannel`

Restrict visibility to a release channel.

```json
"requiredReleaseChannel": "alpha"
```

Allowed values:

* `"stable"`
* `"alpha"`

### `defaultEnabled`

Control whether the extension starts enabled the first time it is discovered.

```json
"defaultEnabled": false
```

If omitted, the extension defaults to enabled.

## Permissions

Declare the capabilities your extension needs:

```json
"permissions": {
  "filesystem": true,
  "ai": true,
  "network": false,
  "catalog": ["nimbalyst-database-read"]
}
```

Available permissions:

| Permission   | Description                                                                                                                                                                                                     |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filesystem` | Read and write files through extension services                                                                                                                                                                 |
| `ai`         | Register AI tools, context providers, and call AI chat/completion models directly (`listModels`, `chatCompletion`, `chatCompletionStream`)                                                                      |
| `network`    | Reserved for network-enabled extensions                                                                                                                                                                         |
| `catalog`    | Permission-catalog capability IDs required by gated host APIs. For example, database reads require `nimbalyst-database-read`. Backend modules declare their own permissions on the module contribution instead. |

## Contributions

The `contributions` object declares what your extension adds to Nimbalyst.

### `customEditors`

```json
"contributions": {
  "customEditors": [
    {
      "filePatterns": ["*.csv", "*.tsv"],
      "displayName": "Spreadsheet Editor",
      "component": "SpreadsheetEditor",
      "supportsSourceMode": true,
      "supportsDiffMode": true,
      "readOnlyDuringDiff": true,
      "supportsTranscriptEmbed": true,
      "transcriptEmbedHeight": 420,
      "showDocumentHeader": true
    }
  ]
}
```

| Field                     | Type       | Description                                                                                                                   |
| ------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `filePatterns`            | `string[]` | Glob patterns for matching files                                                                                              |
| `displayName`             | `string`   | Name shown in the editor selector                                                                                             |
| `component`               | `string`   | Key in your exported `components` object                                                                                      |
| `supportsSourceMode`      | `boolean`  | Enables the host's source-mode toggle                                                                                         |
| `supportsDiffMode`        | `boolean`  | Enables the host's AI diff review mode. Defaults to `false` when omitted                                                      |
| `readOnlyDuringDiff`      | `boolean`  | Tells the host that this editor actually locks manual edits during diff review. Defaults to `false`                           |
| `supportsTranscriptEmbed` | `boolean`  | Allows a read-only, click-to-activate editor embed in agent transcripts. Defaults to `false`                                  |
| `transcriptEmbedHeight`   | `number`   | Preferred transcript embed height in pixels. Defaults to `360`                                                                |
| `showDocumentHeader`      | `boolean`  | Shows the host-provided document header above the editor. Defaults to `true` when omitted                                     |
| `collaboration`           | `object`   | Declares shared-document support and optional awareness fields. Editors that opt in must implement the collaborative binding. |

### `documentHeaders`

Render UI above matching editors without replacing the editor itself.

```json
"documentHeaders": [
  {
    "id": "astro-frontmatter",
    "filePatterns": ["*.astro"],
    "displayName": "Astro Frontmatter",
    "component": "AstroFrontmatterHeader",
    "priority": 100
  }
]
```

### `aiTools`

Declare AI tools your extension provides. This is an array of tool name strings, not full tool definitions.

```json
"aiTools": [
  "csv.get_schema",
  "csv.query"
]
```

The actual tool definitions belong in your TypeScript exports:

```ts
export const aiTools: ExtensionAITool[] = [
  {
    name: 'csv.get_schema',
    description: 'Get the column names from the active CSV file',
    inputSchema: { type: 'object', properties: {} },
    handler: async (_args, context) => {
      return { success: true, data: {} };
    },
  },
];
```

### `newFileMenu`

Add items to the "New File" menu.

```json
"newFileMenu": [
  {
    "extension": ".csv",
    "displayName": "CSV Spreadsheet",
    "icon": "table",
    "defaultContent": "Column A,Column B\n,\n,"
  }
]
```

### `fileIcons`

Override file icons in the sidebar.

```json
"fileIcons": {
  "*.csv": "table",
  "*.tsv": "table",
  "*.json": "data_object"
}
```

Keys are glob patterns. Values are Material icon names.

### `slashCommands`

```json
"slashCommands": [
  {
    "id": "csv.insert-table",
    "title": "Insert CSV Table",
    "description": "Insert a table from CSV data",
    "icon": "table",
    "keywords": ["csv", "table"],
    "handler": "insertCsvTable"
  }
]
```

| Field         | Type       | Description                           |
| ------------- | ---------- | ------------------------------------- |
| `id`          | `string`   | Stable command identifier             |
| `title`       | `string`   | Label shown in the picker             |
| `description` | `string`   | Optional help text                    |
| `icon`        | `string`   | Optional Material icon name           |
| `keywords`    | `string[]` | Optional search keywords              |
| `handler`     | `string`   | Name of the exported handler function |

### `commands` and `keybindings`

Declare named actions in `commands`, then bind keys separately in `keybindings`. Panel toggle commands are registered automatically as `<extensionId>.<panelId>.toggle`, so a panel shortcut does not need a matching `commands` entry.

```json
"commands": [
  {
    "id": "csv.refresh",
    "title": "Refresh CSV Data"
  }
],
"keybindings": [
  {
    "key": "cmd+shift+r",
    "command": "csv.refresh"
  }
]
```

### `configuration`

Declare user/workspace settings for your extension.

```json
"configuration": {
  "title": "CSV Tools",
  "properties": {
    "delimiter": {
      "type": "string",
      "default": ",",
      "description": "Default delimiter for new CSV files",
      "scope": "workspace"
    }
  }
}
```

### `claudePlugin`

Bundle a Claude Code plugin with the extension.

```json
"claudePlugin": {
  "path": "claude-plugin",
  "displayName": "CSV Assistant",
  "description": "Adds Claude Code helpers for CSV workflows",
  "enabledByDefault": true
}
```

### `panels`

```json
"panels": [
  {
    "id": "database-browser",
    "title": "Database",
    "icon": "database",
    "placement": "sidebar",
    "aiSupported": true
  }
]
```

`placement` must be one of:

* `"sidebar"`
* `"fullscreen"`
* `"floating"`
* `"bottom"`

### `settingsPanel`

Add a nested settings UI inside the extension's installed-extension detail.

```json
"settingsPanel": {
  "component": "CsvSettingsPanel",
  "title": "CSV Tools",
  "icon": "settings",
  "order": 100
}
```

### `settingsRoutes`

Add a first-class page to the Application or Project Settings sidebar:

```json
"settingsRoutes": [
  {
    "id": "memory",
    "scope": "project",
    "label": "Memory",
    "group": "Project",
    "icon": "psychology",
    "order": 80,
    "component": "MemorySettings"
  }
]
```

| Field       | Type                         | Description                                                                          |
| ----------- | ---------------------------- | ------------------------------------------------------------------------------------ |
| `id`        | `string`                     | Unique route ID inside this extension. The host namespaces it to prevent collisions. |
| `scope`     | `"application" \| "project"` | Settings scope where the page appears. Account routes are reserved for Nimbalyst.    |
| `label`     | `string`                     | User-facing sidebar label.                                                           |
| `group`     | `string`                     | Optional sidebar group. Defaults to `Extensions`.                                    |
| `icon`      | `string`                     | Optional Material Symbol name. Defaults to `extension`.                              |
| `order`     | `number`                     | Optional sort order within the extension group. Defaults to `100`.                   |
| `component` | `string`                     | Component name exported from the module's `settingsPanel` record.                    |

Project routes receive the active repository through `SettingsPanelProps.workspacePath` and the complete target through `projectTarget`. Application routes omit project context.

Use `settingsRoutes` when the extension owns a settings destination users should navigate to directly. Use `settingsPanel` for configuration that belongs inside the installed-extension detail.

### `themes`

```json
"themes": [
  {
    "id": "solarized-light",
    "name": "Solarized Light",
    "isDark": false,
    "colors": {
      "bg": "#fdf6e3",
      "text": "#657b83",
      "primary": "#268bd2"
    }
  }
]
```

### `nodes`, `transformers`, and `hostComponents`

These contribution arrays declare names of exports provided by your module.

```json
"nodes": ["MyLexicalNode"],
"transformers": ["myMarkdownTransformer"],
"hostComponents": ["MyFloatingToolbar"]
```

`lexicalExtensions` is the supported contribution for Lexical features built with `defineExtension` from `@lexical/extension`. The strings in the manifest name entries in the module's exported `lexicalExtensions` record.

### Advanced contributions

The SDK also defines contribution types for provider-neutral `agentWorkflows`, isolated `backendModules`, `trackerImporters`, and `aiAgentProviders`.

Backend modules run in a utility process or worker thread and remain disabled until the user grants them at first use. Their declaration names the built entry file, runtime, granular permission IDs, and a short purpose shown in the consent prompt. Renderer-side gated APIs instead use the top-level `permissions.catalog` array.

Tracker importers and AI agent providers reference a backend module because their privileged work cannot run in the renderer. These surfaces have additional permission, validation, and lifecycle requirements; use the TypeScript declarations from your installed `@nimbalyst/extension-sdk` and the current built-in extensions as the canonical reference.

## Complete Example

```json
{
  "id": "com.nimbalyst.csv-tools",
  "name": "CSV Tools",
  "version": "1.0.0",
  "description": "Custom CSV editing and AI helpers",
  "author": "Nimbalyst",
  "main": "dist/index.js",
  "styles": "dist/index.css",
  "apiVersion": "1.0.0",
  "defaultEnabled": true,
  "permissions": {
    "filesystem": true,
    "ai": true
  },
  "contributions": {
    "customEditors": [
      {
        "filePatterns": ["*.csv", "*.tsv"],
        "displayName": "Spreadsheet Editor",
        "component": "SpreadsheetEditor",
        "supportsSourceMode": true
      }
    ],
    "aiTools": [
      "csv.get_schema",
      "csv.query"
    ],
    "fileIcons": {
      "*.csv": "table",
      "*.tsv": "table"
    },
    "slashCommands": [
      {
        "id": "csv.insert-table",
        "title": "Insert CSV Table",
        "handler": "insertCsvTable"
      }
    ],
    "configuration": {
      "properties": {
        "delimiter": {
          "type": "string",
          "default": ","
        }
      }
    },
    "settingsRoutes": [
      {
        "id": "csv",
        "scope": "project",
        "label": "CSV Tools",
        "component": "CsvSettingsPanel"
      }
    ]
  }
}
```

## File Pattern Syntax

File patterns use glob syntax:

| Pattern        | Matches                          |
| -------------- | -------------------------------- |
| `*.csv`        | Any file ending in `.csv`        |
| `*.{csv,tsv}`  | Files ending in `.csv` or `.tsv` |
| `data/*.json`  | JSON files in `data/`            |
| `**/*.test.ts` | Test files anywhere in the tree  |

## Validation Notes

Nimbalyst validates your manifest on load. Common errors:

* Missing required top-level fields: `id`, `name`, `version`, or `main`
* `aiTools` contains objects instead of tool-name strings
* `slashCommands` uses old `name` / `displayName` fields instead of `id` / `title`
* `fileIcons` is declared as an array instead of an object map
* Contribution component names do not match your exported module names

## Best Practices

1. Use a stable reverse-domain `id`.
2. Request only the permissions you actually need.
3. Keep `contributions.aiTools` and your exported `aiTools` array in sync.
4. Prefer adding `apiVersion` even though it is currently optional.
5. Validate on every build with `validateExtensionBundle()`.

# API Reference

TypeScript API reference for @nimbalyst/extension-sdk, covering ExtensionContext, custom editors, AI tools, panels, storage, and manifest types.

This document summarizes the main TypeScript exports from `@nimbalyst/extension-sdk`.

## Main Imports

```ts
import type {
  ExtensionContext,
  ExtensionManifest,
  ExtensionModule,
  EditorHostProps,
  ExtensionAITool,
  AIToolContext,
  ExtensionToolResult,
  PanelHostProps,
  SettingsPanelProps,
  SettingsRouteContribution,
  SettingsRouteProjectTarget,
  ResolvedTrackerReference,
} from '@nimbalyst/extension-sdk';

import {
  REQUIRED_EXTERNALS,
  TrackerReferenceChip,
  TrackerReferencePicker,
  navigateToTrackerReference,
  useEditorLifecycle,
  useResolvedTrackerReference,
  validateExtensionBundle,
} from '@nimbalyst/extension-sdk';
import { createExtensionConfig } from '@nimbalyst/extension-sdk/vite';
```

## Extension Entry Point

Your extension module can export any subset of these fields:

```ts
interface ExtensionModule {
  activate?: (context: ExtensionContext) => void | Promise<void>;
  deactivate?: () => void | Promise<void>;

components?: Record<string, React.ComponentType<EditorHostProps>>;
  aiTools?: ExtensionAITool[];
  slashCommandHandlers?: Record<string, () => void>;

nodes?: Record<string, unknown>;
  transformers?: Record<string, unknown>;
  lexicalExtensions?: Record<string, unknown>;
  hostComponents?: Record<string, React.ComponentType>;

panels?: Record<string, PanelExport>;
  settingsPanel?: Record<string, React.ComponentType<SettingsPanelProps>>;
}
```

## `ExtensionContext`

Passed to `activate()` and available inside `AIToolContext.extensionContext`.

```ts
interface ExtensionContext {
  manifest: ExtensionManifest;
  extensionPath: string;
  services: ExtensionServices;
  subscriptions: Disposable[];
}
```

### `ExtensionServices`

```ts
interface ExtensionServices {
  filesystem: ExtensionFileSystemService;
  ui: ExtensionUIService;
  ai?: ExtensionAIService;
  configuration?: ExtensionConfigurationService;
}
```

```ts
interface ExtensionFileSystemService {
  readFile(path: string): Promise<string>;
  writeFile(path: string, content: string | Uint8Array): Promise<void>;
  fileExists(path: string): Promise<boolean>;
  findFiles(pattern: string): Promise<string[]>;
}

interface ExtensionUIService {
  showInfo(message: string): void;
  showWarning(message: string): void;
  showError(message: string): void;
}

interface ExtensionConfigurationService {
  get<T>(key: string, defaultValue?: T): T;
  update(key: string, value: unknown, scope?: 'user' | 'workspace'): Promise<void>;
  getAll(): Record<string, unknown>;
}
```

### `ExtensionAIService`

Available when `permissions.ai` is `true`. Provides AI tool registration and direct access to chat/completion models.

```ts
interface ExtensionAIService {
  // Register AI tools that Claude can call
  registerTool(tool: ExtensionAITool): Disposable;
  registerContextProvider(provider: ExtensionContextProvider): Disposable;

// Session-backed prompt (creates a session in history)
  sendPrompt(options: {
    prompt: string;
    sessionName?: string;
    provider?: 'claude-code' | 'claude' | 'openai';
    model?: string;
  }): Promise<{ sessionId: string; response: string }>;

// List available chat models (Claude, OpenAI, LM Studio)
  listModels(): Promise<ExtensionAIModel[]>;

// Stateless chat completion (no session created)
  chatCompletion(options: ChatCompletionOptions): Promise<ChatCompletionResult>;

// Streaming chat completion (no session created)
  chatCompletionStream(options: ChatCompletionStreamOptions): Promise<ChatCompletionStreamHandle>;
}
```

### Chat Completion Types

```ts
interface ExtensionAIModel {
  id: string;        // e.g. "claude:claude-sonnet-4-6-20250514"
  name: string;      // e.g. "Claude Sonnet 4.6"
  provider: string;  // "claude" | "openai" | "lmstudio"
}

interface ChatCompletionMessage {
  role: 'user' | 'assistant' | 'system';
  content: string;
}

interface ChatCompletionOptions {
  messages: ChatCompletionMessage[];
  model?: string;           // Model ID from listModels(). Provider default if omitted.
  maxTokens?: number;
  temperature?: number;     // 0-1
  systemPrompt?: string;    // Prepended as system message
  responseFormat?: ResponseFormat; // Constrain output format (JSON, JSON schema)
}

type ResponseFormat =
  | { type: 'text' }                                          // Default: plain text
  | { type: 'json_object' }                                   // Valid JSON output
  | { type: 'json_schema';                                    // JSON matching a schema
      schema: JSONSchema;
      name?: string;     // Optional schema name (default: 'response')
      strict?: boolean;  // default: true for OpenAI
    };

interface ChatCompletionResult {
  content: string;          // Assistant response
  model: string;            // Model that was used
  usage?: {
    inputTokens: number;
    outputTokens: number;
  };
}

interface ChatCompletionStreamChunk {
  type: 'text' | 'error' | 'done';
  content?: string;         // Text delta (when type is 'text')
  error?: string;           // Error message (when type is 'error')
}

interface ChatCompletionStreamOptions extends ChatCompletionOptions {
  onChunk: (chunk: ChatCompletionStreamChunk) => void;
}

interface ChatCompletionStreamHandle {
  abort(): void;                        // Cancel the stream
  result: Promise<ChatCompletionResult>; // Resolves on completion
}
```

## Custom Editors

Custom editors receive a single `host` prop. Use the `useEditorLifecycle` hook (from `@nimbalyst/extension-sdk`) to handle all lifecycle concerns.

### useEditorLifecycle Hook

```ts
import { useEditorLifecycle } from '@nimbalyst/extension-sdk';

function useEditorLifecycle<T = string>(
  host: EditorHost,
  options: UseEditorLifecycleOptions<T>
): UseEditorLifecycleResult<T>;
```

```ts
interface UseEditorLifecycleOptions<T> {
  applyContent: (content: T) => void;       // Push content into the editor
  getCurrentContent?: () => T;               // Pull content from the editor (omit for read-only)
  parse?: (raw: string) => T;                // Parse raw file string into editor format
  serialize?: (content: T) => string;        // Serialize editor format to string
  binary?: boolean;                          // Use loadBinaryContent() for binary files
  onLoaded?: () => void;                     // Called after initial load
  onExternalChange?: (content: T) => void;   // Called on external file changes (not echoes)
  onSave?: () => Promise<void>;              // Custom save flow (replaces default)
  onDiffRequested?: (config: DiffConfig) => void;  // Custom diff handling
  onDiffCleared?: () => Promise<void>;       // Custom diff cleanup
}

interface UseEditorLifecycleResult<T> {
  isLoading: boolean;                        // True until initial content loads
  error: Error | null;                       // Load error
  theme: string;                             // Current theme (reactive)
  markDirty: () => void;                     // Call on user edit
  isDirty: boolean;                          // Unsaved changes exist
  diffState: DiffState<T> | null;            // AI edit diff (null when inactive)
  toggleSourceMode: (() => void) | undefined;
  isSourceMode: boolean;
}

interface DiffState<T> {
  original: T;                               // Content before AI edit
  modified: T;                               // Content after AI edit
  tagId: string;                             // History tag ID
  sessionId: string;                         // AI session that made the edit
  accept: () => void;                        // Accept changes
  reject: () => void;                        // Revert to original
}
```

### EditorHost Interface

The `useEditorLifecycle` hook wraps this interface. You rarely need to use it directly.

```ts
interface EditorHostProps {
  host: EditorHost;
}
```

```ts
interface EditorHost {
  readonly filePath: string;
  readonly fileName: string;
  readonly theme: string;
  readonly isActive: boolean;
  readonly workspaceId?: string;
  readonly supportsSourceMode?: boolean;
  readonly storage: ExtensionStorage;
  readonly fs?: EditorHostFileSystem;

onThemeChanged(callback: (theme: string) => void): () => void;

loadContent(): Promise<string>;
  loadBinaryContent(): Promise<ArrayBuffer>;
  onFileChanged(callback: (newContent: string) => void): () => void;

setDirty(isDirty: boolean): void;
  saveContent(content: string | ArrayBuffer): Promise<void>;
  onSaveRequested(callback: () => void): () => void;

openHistory(): void;
  openExternal?(url: string): Promise<void>;

onDiffRequested?(callback: (config: DiffConfig) => void): () => void;
  reportDiffResult?(result: DiffResult): void;
  isDiffModeActive?(): boolean;
  onDiffCleared?(callback: () => void): () => void;

toggleSourceMode?(): void;
  onSourceModeChanged?(callback: (isSourceMode: boolean) => void): () => void;
  isSourceModeActive?(): boolean;

getConfig?<T>(key: string, defaultValue?: T): T;
  registerMenuItems(items: EditorMenuItem[]): void;
}
```

Supporting editor types:

```ts
interface EditorMenuItem {
  label: string;
  icon?: string;
  onClick: () => void;
}

interface DiffConfig {
  originalContent: string;
  modifiedContent: string;
  tagId: string;
  sessionId: string;
}

interface DiffResult {
  content: string;
  action: 'accept' | 'reject';
}
```

### Project Filesystem

`EditorHost.fs` provides workspace-bounded, versioned access to additional project files:

```ts
interface ProjectFileSnapshot {
  path: string;
  exists: boolean;
  content: string | null;
  sha256: string | null;
}

interface ProjectFileChange {
  path: string;
  expectedSha256: string | null;
  content: string | null;
}

interface ProjectFileEdit {
  label: string;
  actor: 'user' | 'agent';
  changes: ProjectFileChange[];
}

interface ProjectFileWriteReceipt {
  id: string;
  label: string;
  actor: 'user' | 'agent';
  timestamp: number;
  files: Array<{
    path: string;
    beforeSha256: string | null;
    afterSha256: string | null;
  }>;
  atomic: false;
}

interface EditorHostFileSystem {
  read(paths: string[]): Promise<ProjectFileSnapshot[]>;
  write(edit: ProjectFileEdit): Promise<ProjectFileWriteReceipt>;
  onChanged(callback: (paths: string[]) => void): () => void;
}
```

The service is optional and is unavailable for hosts without local project-file semantics. Writes use the SHA-256 returned by `read()` to prevent stale overwrites.

## Tracker References

The SDK exports host-owned Tracker UI so extensions can store portable issue keys while Nimbalyst owns search, live resolution, display, and navigation.

```tsx
import {
  TrackerReferenceChip,
  TrackerReferencePicker,
  useResolvedTrackerReference,
  navigateToTrackerReference,
} from '@nimbalyst/extension-sdk';

```ts
interface ResolvedTrackerReference {
  id: string;
  issueKey?: string;
  title: string;
  status?: string;
  type?: string;
  priority?: string;
  owner?: string;
  updatedAt?: string;
}
```

* `TrackerReferencePicker` provides the canonical typed search and selection UI.
* `TrackerReferenceChip` renders a live reference in default or compact form.
* `useResolvedTrackerReference(referenceKey)` resolves a stored key reactively.
* `navigateToTrackerReference(reference)` opens the item in Nimbalyst.

Persist the issue key or reference key, not a copied title or workflow state. The host resolves mutable fields when it renders the reference.

## AI Tools

```ts
interface ExtensionAITool {
  name: string;
  description: string;
  inputSchema?: JSONSchema;
  parameters?: JSONSchema; // legacy alias
  scope?: 'global' | 'editor';
  editorFilePatterns?: string[];
  handler: (
    params: Record<string, unknown>,
    context: AIToolContext
  ) => Promise<ExtensionToolResult>;
}
```

```ts
interface AIToolContext {
  workspacePath?: string;
  activeFilePath?: string;
  extensionContext: ExtensionContext;
}
```

```ts
interface ExtensionToolResult {
  success: boolean;
  message?: string;
  data?: unknown;
  error?: string;
  extensionId?: string;
  toolName?: string;
  stack?: string;
  errorContext?: Record<string, unknown>;
}
```

### JSON Schema Types

```ts
interface JSONSchema {
  type: 'object' | 'array' | 'string' | 'number' | 'boolean' | 'null';
  properties?: Record<string, JSONSchemaProperty>;
  required?: string[];
  items?: JSONSchema;
  description?: string;
}

interface JSONSchemaProperty {
  type: 'string' | 'number' | 'boolean' | 'array' | 'object' | 'null';
  description?: string;
  enum?: Array<string | number>;
  items?: JSONSchemaProperty;
  properties?: Record<string, JSONSchemaProperty>;
  required?: string[];
  default?: unknown;
}
```

## Panels

Panels are non-file-based extension UIs.

```ts
interface PanelExport {
  component: React.ComponentType<PanelHostProps>;
  gutterButton?: React.ComponentType<PanelGutterButtonProps>;
  settingsComponent?: React.ComponentType<PanelHostProps>;
}
```

```ts
interface PanelHostProps {
  host: PanelHost;
}

interface PanelHost {
  readonly panelId: string;
  readonly extensionId: string;
  readonly theme: string;
  readonly workspacePath: string;
  readonly isSettingsOpen: boolean;
  readonly ai?: PanelAIContext;
  readonly storage: ExtensionStorage;

onThemeChanged(callback: (theme: string) => void): () => void;
  openFile(path: string): void;
  openPanel(panelId: string): void;
  close(): void;
  openSettings(): void;
  closeSettings(): void;
}
```

```ts
interface PanelAIContext {
  setContext(context: Record<string, unknown>): void;
  getContext(): Record<string, unknown>;
  clearContext(): void;
  notifyChange(event: string, data?: unknown): void;
  onContextChanged(callback: (context: Record<string, unknown>) => void): () => void;
}
```

```ts
interface SettingsPanelProps {
  storage: ExtensionStorage;
  theme: string;
  callBackendTool?: (
    toolName: string,
    args?: Record<string, unknown>
  ) => Promise<unknown>;
  workspacePath?: string;
  projectTarget?: SettingsRouteProjectTarget;
}
```

`workspacePath` and `projectTarget` are provided only for first-class project settings routes. Application routes and legacy nested settings panels do not receive project context.

```ts
type SettingsRouteProjectTarget =
  | { kind: 'workspace'; workspacePath: string }
  | { kind: 'organizationProject'; orgId: string; projectId: string };

interface SettingsRouteContribution {
  id: string;
  scope: 'application' | 'project';
  label: string;
  group?: string;
  icon?: string;
  order?: number;
  component: string;
}
```

## Extension Storage

`ExtensionStorage` is available to custom editors, panels, and settings panels.

```ts
interface ExtensionStorage {
  get<T>(key: string): T | undefined;
  set<T>(key: string, value: T): Promise<void>;
  delete(key: string): Promise<void>;

getGlobal<T>(key: string): T | undefined;
  setGlobal<T>(key: string, value: T): Promise<void>;
  deleteGlobal(key: string): Promise<void>;

getSecret(key: string): Promise<string | undefined>;
  setSecret(key: string, value: string): Promise<void>;
  deleteSecret(key: string): Promise<void>;
}
```

## Manifest Types

The manifest shape is defined by `ExtensionManifest` and `ExtensionContributions`. See [Manifest Reference](/extensions/building-extensions/manifest-reference) for field-by-field guidance.

```ts
interface ExtensionManifest {
  id: string;
  name: string;
  version: string;
  description?: string;
  author?: string;
  main: string;
  styles?: string;
  apiVersion?: string;
  permissions?: ExtensionPermissions;
  contributions?: ExtensionContributions;
  requiredReleaseChannel?: 'stable' | 'alpha';
  defaultEnabled?: boolean;
}
```

```ts
interface ExtensionContributions {
  customEditors?: CustomEditorContribution[];
  fileIcons?: Record<string, string>;
  aiTools?: string[];
  newFileMenu?: NewFileMenuContribution[];
  commands?: CommandContribution[];
  keybindings?: KeybindingContribution[];
  slashCommands?: SlashCommandContribution[];
  nodes?: string[];
  transformers?: string[];
  lexicalExtensions?: string[];
  hostComponents?: string[];
  configuration?: ExtensionConfigurationContribution;
  claudePlugin?: ClaudePluginContribution;
  panels?: PanelContribution[];
  settingsPanel?: SettingsPanelContribution;
  settingsRoutes?: SettingsRouteContribution[];
  documentHeaders?: DocumentHeaderContribution[];
  themes?: ThemeContribution[];
  agentWorkflows?: AgentWorkflowsContribution;
  backendModules?: BackendModuleContribution[];
  trackerImporters?: TrackerImporterContribution[];
  aiAgentProviders?: AiAgentProviderContribution[];
}
```

The interfaces above are a working map of the common surface, not a substitute for your installed SDK's declarations. Advanced provider, backend-module, collaboration, and tracker-importer APIs evolve with the host; import their types from the package rather than copying these abbreviated declarations into an extension.

## Vite Helper

Use `createExtensionConfig()` to get the correct externalization and output shape for extensions.

```ts
import react from '@vitejs/plugin-react';
import { createExtensionConfig } from '@nimbalyst/extension-sdk/vite';

export default createExtensionConfig({
  entry: './src/index.tsx',
  plugins: [react()],
});
```

## Validation Helpers

```ts
import { validateExtensionBundle } from '@nimbalyst/extension-sdk';

const result = await validateExtensionBundle('/path/to/extension');
```

```ts
interface ValidationResult {
  valid: boolean;
  errors: string[];
  warnings: string[];
  manifest?: ExtensionManifest;
}
```

## Required Externals

`REQUIRED_EXTERNALS` exports the package names that must stay external in your build because Nimbalyst provides them at runtime.

# Mobile App

Run your desktop coding agents from your phone with Nimbalyst Mobile. Start and resume sessions, answer approvals, and edit synced markdown on the go.

Nimbalyst Mobile is an iOS app that runs your desktop coding agents from your phone. Use it when you are away from your desk and want to start new sessions, resume or redirect running ones, answer an agent that is waiting for approval, and edit synced markdown files (in alpha for now).

### Why Mobile?

When you run multiple parallel sessions, agents often finish or hit a blocker while you are at lunch, commuting, or in a meeting. Nimbalyst Mobile keeps you connected so you can start new work, answer a waiting agent, or just keep an eye on things from wherever you are.

See [mobile agent management](https://nimbalyst.com/mobile-agent-management/) for what the phone app covers.

### How It Works

The mobile app links securely to the desktop app running Nimbalyst. You select which projects to sync, then run sessions, edit files, and manage your agents from the phone while the work itself executes on your desktop machine.

iPhone and iPad share one adaptive layout. Rotating the device preserves the active session and any draft you are composing, and wide screens add a session sidebar so you can switch sessions without leaving the one you are reading.

### Setup

1. On desktop, sign in to Nimbalyst and select which projects you want synced.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2FxU9xZLC0iO1g9jlV6nS6%2Fimage.png?alt=media&token=37ab0da4-c59d-4787-becb-4671c18a1f31" alt="The desktop sync settings panel with the signed-in account, the Projects to Sync list, and the Pair Device button"><figcaption><p>On desktop: the signed-in account, the Projects to Sync list, and the Pair Device button.</p></figcaption></figure>

2. Download the Nimbalyst mobile app from the **iOS App Store**.
3. Sign in with Google or use your email address and the magic link Nimbalyst sends you.
4. On desktop, click the **Pair Device** icon.
5. In the mobile app, scan the QR code and authenticate with the same credentials.

**If QR scanning doesn't work** (camera issues, bright sunlight): use the "Copy to Clipboard" option on desktop and paste the pairing data manually into the mobile app's text field.

### Use Multiple Accounts

You can sign in with more than one Nimbalyst account on iOS and switch between them from the account menu.

Each account keeps its own organizations, project access, paired-device state, and personal sync profile. If some content is not visible, switch to the account that owns the project or received the team invitation.

On desktop, manage accounts under **Settings > Account > Accounts** and choose mobile projects under **Settings > Account > Mobile App**.

***

### What Syncs to Mobile

**Sessions:** Full conversation history, session metadata (title, provider, model), status, and draft inputs you're composing.

**Project Files:** Markdown files (`.md`) from projects with **Docs** enabled sync to mobile. You can read and edit them, so documentation, plans, and notes stay updatable from your phone, and edits sync back to desktop. Document sync is currently available on the Alpha update channel: select **Alpha (Developer Releases)** under **Settings > Application > Advanced**, then enable **Docs** for the project under **Settings > Account > Mobile App**.

**What doesn't sync:** Code files, images, Excalidraw diagrams, mockups, data models, PDFs, CSVs, app settings, and extension data. These remain on desktop only.

***

### Start New Sessions

You don't need to be at your desk to kick off work. Start a brand new AI session from your phone: pick a project, type a prompt, and the session runs on your desktop machine.

### Choosing a Model

Pick which agent and model run your work right from your phone. The model you select becomes the default for new sessions you start on mobile.

1. Open a project and stay on its **Sessions** list.
2. Tap the **+** button in the top right to open the new session menu.
3. Tap the **Model** row at the bottom of the menu. It shows the current agent and model selection.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2Fgit-blob-f563c4aa20f97e33fd93592788750ec471483345%2Fmobile-model-menu.png?alt=media" alt="Mobile new session menu showing the Model row at the bottom"><figcaption><p>The new session menu, with the Model row showing the current agent and model.</p></figcaption></figure>

4. In the **Select Model** sheet, tap the model you want. A checkmark marks the active choice.

Models are grouped under **Agents**:

* **Claude Agent (Claude Code)**
* **OpenAI Codex**

The list reflects the providers and models you have set up on your desktop, so what you see may differ.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2Fgit-blob-adc0b74306c8f06815a2696c8d2daf9ebe57bc81%2Fmobile-select-model.png?alt=media" alt="Select Model sheet listing Claude Agent and OpenAI Codex models with the active one checked"><figcaption><p>The Select Model sheet, with Claude Agent and Codex models grouped under Agents and the active model checked.</p></figcaption></figure>

Each session in your list also shows its own model badge, so you can tell at a glance which agent is running each one.

### Session Dashboard

See all your active, completed, and paused sessions at a glance, with color-coded status, sorted by activity. One tap opens the details.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2Fgit-blob-7fc63cb88e5781fa2620988f6659c03cb0a8fa7d%2Fmobile-session-dashboard.png?alt=media" alt="Mobile session list filtered by All, Active, Planning, and Done"><figcaption><p>The session list with All, Active, Planning, and Done filters; each session shows its model and phase.</p></figcaption></figure>

### Answer Questions and Approvals

When a session is waiting for input, open it to answer the question or respond to its approval request. This includes tool permissions, plan approval, and commit proposals surfaced in the transcript. Code diff review remains a desktop workflow.

### Resume

Session stalled? Resume it with a voice note or typed instruction right from your phone. Redirect the agent or continue the conversation just like you would on desktop.

* **Queue a prompt:** If the session is busy, your prompt queues and runs when the current task finishes. You can queue multiple prompts while offline.
* **Attach images:** Take a photo or choose from your camera roll. Useful for screenshots of bugs, whiteboard sketches, or design references.
* **Draft sync:** Start typing a message on mobile, switch to desktop, and your draft is there waiting.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2Fgit-blob-b2447624f79d08322a14e4999fc637138acc625d%2Fmobile-resume-reassign.png?alt=media" alt="Mobile session view with the agent's result above and the composer below"><figcaption><p>The composer below a finished response, ready to send a follow-up instruction.</p></figcaption></figure>

### Voice on Mobile

Drive your desktop sessions by voice from your phone. Ask the voice agent to start a new session, find a session by topic, switch between sessions, summarize one (including any question it is waiting on), answer a pending question, or send a new coding task to your desktop.

There is no permanent mic button. Start voice from the **•••** menu inside a session (**Start Voice Mode**), or from the **+** menu on a project's **Sessions** tab (**Start Voice Agent**). The floating mic appears once it connects, with **Pause** and **Cancel** so you stay in control.

Voice runs in the iOS app and is in alpha. See [Voice on Mobile](/mobile/voice-on-mobile) for setup, controls, and troubleshooting, or [Voice Mode](/setup-nimbalyst/voice-mode) for the desktop side.

### Lock Screen Live Activity

On iPhone, your session fleet also reaches the Lock Screen and Dynamic Island as a Live Activity. Sessions are ranked by how long each one has been waiting on you, so the agent that has been blocked the longest is the first thing you see. Tap a session to open it in the app.

### Push Notifications

Get notified when sessions complete, hit errors, or need your approval. Your agents tell you when they need you, so you can stop checking.

**Smart routing:** Notifications only go to your phone when you're away from your desktop. If Nimbalyst is active on your Mac, your phone stays silent.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2Fgit-blob-87523ae87fb02524e740db8eda190c3ee3eedcfb%2Fmobile-push-notifications.png?alt=media" alt="A Session Complete push notification from Nimbalyst"><figcaption><p>A Session Complete notification summarizing what the agent finished.</p></figcaption></figure>

### Desktop Sync

Sessions, prompts, supported approvals, and enabled markdown documents sync with your desktop Nimbalyst workspace. Prompts you queue from your phone run on your desktop machine, and markdown edits sync back to the corresponding project file.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2Fgit-blob-e31f97ee2106b33f9d89f8deccc6bdb158c1b93c%2Fmobile-desktop-sync.png?alt=media" alt="Mobile Settings screen showing the sync connection status as Connected"><figcaption><p>The mobile Settings screen showing the sync connection status.</p></figcaption></figure>

### Sleep Prevention / Keep Awake

A common issue with mobile sync is your desktop going to sleep, which breaks the connection. In Nimbalyst Settings, you can enable **sleep prevention** to keep your desktop awake while syncing. Choose between:

* **Off**: default, no sleep prevention
* **Always**: keeps your desktop awake whenever Nimbalyst is running
* **When plugged in**: only prevents sleep when your computer is connected to power

### Clickable Links in Transcripts

Links in session transcripts on iOS are tappable, so you can open URLs directly from your mobile session view.

### Encryption and Privacy

All data synced between your devices is end-to-end encrypted:

* **Encryption:** AES-256-GCM per message, each with its own initialization vector
* **Key exchange:** Via QR code during setup; keys never touch our servers
* **Server access:** Our sync servers store and relay encrypted data. They cannot read your content.

Your encryption key is derived from the seed shared during QR pairing using PBKDF2 with 100,000 iterations.

### Offline Behavior

* **Reading:** Previously synced sessions and files are cached locally and readable without connectivity
* **Writing:** Compose and queue prompts while offline; they transmit automatically when you're back online
* **Limitations:** No push notifications or real-time updates while offline. New desktop sessions won't appear until you reconnect.

When you come back online, the app syncs incrementally, fetching only messages newer than what you already have.

### Troubleshooting

**Sessions not appearing on mobile**

* Verify the project is enabled under **Settings > Account > Mobile App** on desktop.
* Confirm that the same account is active on the desktop and phone.
* Check that mobile sync is enabled for that account.
* Ensure both devices are online.

**Push notifications not working**

* Check that notifications are enabled in your phone's system settings for Nimbalyst.
* Notifications are suppressed when Nimbalyst is active on desktop. This is intentional.

**Sync feels slow**

* Large sessions with many messages take longer on first sync.
* After initial sync, updates are incremental and near-instant.
* Check your network connection on both devices.

### Works With Claude Agent and Codex

Manage Claude Agent and OpenAI Codex sessions from one app. Other direct chat providers can also appear in the mobile model picker when they are enabled on desktop.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2Fgit-blob-e5e2c433eb08f54521454bd1d002af6a74a552da%2Fmobile-all-agents.png?alt=media" alt="The Select Model sheet showing OpenAI Codex models with the active one checked"><figcaption><p>Codex models in the Select Model sheet, with the active model checked.</p></figcaption></figure>

# Voice on Mobile

Talk to the coding agents running on your desktop from the Nimbalyst iOS app. Voice relays what you say and speaks the result back to you.

Talk to your desktop coding agents from your phone. The mobile voice agent listens, relays what you say to a session running on your desktop, and speaks the result back to you. Voice Mode is in **alpha** while we polish it.

Voice is part of the mobile workflow described on the [mobile agent management page](https://nimbalyst.com/mobile-agent-management/).

Voice runs in the **iOS** app.

### Before you start

Three things need to be in place.

1. **Your phone is paired and signed in.** See [Mobile App](/mobile/mobile-app) for pairing and sync setup.
2. **Your desktop is running and connected.** Voice on mobile drives sessions on your computer, so the desktop app has to be awake and syncing. Sleep prevention under **Settings > Account > Mobile App** on desktop keeps the connection alive while you are away from your desk.
3. **An OpenAI API key has synced to your phone.** Voice Mode runs on OpenAI's realtime voice models, and your phone gets the key from your desktop rather than from a field you type into.

To check the key, open **Settings > Voice Mode** in the mobile app. The **OpenAI API Key** row should read **Synced from desktop** with a green check.

If it reads **Not synced yet**, set an OpenAI key on the desktop under **Settings > Application > Voice Mode**. A Claude or Codex agent login on its own is not enough. See [AI Provider Setup and Notifications](/setup-nimbalyst/ai-provider-setup-and-notifications). Your desktop pushes the key a few seconds after your phone connects, and again on every reconnect, so reopening the mobile app is the quickest way to trigger a resync.

### Start a voice session

There is no permanent mic button on the main screens. Voice stays off until you start it from a menu, and the floating mic appears once it connects.

**Project-wide**, where the voice agent can work with any session in the project or create a new one:

1. Open a project so you are on its session list, **Sessions** tab.
2. Tap **+** in the top right.
3. Tap **Start Voice Agent**.

**Focused on one session**, where everything you say targets that session:

1. Open the session.
2. Tap **•••** in the top right.
3. Tap **Start Voice Mode**.

The first time you start voice, iOS asks for microphone permission. Voice cannot connect without it.

To end a session, tap **Cancel** on the floating mic, open a session's **•••** menu and choose **Stop Voice Mode**, or just tell the voice agent to stop.

### The floating mic

Once connected, a floating mic sits at the bottom of the screen and a small status pill appears in the navigation bar.

| Control    | What it does                                                                                       |
| ---------- | -------------------------------------------------------------------------------------------------- |
| **Mic**    | Tap to talk, to resume after the mic has gone idle, or to interrupt the agent while it is speaking |
| **Pause**  | Releases the mic while listening, or stops the agent mid-sentence while it is speaking or thinking |
| **Resume** | Brings the mic back after an idle timeout                                                          |
| **Cancel** | Ends the voice session                                                                             |

The mic ring pulses amber with a small badge while the voice agent runs a tool, so you can watch it look something up instead of wondering whether it heard you. The status pill mirrors the same states: a filled mic while listening, a speaker while speaking, and dots while it is thinking.

### Sending a task to a session

Coding requests are not fired off the instant you finish talking. A card slides up showing the target session and the exact prompt, with a countdown running. **Cancel** drops it, **Send Now** skips the wait, and doing nothing sends it when the countdown ends. The pause gives you a chance to catch a misheard request before it reaches the agent.

Set the length of the countdown under **Settings > Voice Mode > Confirm Delay**. Once sent, the prompt queues on your desktop like any other mobile prompt and runs on your machine.

### What you can ask for

* Start a new session. The device that asked for it opens the session once it exists, and your other devices just see it appear in their list.
* Find a session by topic, described in your own words.
* Switch between sessions.
* Summarize a session, including any question it is waiting on.
* Answer a session's pending question by voice.
* Send a new coding task to a session.
* Ask the coding agent a question and wait for the spoken answer.
* Look something up in your project's docs, plans, and decisions, answered from your desktop's project memory when it is available.

### Idle and wake

After a stretch with nothing happening (30 seconds by default) the mic goes idle. The connection stays up and the microphone is released, so the app is not listening in the background. Tap the mic or **Resume** to pick up where you left off.

With **Auto-Announce Completions** on, a session finishing wakes voice back up and speaks the result. You can kick off work, put the phone in your pocket, and hear how it went.

### Mobile voice settings

Under **Settings > Voice Mode** in the mobile app:

* **OpenAI API Key.** Status of the key synced from your desktop. Read-only.
* **Voice.** The spoken voice. Your desktop's voice preference syncs here, so both devices sound the same unless you pick a different one on the phone.
* **Idle Timeout.** How long the mic stays open with nothing happening, from 10 to 120 seconds.
* **Auto-Announce Completions.** Whether a finished session wakes voice to speak its result.
* **Confirm Delay.** The countdown on the pending prompt card, from 1 to 10 seconds.

The spoken language follows the preferred agent language configured on your desktop, whatever language you speak in, and falls back to English when no preference is set.

### Troubleshooting

**No Start Voice Agent in the + menu.** The item appears on the **Sessions** tab of a project and only while voice is off. Switch back from the **Files** tab if you are on it. If voice is already running, the session menu offers **Stop Voice Mode** instead.

**"Sync an OpenAI API key from Nimbalyst on your Mac."** Your phone has no key yet. Set one on the desktop under **Settings > Application > Voice Mode**, confirm the desktop is running, then reopen the mobile app to trigger a resync. The row under **Settings > Voice Mode** on mobile should change to **Synced from desktop**.

**Microphone permission denied.** Grant it under iOS Settings > Nimbalyst > Microphone, then start voice again.

**Voice ends when the connection drops.** Mobile does not silently reconnect the way desktop does. If the connection is lost, the voice session ends and you start it again from the menu.

**Nothing reaches the desktop.** Check the connection indicator in the project list. Voice relays through the same encrypted sync channel as your sessions, so if sessions are not updating, voice commands will not land either. A sleeping desktop is the usual cause, which is what sleep prevention is for.

### A note on stability

Voice Mode is alpha and may change, break, or be removed without notice. If you hit a problem, share feedback via Discord or our support channels. See [Feedback, Discord, Support, Releases](/getting-started/feedback-discord-support-releases).

For the desktop side and the full settings panel, see [Voice Mode](/setup-nimbalyst/voice-mode).

# AI Provider Setup and Notifications

Connect Claude, Codex, Copilot, and other AI providers in Nimbalyst, add keys or subscriptions, and set up session completion notifications.

Nimbalyst works with the coding agents and AI subscriptions you already have. This page covers which providers are supported, how to connect each one under **Settings > Application**, and how to get notified when a session finishes.

### Supported AI Providers

The following coding agents are currently supported:

* Claude Agent
* OpenAI Codex
* Claude Code CLI (opt-in)
* OpenCode (Alpha)
* GitHub Copilot (Alpha)
* Grok Build (Alpha)
* Cursor Agent (Alpha)
* Gemini through Antigravity (Alpha)

Alpha providers are toggled on individually from their own settings panels. See [Alpha Features](/setup-nimbalyst/alpha-features).

Models are discovered dynamically from each provider, so current Claude and Codex generations (for example Claude Fable 5.1 and GPT-6 Astra) appear in the model picker as providers ship them.

Nimbalyst works with the agents you already pay for. See [Claude Code and Codex subscriptions](https://nimbalyst.com/claude-code-codex-subscriptions/) for how existing plans are used.

You can also configure Nimbalyst to access AI models directly; see [Integrate other AI models](#integrate-other-ai-models-with-nimbalyst-optional) below.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2Fgit-blob-ac8887ab7b6a64356819625db804833002e94f48%2Fdocs-ai-providers.png?alt=media" alt="Nimbalyst Application Settings with Claude Agent selected and the list of available agent providers in the sidebar"><figcaption><p>AI Providers in Application Settings on macOS. Select a provider in the sidebar to enable it, authenticate, and configure its behavior.</p></figcaption></figure>

### OpenAI Codex

OpenAI Codex is enabled by default for new Nimbalyst installations. Existing provider choices are preserved when you upgrade.

Open **Settings > Application > OpenAI Codex** to sign in, review the discovered models, or provide an API key override. By default, Codex uses the signed-in Codex or ChatGPT subscription.

Codex sessions support the same core Nimbalyst workflow as Claude Agent:

* **Inline edit cards**: Codex `file_change` tool calls render as red/green edit cards in the transcript, matching how Claude's Edit tool already renders.
* **Slash command autocomplete**: Codex slash commands surface in the same unified `/` picker as Claude Code commands.
* **Cross-agent skills and commands**: Skills and commands written for one agent run in the other, so workflow discovery is unified across providers.
* **Reasoning blocks**: Codex reasoning items map into transcript thinking blocks.
* **Worktree isolation**: sessions started in a worktree run inside that worktree and keep their edits on its branch.

### Claude Agent

Claude Agent is Nimbalyst's integrated Claude coding agent. Open **Settings > Application > Claude Agent** to authenticate, choose visible models, and configure its behavior.

Use your Claude subscription login or an Anthropic API key that you explicitly add in Nimbalyst. Nimbalyst does not import API keys from environment variables.

Claude Enterprise SSO is supported when your organization provides it.

#### Claude Code CLI

The raw Claude Code CLI provider is opt-in for new installations. Turn it on from the Claude Agent settings when you specifically want the native CLI terminal experience. Upgrading does not disable it if you already selected it.

When enabled, Claude models appear under separate Claude Agent and Claude Code CLI groups in the model picker.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2Fgit-blob-155361c48db88e38b613c1a691c22f0a821778c6%2FClaude%20model%20picker.png?alt=media" alt="Nimbalyst model picker showing the Claude Agent and Claude Code CLI groups" width="189"><figcaption><p>The model picker with Claude models grouped under Claude Agent and Claude Code CLI.</p></figcaption></figure>

#### Effort Level

Claude Agent and Claude Code CLI support an effort selector. Higher levels let the model spend more reasoning effort on a turn at the cost of additional latency and usage.

Pick from five levels:

* **Low**
* **Medium**
* **High**
* **xHigh**
* **Max**

The selector is part of the session controls, and it only offers the levels the selected model accepts.

#### Extended Thinking

Supported Claude Agent models also show **Extended: On** and **Extended: Off**. Extended thinking stays on by default. Turn it off per session when lower latency and token use matter more than additional reasoning.

Press **Cmd/Ctrl+Shift+M** in the chat input to open the model picker from the keyboard. Search by model name or ID, then use the arrow keys and Enter to select a model.

### OpenCode (Alpha)

OpenCode is an open-source coding agent with multi-model support. It works with Claude, OpenAI, Gemini, and local models through a unified interface.

To set it up, open **Settings > Application > OpenCode**:

1. Install the OpenCode CLI (use the **Install OpenCode CLI** button or follow the OpenCode docs).
2. Toggle **Enable OpenCode** on.
3. Configure and authenticate model providers in OpenCode's own settings. The optional API key field in Nimbalyst is used only to test the connection; it does not replace OpenCode's provider configuration.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2Fgit-blob-0ba1cca7b27772651d78b48173252aedbdc69dbf%2FOpenCode%20Settings.png?alt=media" alt="The OpenCode settings panel"><figcaption><p>OpenCode agent provider settings</p></figcaption></figure>

### GitHub Copilot (Alpha)

GitHub Copilot is supported as a coding agent via the ACP (Agent Communication Protocol) server mode. It uses your existing Copilot CLI login for authentication.

To set it up, open **Settings > Application > GitHub Copilot**:

1. Install the Copilot CLI (`npm install -g @github/copilot`, or use the **Install Copilot CLI** button).
2. Toggle **Enable GitHub Copilot** on.
3. Authenticate by running `copilot` and using the `/login` command. Model selection is managed by Copilot, so no additional API key is required.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2Fgit-blob-ad2b440697d3048d490120713d35f55cc1ec5585%2FGitHub%20Copilot%20Settings.png?alt=media" alt="The GitHub Copilot settings panel"><figcaption><p>GitHub Copilot agent provider settings</p></figcaption></figure>

### Grok Build (Alpha)

Grok Build is xAI's coding agent. Enable it under **Settings > Application > Grok Build**.

Grok Build sessions can answer questions and approve tool use while they run, reach your Nimbalyst tools, and use the model you picked.

### Cursor Agent (Alpha)

Cursor Agent runs the Cursor coding agent headlessly against your project. Install the Cursor CLI, run `cursor-agent login`, then enable it under **Settings > Application > Cursor Agent**. It uses your existing Cursor CLI login.

### Gemini through Antigravity (Alpha)

Gemini uses the language server bundled with Google's Antigravity desktop app. Install Antigravity and sign in once, then open **Settings > Application > Gemini**. Antigravity does not need to remain open while the agent runs.

### Integrate other AI Models with Nimbalyst (optional)

* Nimbalyst can integrate with Anthropic, OpenAI, or LM Studio for local models.
* Add an API key in Nimbalyst for Anthropic or OpenAI. Nimbalyst never reads those keys from environment variables.
* As these are not coding agents, only some features are supported.
* For LM Studio, run its local server and enter the server URL; it does not require an API key.
* Return to **Settings > Application** to change the configuration later.

Provider API keys you save in Nimbalyst are encrypted on disk.

### Notification that AI response is complete

Open **Settings > Application > Notifications**.

<div align="left"><figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2FSOFYBrlawEyz85s7TCzw%2Fimage.png?alt=media&token=81960173-b33d-4f8e-9aef-b2941f2bbbd2" alt="The Notifications settings panel with Completion Sounds and OS Notifications sections" width="563"><figcaption><p>The Notifications panel: completion sounds with a sound type picker and Test Sound, plus OS notifications.</p></figcaption></figure></div>

By default:

* You are notified when an AI session completes.
* When Nimbalyst is not the active window, a system notification can appear. Clicking it takes you to the workspace and session that needs attention.
* Agents can also request an attention notification during a longer workflow.

Use the Notifications page to control these behaviors.

### Completion Sounds

Nimbalyst can also play a sound when the AI or an agent finishes a turn and is ready for you again. Find it under **Settings > Application > Notifications > Completion Sounds**.

* Turn it on with **Enable Completion Sounds**.
* Pick a built-in **Sound Type** (chime, bell, or pop), or choose **custom** to use your own audio file.
* For a custom sound, click **Choose File** and pick an audio file. Supported formats are MP3, WAV, OGG, M4A, AAC, and FLAC.
* Adjust the **Volume**, and use **Test Sound** to hear your choice.

# Application, Account, and Project Settings

Nimbalyst splits settings into application, account, and project scopes, so it is clear whether a change applies everywhere or to one project.

Nimbalyst separates settings into three scopes so it is clear whether a change applies everywhere, to a signed-in identity, or only to the current project.

Open Settings with **Cmd/Ctrl+,** or from the account menu, then choose **Application**, **Account**, or **Project** at the top.

## Application

Application settings follow this Nimbalyst installation across projects. Use this scope for:

* Notifications and themes
* Voice Mode and agent features
* Agent and chat providers
* The extension Marketplace and installed extensions
* Application-level MCP servers
* Tools and token-cost controls
* Advanced and database settings

Choose Application when a provider, extension, MCP server, or preference should be available in every project you open.

Database Settings, under this scope, is where you look after a database problem. It can recover database copies Nimbalyst preserved rather than deleted, roll back a SQLite migration to the preserved PGLite copy, and explain why an automatic migration is being held back on this computer. Recovery and rollback keep the original data intact across restarts. See [Database Backups and Restore](/troubleshooting/database-backups-and-restore).

## Account

Account settings manage signed-in Nimbalyst identities and personal device sync:

* Add, reconnect, switch, or sign out of accounts
* Choose the account used for personal and mobile sync
* Pair and manage devices
* Choose projects and documents that sync to mobile
* Manage shared links owned by an account

You can sign in with multiple accounts. A project, organization, or shared link can belong to a different account from the one used for personal mobile sync.

## Project

Project settings apply only to the current workspace:

* Sharing and organization membership
* Agent permissions
* Tracker configuration
* Project-specific AI provider overrides
* Project-level MCP servers
* GitHub integration
* Project extension settings

Project-level MCP servers and provider overrides are useful when a tool or model should be available only inside one repository.

## Organization Management

Organizations have a dedicated management dialog rather than a fourth Settings scope. Open it from the organization switcher (**Manage organization…**), the account menu, or **Manage** on an organization row in **Settings > Account > Accounts**.

Use it to manage:

* Members, invitations, and roles
* Projects in the organization and who can access each one
* Organization messaging, security, and encryption
* Billing, and organization deletion under Danger zone

**Window > Organization Messages** is separate. It opens the messaging window for rooms and direct messages, not administration.

See [Set Up Nimbalyst Teams and Organizations](/team-collaboration/setup-teams-and-orgs) for the full walkthrough.

## Extension Settings

Extensions can add their own first-class pages under Application or Project settings. A Project extension page receives the current repository as context, so the same extension can keep different configuration in different projects.

If an extension page is missing, confirm that the extension is installed and enabled in the same scope.

## Choosing the Right Scope

| You want to change…                                                 | Use                 |
| ------------------------------------------------------------------- | ------------------- |
| Theme, notifications, default agent, or a tool used everywhere      | Application         |
| Signed-in accounts, mobile sync, devices, or shared links           | Account             |
| Permissions, Trackers, sharing, GitHub, or tools for one repository | Project             |
| Team roster, invitations, or organization projects                  | Organization dialog |

# Claude Code in Vertex, Bedrock

Configure Claude Code in Nimbalyst to run through Google Vertex AI or Amazon Bedrock using your own cloud account and existing credentials.

Nimbalyst can run Claude through your preferred cloud provider, Claude on Vertex AI (Google Cloud) or Amazon Bedrock, instead of Anthropic directly. Use this when your organization already has cloud billing and compliance set up with one of those providers.

You configure this by adding environment variables in the Claude Agent settings panel. Nimbalyst sets them for the Claude Code sessions it launches; they are stored with your Claude Code settings, and Nimbalyst never reads API keys from your shell environment.

### How to configure

1. Open **Settings > Application > Claude Agent**.
2. Scroll to the **Environment Variables** section.
3. Add the required variables for your provider.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2FduHzSqRK9uwYyapPlEsC%2Fimage.png?alt=media&token=84dd0e9b-faf6-46fd-a491-b339827913d5" alt="The Environment Variables section of the Claude Agent settings with name and value fields and an Add button"><figcaption><p>The Environment Variables section: enter a variable name and value, then click Add.</p></figcaption></figure>

**For Google Vertex AI:**

| Variable                      | Value                                           |
| ----------------------------- | ----------------------------------------------- |
| `CLAUDE_CODE_USE_VERTEX`      | `1`                                             |
| `CLOUD_ML_REGION`             | `global` (or a specific region like `us-east5`) |
| `ANTHROPIC_VERTEX_PROJECT_ID` | Your GCP project ID                             |

Prerequisites: Enable the Vertex AI API in your GCP project, request access to Claude models in the Model Garden, and authenticate via `gcloud auth application-default login`.

**For Amazon Bedrock:**

| Variable                  | Value                                  |
| ------------------------- | -------------------------------------- |
| `CLAUDE_CODE_USE_BEDROCK` | `1`                                    |
| `AWS_REGION`              | `us-east-1` (or your preferred region) |

Prerequisites: Enable Bedrock access in your AWS account, request access to Claude models, and configure AWS credentials (via AWS CLI, environment variables, or SSO profile).

### Benefits

* Use existing cloud credentials and billing
* Meet enterprise compliance requirements
* Choose the provider that fits your infrastructure
* No separate Anthropic API key required

# MCP

Add MCP servers to Nimbalyst so your coding agent can reach GitHub, Linear, Slack, and other services. Covers install, config, and permissions.

MCP (Model Context Protocol) servers extend what your coding agent can do in Nimbalyst. They give your agent access to external services like GitHub, Linear, Slack, and more. Add one when you want the agent to work with a tool you already use.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2FJ1pBc9XDlJuxIRdclLDe%2Fimage.png?alt=media&token=a0765aba-4f66-4128-826b-1c75aa29fd5d" alt="The MCP Servers settings page showing the Add MCP Server template gallery"><figcaption><p>The MCP Servers settings page, with the template gallery for adding a server.</p></figcaption></figure>

### What Are MCP Servers?

MCP servers are connectors that let your coding agent interact with other apps and services. When you connect an MCP server, the agent gains new abilities like:

* Creating issues in Linear
* Searching your GitHub repositories
* Querying your database
* Accessing files in Google Drive

For setup walkthroughs and a list of servers worth connecting, see [Claude Code MCP setup](https://nimbalyst.com/blog/claude-code-mcp-setup/) and [best Claude Code MCP servers](https://nimbalyst.com/blog/best-claude-code-mcp-servers/).

### Built-in MCP Tools

Nimbalyst ships its own MCP tools that any agent can call to interact with the editor:

* **AskUserQuestion**: pops up one or more multiple-choice questions in the transcript and blocks the agent until you answer.
* **PromptForUserInput**: collects several inputs at once through a single structured-prompt widget. Five field types are available: multi-select, single-select, reorder, edit-text, and confirm. Voice mode honors a `voiceFriendly` hint and defers to the screen widget for long drafts or large reorders. See [Interactive Prompts](/session-management/interactive-prompts) for examples and trigger phrases.
* **display\_to\_user** / **capture\_editor\_screenshot**: render charts, images, or screenshots inline in the transcript.
* **developer\_git\_commit\_proposal**: surfaces the interactive commit proposal widget instead of running `git commit` from a shell.

### Calling a Configured MCP Server from Chat

Just refer to the MCP server in your chat and your coding agent will figure out you need to use it.

For example:

* "Add these to a Linear ticket"
* "Analyze this cohort in PostHog"

### Application vs Project Servers

You can configure servers at two levels:

**Application**

* Available in all your projects
* Good for personal tools you always want access to
* Example: Your personal GitHub account
* Configure under **Settings > Application > MCP Servers**

**Project**

* Only available in a specific project
* Good for project-specific services
* Example: A project's database connection
* Configure under **Settings > Project > MCP Servers**

Project servers receive the current repository as their scope and do not automatically appear in other workspaces. See [Application, Account, and Project Settings](/setup-nimbalyst/settings-scopes).

### Node Runtime for MCP Servers

MCP servers configured with `command: "node"` use Electron's bundled Node runtime. You don't need a system-wide Node.js install for MCP servers to work on a fresh Nimbalyst install.

### Adding MCP Servers

1. Open **Settings** with the account menu or `Cmd/Ctrl+,`.
2. Choose **Application > MCP Servers** or **Project > MCP Servers**.
3. Click **Add Server**.
4. Choose from a template or configure manually.
5. If the server requires credentials, enter them: for **API key** servers, paste the key into the server settings; for **OAuth** servers, click **Authorize** and sign in through your browser.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2FJPvp36JRiYToq72WcUsG%2Fimage.png?alt=media&token=8009d9e6-bcb5-4575-afa0-2dc5e391edbc" alt="The GitHub MCP server template configuration with a personal access token field, Test Connection, and Add Server button"><figcaption><p>Configuring the GitHub template: enter the required credential, test the connection, then add the server.</p></figcaption></figure>

#### Available Templates

Nimbalyst includes ready-to-use templates for popular services, grouped by category in the gallery. They include:

* **Development**: GitHub, Playwright, Chrome DevTools, Context7, Serena, Sentry
* **Productivity**: Linear, Notion, Asana, Atlassian (Jira and Confluence), Slack
* **Data & Analytics**: PostHog, Snowflake, AWS, Stripe
* **Design**: Figma
* **Search & Files**: Brave Search, Fetch, Filesystem

More templates ship over time; use the search field in the gallery to find one.

### Checking Server Status

In the MCP Servers settings, each server shows its status:

* **Connected**: Working and ready to use
* **Not authorized**: Needs authentication (click Authorize)
* **Error**: Something went wrong (check the error message)

### Troubleshooting

**Server not appearing in your agent's tools?**

* Make sure the server is enabled (not disabled)
* Check that authentication is complete
* Try restarting Nimbalyst

**OAuth authorization failed?**

* Complete the sign-in process in your browser
* Try revoking and re-authorizing
* Check your internet connection

**API key not working?**

* Verify the key is correct (no extra spaces)
* Check that the key has the required permissions
* Some services require specific scopes or access levels

### Privacy & Security

* All MCP connections are made locally from your computer
* API keys and tokens are stored securely on your machine
* OAuth tokens can be revoked at any time from settings
* No credentials are sent to Nimbalyst servers

# Alpha Features

Find and enable alpha features in Nimbalyst, understand the separate Alpha update channel, and see which capabilities are still experimental.

Nimbalyst labels early capabilities as **Alpha** while we polish them. Most have their own opt-in toggle and may be unstable. A few capabilities are available only in Alpha builds.

### Where to enable Alpha

Most alpha features are opt-in per user from the feature's own settings panel, with no master "enable everything" toggle. Voice Mode and alpha agent providers use their own panels. Super Loops, Blitz, and Meta Agent are toggled under **Agent Features**.

To turn one on, open **Nimbalyst → Settings**, find the feature panel, and flip its toggle. The exception is alpha-build functionality such as syncing markdown documents to the iOS app: switch **Settings > Application > Advanced > Update Channel** to Alpha first, then enable **Docs** for the project under **Settings > Account > Mobile App**.

What has shipped out of alpha is listed on the [changelog](https://nimbalyst.com/changelog/).

### How Alpha features are labeled

Anywhere an alpha feature appears in the UI, it is tagged with an `alpha` chip next to its name. For example, in the Settings sidebar Voice Mode, OpenCode, and GitHub Copilot all show the chip:

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2Fgit-blob-418c755eb2cfc90473e4270be1b1a8c2cdec0010%2FAlpha%20Settings%20Sidebar.png?alt=media" alt=""><figcaption><p>Alpha-tagged entries in the Settings sidebar</p></figcaption></figure>

This makes it easy to tell at a glance which capabilities are in early access.

### Update Channel

The **Update Channel** selector lives in **Settings > Application > Advanced**. Choose **Stable** for production-ready releases, or **Alpha (Developer Releases)** for frequent, rough builds. Most feature toggles are independent of the channel, while features that only ship in alpha builds require the Alpha channel.

### Currently in Alpha

The following features are available in Alpha today:

#### Voice Mode

Talk to your coding agent and have it talk back, on desktop and mobile. Turn it on under **Settings > Application > Voice Mode**. For everything it can do, the settings, and the mobile voice actions, see [Voice Mode](/setup-nimbalyst/voice-mode).

#### OpenCode (Agent Provider)

OpenCode is available as an additional agent provider alongside Claude Agent and OpenAI Codex. Select it under **Settings > Application > OpenCode**. See [AI Provider Setup and Notifications](/setup-nimbalyst/ai-provider-setup-and-notifications) for configuration details.

#### GitHub Copilot (Agent Provider)

GitHub Copilot is available as an additional agent provider. Select it under **Settings > Application > GitHub Copilot**. See [AI Provider Setup and Notifications](/setup-nimbalyst/ai-provider-setup-and-notifications) for configuration details.

#### Grok Build, Cursor Agent, and Gemini (Agent Providers)

These providers also have alpha-tagged panels under **Settings > Application > Agent Providers**. Grok Build uses your Grok CLI login, Cursor Agent uses your Cursor CLI login, and Gemini uses the language server bundled with Google's Antigravity desktop app. See [AI Provider Setup and Notifications](/setup-nimbalyst/ai-provider-setup-and-notifications) for configuration details.

#### Agent Features

A consolidated panel for agent-session behavior. Its individual alpha toggles are **Super Loops**, **Blitz**, and **Meta Agent**. The panel also holds related settings such as Auto-approve Commits, MCP server status, preferred agent language, and attachment staging. Find it under **Settings > Application > Agent Features**.

#### Database Recovery

In Developer Mode, **Settings > Application > Database** is alpha-tagged. It shows migration status and preserved recovery copies. Use it only when diagnosing or recovering the app database; see [Database Backups and Restore](/troubleshooting/database-backups-and-restore).

### A note on stability

Alpha features may change, break, or be removed without notice. If you hit a problem, please share feedback via Discord or our support channels — see [feedback-discord-support-releases.md](/getting-started/feedback-discord-support-releases).

# Voice Mode

Talk to your coding agent and hear it reply. How to turn on Nimbalyst Voice Mode on desktop and mobile, pick a voice, and run hands-free.

Talk to your coding agent and have it talk back, on desktop and mobile. Voice Mode is in **alpha** while we polish it.

### Turn it on

Open **Settings > Application > Voice Mode** and flip the toggle. There is no separate release channel to switch. The panel also shows microphone permission status, with a deep link to macOS System Settings if you need to grant access.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2Fgit-blob-a536abd156bfbb47dc296c751a8d0c8ba2d0863c%2Frelease-voice-mode.png?alt=media" alt="The activity bar mic button highlighted while Voice Mode is active"><figcaption><p>The mic button in the activity bar lights up while Voice Mode is active.</p></figcaption></figure>

### What the voice agent can do

* **Start a new coding session by voice.** Say something like "create a new session" and the agent creates one and makes it active, so any follow-up such as "ask the coding agent to..." or "run this prompt" targets the new session without you navigating there.
* **Run "Commit with AI" by voice.** The agent surfaces the same commit-proposal widget you get from the UI. Approve or reject by voice.
* **Use workspace slash commands.** Ask the voice agent to run a slash command that is available in the current project, such as "run the commit command" or "use slash track for this bug."
* **Generate a project summary** without an Anthropic API key. "Generate Project Summary" launches a new session in your configured agent (Claude Code, Codex, and so on) rather than calling the Anthropic API directly.

The voice agent reads the same workspace command catalog as the chat composer. A command must be available in the current project before voice can use it. See [/ Commands and Skills](/session-management/commands-and-skills) for built-in, extension-provided, and custom commands.

### On mobile

The voice agent runs in the iOS app too, and can drive your desktop sessions hands-free:

* Start a new coding session on your desktop.
* Find a session by topic, spoken in your own words.
* Switch between sessions.
* Summarize a session, including any question it is waiting on.
* Answer a session's pending question by voice.
* Send a new coding task to your desktop agent.

There is no permanent mic button on mobile. Start voice from the **+** menu on a project's **Sessions** tab (**Start Voice Agent**) or from the **•••** menu inside a session (**Start Voice Mode**). The API key comes from your desktop rather than a field on the phone. For setup, controls, and troubleshooting, see [Voice on Mobile](/mobile/voice-on-mobile).

#### The floating mic

While the voice agent is working, a floating mic shows what it is doing at each step. **Pause** stops it listening or speaking, and **Cancel** ends the turn, so you always stay in control.

### Settings

Voice Mode has its own settings panel under **Settings > Application > Voice Mode**:

* **Realtime Model.** `gpt-realtime-2` is the newer model, with stronger reasoning, a larger context window, and more consistent voice. `gpt-realtime` is the fallback for accounts without access to it.
* **Reasoning Effort.** Choose from minimal, low, medium, high, and extra high. Higher is smarter but slower and more expensive; low is a good default for a responsive voice relay. This applies to `gpt-realtime-2`.
* **Voice.** Pick the spoken voice, with a Preview button to hear a sample.
* **Turn detection.** Tune how the agent decides you are done speaking: input mode, voice-detection sensitivity, pause before processing, whether it can be interrupted, and how long the mic keeps listening (the listen window, 5 to 30 seconds).
* **Command submission.** Set a review delay before a voice command is sent to the coding agent, from immediate up to 10 seconds, so you can catch and edit a misheard request.
* **Language.** The voice agent always speaks in your configured preferred language, whatever language you speak to it in.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2Fgit-blob-d7da8472dabe2b2642a4cf9fdd2f3ae68aa3c807%2Fvoice-mode-settings.png?alt=media" alt="The Voice Mode settings panel showing turn detection, command submission, project summary, and pricing"><figcaption><p>The Voice Mode settings panel under Settings > Application > Voice Mode.</p></figcaption></figure>

The panel also shows a **Project Summary** (an AI-generated overview of your project that the voice agent uses for context, which you can regenerate) and OpenAI's **usage pricing** for voice, since Voice Mode runs on OpenAI's realtime voice models.

### The listen window

On desktop, the listen window (15 seconds by default) starts when audio playback drains in your speakers, not when the server finishes streaming, so the mic stays open through the end of the agent's reply. Turns that only call a function also wake the mic, with a short readiness cue when there is no audible reply.

### A note on stability

# Open Data, Workflow, File Storage

Nimbalyst keeps your documents, metadata, and settings in open formats on your own machine, and the app itself is open source on GitHub.

This page covers where Nimbalyst keeps your content and configuration. Your documents, plans, workflow commands, and images live as ordinary files in your own folders, in formats any tool can read.

### Open Source App

Nimbalyst itself is open source. The full source code is published at [github.com/nimbalyst](https://github.com/nimbalyst), so you can audit how your files, sessions, and settings are handled, build your own version, or contribute back.

More on the license and what is open is on the [open source page](https://nimbalyst.com/open-source/).

### Documents and Status Stored as Markdown

<div align="left"><figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2F6qdZTYzclP9YyAlXGceK%2FMetaData%20Storage%20of%20Status.png?alt=media&token=d2ee7e1f-7a68-4802-8f17-e1629cf335fc" alt="A plan file open in the Nimbalyst editor, showing YAML frontmatter above the markdown body" width="375"><figcaption><p>A plan file in the editor. The YAML frontmatter at the top holds the plan's status, priority, owner, tags, and dates; the markdown body follows below.</p></figcaption></figure></div>

* **Human-readable format**: Plans, documents, tasks, and status tracking use standard markdown files
* **Version control ready**: Plain text files work with Git for history and collaboration
* **YAML frontmatter**: Structured metadata sits as YAML at the top of the markdown file
* **No proprietary formats**: Edit your files with any text editor, never locked into a specific tool
* **Transparent tracking**: Plan status, progress, and metadata are all visible and editable in the markdown source

### Workflow and Config Stored as Coding Agent Commands

<div align="left"><figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2F2CmBcWlMXetcBpydPkX2%2FCustom%20Claude%20Code%20%3A.png?alt=media&token=9f1d2827-c848-4619-906b-43466c8cdb6c" alt="Claude Code documentation describing custom slash commands stored as markdown files" width="375"><figcaption><p>Claude Code's custom slash commands are markdown files in the .claude/commands/ folder of your project, so your Nimbalyst workflows use the same open format.</p></figcaption></figure></div>

* **Slash commands**: Custom workflows stored in `.claude/commands/` as markdown files
* **Project instructions**: Repository-specific guidance in `CLAUDE.md` checked into your codebase
* **Local configuration**: Settings and preferences stored in standard application directories
* **Portable workflows**: Share custom commands and workflows by committing them to version control
* **No vendor lock-in**: All configuration uses open standards and readable formats

### Your Files Stored in Your File Tree or GitHub

<div align="left"><figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2FNUe9HQDTAR6AMpRKIzgO%2FStore%20in%20Markdown.png?alt=media&token=ab90698a-57bc-42dc-a0a3-1565b5fe310a" alt="A plans folder in the file tree containing individual .md plan files"><figcaption><p>A project's plans folder in the file tree. Each plan is an ordinary .md file you can open with any editor.</p></figcaption></figure></div>

* **File system first**: Local documents are stored directly in your local file system
* **Optional team workspace**: Files explicitly promoted to Nimbalyst Teams gain a shared copy that flows through Cloudflare encrypted in transit and at rest
* **Git integration**: Full support for Git version control and GitHub synchronization
* **Your choice of sync**: Use GitHub, GitLab, Bitbucket, or any Git hosting service you prefer
* **Standard file structure**: Local project content stays in files and folders you control
* **Backup friendly**: Standard file storage works with any backup solution

### Your Images Stored in Your Project

When you paste or insert an image, the image file itself is saved in your project's `.nimbalyst/assets` folder, and your markdown file holds a plain link to it. Both travel with the project like any other file.

# Permissions and Safety

How Nimbalyst permissions keep AI agents in bounds by approving file writes and shell commands, and guarding against prompt injection.

This page explains how permissions control what an AI agent can do in your projects: the settings Claude Code brings with it, the trust and approval layer Nimbalyst adds on top, and how to manage both.

### Why Permissions Matter

AI agents can execute code, modify files, and run shell commands. Without guardrails, a prompt injection or a mistake could delete files, leak secrets, or run malicious code. Permissions keep you in control.

How Nimbalyst surfaces and enforces agent permissions is covered on the [security feature page](https://nimbalyst.com/features/security/).

### Claude Code's Built-in Permissions

Claude Code uses settings files to define what the agent can do:

* **`.claude/settings.json`** - Project settings (shared with team)
* **`.claude/settings.local.json`** - Personal project settings (gitignored)
* **`~/.claude/settings.json`** - Global user settings

Each file can specify:

* `allow` - Patterns that auto-approve
* `deny` - Patterns that always block
* `additionalDirectories` - Folders outside the project the agent can access

Nimbalyst reads and honors these files, so permissions you already set up for Claude Code carry over.

### What Nimbalyst Adds

Nimbalyst adds a **workspace trust layer** on top of the coding agent's permissions:

1. **Trust Gate** - Projects must be explicitly trusted before the agent can do anything
2. **Permission Modes** - Choose how much autonomy to grant the agent
3. **Inline Confirmations** - Approve or deny actions as they happen

### Permission Modes

When you first use an agent in a project, Nimbalyst presents four autonomy levels:

| Mode                             | Behavior                                                                                                                                                      |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Agent-verified** (Recommended) | Routine work proceeds without interrupting you. Risky or uncertain actions are evaluated by the provider's automatic reviewer and can still require approval. |
| **Allow everything**             | Operations run without approval prompts or automatic review. Use only in a project and environment you fully trust.                                           |
| **Allow edits only**             | File edits proceed automatically. Shell commands and web requests ask first.                                                                                  |
| **Ask every time**               | Approve each agent action before it runs. Your saved approvals are remembered.                                                                                |

**Agent-verified** is the default. It keeps normal workflows moving while retaining a second review step for destructive or uncertain operations. Claude Agent and OpenAI Codex use their native automatic reviewers behind the same Nimbalyst mode.

### Allowing Web Searches in Allow Edits Only

To allow your coding agent to search and fetch websites, add approved domains to the URL allow list in Agent Permissions. You can use wildcard domain patterns such as `*.github.com` to allow subdomains, or use **Allow All Domains** when broad web access is appropriate for the project.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2FXLoMU3aubjguuZ8gGibh%2Fimage.png?alt=media&token=8005940b-2500-43eb-9078-d3025b1844dd" alt="The URL allow list in Agent Permissions, showing wildcard patterns and an Add URL Pattern button"><figcaption><p>The URL allow list in Agent Permissions. Each entry is a domain pattern, such as *.github.com, and Add URL Pattern adds a new one.</p></figcaption></figure>

### How Approval Works in Ask Every Time

When the agent wants to perform an action in **Ask every time**:

1. An inline confirmation appears with the action details
2. You choose:

* **Deny** - Block this request.
* **Allow Once** - Allow only this request.
* **Session** - Allow the displayed pattern until you close Nimbalyst.
* **Always** - Save the displayed pattern to `.claude/settings.local.json`.

### Managing Permissions

Open **Settings > Project > Agent Permissions** to:

* Change your permission mode
* View and remove approved patterns
* Add additional directories
* Reset to defaults

Permissions are project-specific. Giving an agent more autonomy in one repository does not grant the same access in every project.

### Pattern Examples

* `Bash(git:*)` - Allow git commands
* `Bash(npm:*)` - Allow npm commands
* `Edit` - Allow file edits
* `WebFetch(domain:github.com)` - Allow fetching from github.com

### Security Notes

* Sensitive paths (`~/.ssh`, `~/.aws`, etc.) are always blocked
* Compound bash commands get one-time patterns that don't persist
* Untrusted projects deny agent actions until you choose a permission mode

# Privacy

Nimbalyst is local first. Files, app state, and agents stay on your machine, and online features move only the data that feature needs.

This page describes what stays on your machine, what data moves when you turn on an online feature, and how to opt out of telemetry.

### Local First, Shared When You Choose

Nimbalyst starts with local files, local application state, and agents configured on your machine. You can use the desktop app without moving a project into a hosted workspace.

Online features move only the data needed for the feature you choose:

* **Local workspace by default**: Project files remain outside Nimbalyst Teams unless you explicitly promote them into the shared team workspace.
* **Nimbalyst Teams**: Shared files and Trackers flow through Nimbalyst's Cloudflare sync service. Team data is encrypted in transit and at rest, isolated per team, and available only to authenticated, authorized members.
* **Personal device sync**: Personal sessions, prompts, drafts, and settings use a separate end-to-end encrypted channel.
* **Optional telemetry**: Nimbalyst collects anonymous product analytics to improve the app. You can opt out under **Settings > Application > Advanced > Analytics**. Telemetry does not include file contents, file paths, API keys, authentication tokens, document content, session content, or chat content.
* **Accounts are optional for local use**: An account is required for online services such as Nimbalyst Teams and personal device sync, not for local editing.
* **API keys and settings protected on disk**: Provider API keys are encrypted at rest, and Nimbalyst's settings files are written with private file permissions (as of v0.77.2).
* **Open source**: Verify how these boundaries are implemented in the source at [github.com/nimbalyst](https://github.com/nimbalyst).

### In-App Feedback Reports

Filing a bug report or feature request from inside the app sends nothing until you approve it:

* Logs are gathered only if you leave the consent checkbox on when starting a bug report.
* Everything gathered goes through an anonymization pass, a scrubbing step plus an AI redaction step over file paths, project names, and identifiers, before you see the draft.
* You review the redacted draft, and the report opens as a pre-filled GitHub issue form in your browser. You submit it yourself on github.com; nothing is posted on your behalf.

The [trust page](https://nimbalyst.com/trust/) lists the subprocessors involved when you turn on team features.

# Session and Window State Storage

Where Nimbalyst stores AI session history and window state on your machine, including the local database location on macOS, Windows, and Linux.

Session history and window state are stored in a local database on your own machine. This page covers which database that is, where it lives, and what a session record contains.

### The database

**Backend:** SQLite on newer installs. Installs that predate the SQLite migration stay on PGLite until they migrate.

**Tables:** `ai_sessions` for the sessions themselves, `ai_agent_messages` for the message log behind each one.

**Location:** inside the Nimbalyst application data folder.

| Platform | Application data folder                   |
| -------- | ----------------------------------------- |
| macOS    | `~/Library/Application Support/Nimbalyst` |
| Windows  | `%APPDATA%\Nimbalyst`                     |
| Linux    | `~/.config/Nimbalyst`                     |

Development builds use an `@nimbalyst/electron` folder in the same platform-specific location.

The database itself is `sqlite-db/nimbalyst.sqlite` on SQLite, or the `pglite-db/` folder on PGLite.

### What a session record holds

* Session id, title, and workspace
* Provider and model
* Session type, mode, and agent role
* Document context and the last document state
* Draft input you typed but have not sent
* Parent, branch, and worktree links
* Status, pinned and archived flags, and created and updated timestamps

Conversation messages are stored separately in `ai_agent_messages` and linked back to the session id, so a long transcript does not have to be rewritten every time the session changes.

### Backups

Nimbalyst backs this database up every 12 hours by default and on quit, keeping two rolling copies by default. You can change the interval and keep one to three copies under **Settings > Application > Database**. See [Database Backups and Restore](/troubleshooting/database-backups-and-restore) for the backup locations and restore steps.

# Security

How Nimbalyst handles files, sessions, and credentials, with open source code your security team can audit and encryption for shared data.

This page covers how Nimbalyst approaches security: open source code you can audit, SOC 2 Type 2 certification, and encryption for shared team data.

### Open Source: Audit the Code Yourself

Nimbalyst is open source. The full source code is published at [github.com/nimbalyst](https://github.com/nimbalyst), so you (or your security team) can review exactly how the app handles your files, sessions, credentials, and network traffic.

### Nimbalyst is SOC 2 Type 2 Certified

Nimbalyst holds a SOC 2 Type 2 certification: an independent auditor has examined our security, availability, and confidentiality controls and verified they operated over time, not just on the day of the audit. Compliance is monitored continuously between audits.

Current certifications, subprocessors, and policies are published on the [trust page](https://nimbalyst.com/trust/), and the [security feature page](https://nimbalyst.com/features/security/) covers how data is handled in the app.

### Nimbalyst Teams Data Security

Nimbalyst Teams is a shared layer over each teammate's local Nimbalyst installation and locally configured agents. Only files and Tracker items explicitly shared with a team enter the team collaboration flow.

* **Cloudflare infrastructure**: Shared team data flows through Nimbalyst's Cloudflare sync service.
* **Encrypted in transit and at rest**: Team documents, Tracker data, and collaboration updates are encrypted while moving across the network and while stored.
* **Isolated per team**: Team data is stored in team-specific infrastructure and access requires an authenticated, authorized membership.
* **Server-managed team keys**: Nimbalyst-hosted Teams manages encryption keys so authorized web, CLI, and agent experiences can access team work. Hosted team data is encrypted but is not zero-knowledge.
* **Separate personal sync**: Personal device sync uses end-to-end encryption with keys that stay on your devices.

# FAQs

Answers to common Nimbalyst questions about open source, Claude Code custom commands, multiple workspaces, data privacy, offline use, and file associations.

Quick answers to the questions we hear most often.

### **Is Nimbalyst open source?**

Yes. Nimbalyst is open source and the code lives at [github.com/nimbalyst](https://github.com/nimbalyst). You can read the source, file issues, and contribute pull requests.

The [open source page](https://nimbalyst.com/open-source/) covers the license and what is included.

### **Can I use my existing Claude Code custom commands?**

Yes. Nimbalyst runs Claude Code itself, so slash commands in `.claude/commands/` and the instructions in your `CLAUDE.md` work the same way they do in the terminal.

### **Can I have multiple workspaces open?**

Yes, you can open as many windows as you like. Each workspace is independent, and you switch between them with the standard window shortcuts.

### **Is my data sent to AI providers?**

When you send a message to an agent, the prompt and the context supplied to that session go to the agent or model provider you selected. Nimbalyst does not send your project files to an AI provider merely because you opened or edited them. API keys you enter in Settings are stored encrypted at rest on your device and are used to authenticate requests to that provider.

With LM Studio, inference runs on the local server you configured. Other app features, such as update checks, sign-in, sync, or optional sharing, may still use the internet independently of the model request. See [Privacy](/open-safe-private-secure/privacy) for the full data-flow explanation.

### **Nimbalyst keeps opening my .md files instead of VS Code (or another app)**

This is a macOS behavior, not a Nimbalyst issue. On Mac, the "Always Open With" option in the right-click menu only applies to **that specific file**, not all files of that type.

To change the default app for **all** `.md` files:

1. In Finder, select any `.md` file
2. Press **⌘ + I** (Get Info)
3. Under **Open with**, select your preferred app (e.g., Visual Studio Code)
4. Click **Change All...**

This tells macOS to open every `.md` file with your chosen app going forward.

### **Can I use Nimbalyst offline?**

The full markdown editor works offline. AI features need an internet connection, except LM Studio, which runs locally.

### **What languages does Nimbalyst support?**

English today.

### **How does Nimbalyst compare to my current tools?**

Side-by-side comparisons against editors, task trackers, diagram tools, and agent harnesses are on the [comparison pages](https://nimbalyst.com/compare/).

# Troubleshooting

Fix common Nimbalyst problems, including agents not responding, provider outages, API key and login errors, sync issues, and install trouble.

This page collects fixes for the most common problems: an agent that stops responding, and crashes or freezes caused by running out of memory. For database problems, see [Database Backups and Restore](/troubleshooting/database-backups-and-restore).

### Claude or Codex is not responding: check the provider status pages first

Before you dig into Nimbalyst settings, your network, or your API key, check whether Anthropic or OpenAI is having an outage. When their APIs are degraded or down, sessions hang, time out, or return errors that look like a Nimbalyst bug but are not.

* **Anthropic (Claude):** [status.anthropic.com](https://status.anthropic.com)
* **OpenAI (Codex / ChatGPT):** [status.openai.com](https://status.openai.com)

If either provider is reporting an incident on the affected component (Messages API, Claude Code, Codex, etc.), the fix is to wait for them to recover. There is nothing to change on your end.

### Nimbalyst is crashing: increase the heap size

If Nimbalyst is crashing, freezing, or showing out-of-memory errors (especially in large projects, long sessions, or while working with big diffs), the V8 memory limit is the likely culprit. The default heap size is **4 GB**, which is enough for most projects but can be too small if you keep many sessions, tabs, or files open at once.

**How to increase it:**

1. Open **Nimbalyst > Settings > Application > Advanced**.
2. Scroll to the **Tools & Environment** section.
3. Find **Max Heap Size** and pick a larger value (6 GB, 8 GB, 12 GB, or 16 GB).
4. Restart Nimbalyst. The new limit takes effect on the next launch.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2Fgit-blob-ed790f306078947273cbed5cfb6f07229bb89bfb%2FIncrease%20Heap%20Size.png?alt=media" alt="Application settings, Advanced, Tools and Environment, with the Max Heap Size dropdown open"><figcaption><p>Settings > Application > Advanced > Tools & Environment: Max Heap Size dropdown</p></figcaption></figure>

Pick the smallest size that comfortably fits your workload. Going higher than you need does not make Nimbalyst faster, it just lets V8 hold more in memory before garbage collecting. If you routinely hit the ceiling at 4 GB, 8 GB is a reasonable next step. Reach for 12 GB or 16 GB only if you work with very large repos or many parallel sessions.

If raising the heap does not fix the crashes, share details (project size, what you were doing, any error messages) via Discord or support. See [Feedback, Discord, Support, Releases](/getting-started/feedback-discord-support-releases).

Still stuck? The [Nimbalyst site](https://nimbalyst.com/) has feature walkthroughs and demo videos that often show the setting you are looking for, and support is at <support@nimbalyst.com>.

# Database Backups and Restore

Where Nimbalyst stores its automatic database backups on macOS, Windows, and Linux, and how to restore one by hand for both the SQLite and PGLite backends.

Nimbalyst keeps rolling backups of its local database so a corrupted database does not cost you your session history. This page covers where those backups live, how often they are taken, and the exact restore steps for both database backends.

## Try in-app recovery first

Before restoring anything by hand, open **Settings > Application > Database**. Database Settings can handle the common cases without the command line:

* **Databases set aside on this computer** lists any database copy Nimbalyst preserved rather than deleted, with when it was set aside and what it contains. You can review a copy, reveal it on disk, or restore it. Restore is always an explicit action you confirm; nothing is restored automatically.
* **PGLite copies kept from a migration** shows the pre-migration copy of your PGLite database after a SQLite migration, and **Restore from preserved PGLite** rolls back to it if the migration left you worse off.
* If automatic migration has been **held back on this computer**, the panel explains the recorded reason and lets you clear the block so a later launch can assess the migration again.

Recovery and rollback keep the original data intact across restarts, so trying an in-app restore does not burn your only copy. The manual steps below are for when the app cannot start at all, or when you need a specific rolling backup slot that the panel does not offer.

## Which backend you are on

Nimbalyst ships two local database backends. Newer installs use **SQLite**. Installs that started before the SQLite migration stay on **PGLite** until you migrate.

Check in this order, inside the Nimbalyst application data folder (paths below). Nimbalyst itself resolves the backend the same way, so stop at the first line that matches:

1. **`database-backend.json` exists.** Open it and read the `backend` field. It says either `sqlite` or `pglite`, and it wins over everything else on disk.
2. **No `database-backend.json`, but a `pglite-db` folder exists.** You are on PGLite.
3. **Neither.** You are on SQLite.

You can also read the answer straight from the log: the first database line in `logs/main.log` inside the application data folder looks like `[Database] Backend selector resolved to 'sqlite'`.

Do not judge by the presence of a `sqlite-db` folder alone. If you migrated to SQLite and later rolled back from **Settings → Database**, that folder stays behind while `database-backend.json` says `pglite`, and restoring into it would do nothing.

You may also see a `pglite-db.migrated-<timestamp>` folder. That is the pre-migration copy of your old PGLite database, kept as a safety net. It is not the live database and it is not a backup slot, so ignore it when following the steps below. Database Settings manages these copies for you, including rollback and deletion, under **PGLite copies kept from a migration**.

Each backend has its own backup folder, so follow the section that matches yours.

## Where the files live

The application data folder is:

Development builds use an `@nimbalyst/electron` folder in the same platform-specific location.

Inside that folder:

| What          | SQLite                                                                                                  | PGLite                                                                                |
| ------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Live database | `sqlite-db/nimbalyst.sqlite` (plus `-wal` and `-shm` siblings)                                          | `pglite-db/` (a folder)                                                               |
| Backups       | `sqlite-db.backups/`                                                                                    | `db-backups/`                                                                         |
| Backup slots  | `nimbalyst.backup-current.sqlite`, `nimbalyst.backup-previous.sqlite`, `nimbalyst.backup-oldest.sqlite` | `pglite-db.backup-current/`, `pglite-db.backup-previous/`, `pglite-db.backup-oldest/` |
| Backup index  | `backup-metadata.json`                                                                                  | `backup-metadata.json`                                                                |

`backup-metadata.json` records the timestamp, size, and verification result for each slot, which is the quickest way to see how fresh your newest backup is.

## How backups are taken

* **Every 12 hours by default** while Nimbalyst is running.
* **On quit**, as part of the shutdown sequence.
* **At startup and on wake from sleep**, if the last successful backup is older than the configured interval. A laptop that slept through a backup window still gets a fresh snapshot.
* **Two rolling copies by default.** A new backup becomes `current` and the old `current` becomes `previous`.
* **Verified before it is kept.** Nimbalyst opens each new backup and reads from it before promoting it into the rolling slots, and rejects a snapshot that has shrunk to less than half the size of the one it would replace.

Under **Settings > Application > Database**, you can keep one, two, or three copies and change the interval. Setting the interval to **On quit only** disables periodic backups. Cadence changes take effect after a restart. The `oldest` slot exists only when you keep three copies.

On PGLite, a database that fails to open at startup triggers an automatic restore from the newest valid backup. On SQLite, restore is a manual step, which is what the rest of this page walks through.

## Restore a SQLite backup

Only follow this section if you confirmed SQLite is your active backend above.

Quit Nimbalyst completely first. Restoring while the app is running will not work, and can leave you with a half-written database.

### macOS and Linux

```bash
# 1. Quit Nimbalyst completely (Cmd+Q on macOS)

# 2. Go to the application data folder
cd ~/Library/Application\ Support/Nimbalyst     # macOS
# cd ~/.config/Nimbalyst                        # Linux

# 3. Move the bad database aside, including its WAL and SHM siblings
mv sqlite-db/nimbalyst.sqlite sqlite-db/nimbalyst.sqlite.bad
rm -f sqlite-db/nimbalyst.sqlite-wal sqlite-db/nimbalyst.sqlite-shm

# 4. Copy the most recent backup into place
cp sqlite-db.backups/nimbalyst.backup-current.sqlite sqlite-db/nimbalyst.sqlite

# 5. Start Nimbalyst
```

### Windows (PowerShell)

```powershell
# 1. Quit Nimbalyst completely

# 2. Go to the application data folder
cd "$env:APPDATA\Nimbalyst"

# 3. Move the bad database aside, including its WAL and SHM siblings
Rename-Item sqlite-db\nimbalyst.sqlite nimbalyst.sqlite.bad
Remove-Item sqlite-db\nimbalyst.sqlite-wal, sqlite-db\nimbalyst.sqlite-shm -ErrorAction SilentlyContinue

# 4. Copy the most recent backup into place
Copy-Item sqlite-db.backups\nimbalyst.backup-current.sqlite sqlite-db\nimbalyst.sqlite

# 5. Start Nimbalyst
```

Deleting the `-wal` and `-shm` files matters. They belong to the database you just replaced, and leaving them behind can corrupt the restored copy.

## Restore a PGLite backup

Only follow this section if you confirmed PGLite is your active backend above. If `database-backend.json` says `sqlite`, Nimbalyst never opens `pglite-db` and restoring it changes nothing. Use the SQLite steps instead.

Quit Nimbalyst completely first, the same as for SQLite.

PGLite stores its database as a folder rather than a single file, so every copy here is recursive.

### macOS and Linux

```bash
# 1. Quit Nimbalyst completely (Cmd+Q on macOS)

# 2. Go to the application data folder
cd ~/Library/Application\ Support/Nimbalyst     # macOS
# cd ~/.config/Nimbalyst                        # Linux

# 3. Rename the corrupted database (keeps it around just in case)
mv pglite-db pglite-db.bad

# 4. Copy the most recent backup into place
cp -r db-backups/pglite-db.backup-current pglite-db

# 5. Start Nimbalyst
```

### Windows (PowerShell)

```powershell
# 1. Quit Nimbalyst completely

# 2. Go to the application data folder
cd "$env:APPDATA\Nimbalyst"

# 3. Rename the corrupted database
Rename-Item pglite-db pglite-db.bad

# 4. Copy the most recent backup into place
Copy-Item -Recurse db-backups\pglite-db.backup-current pglite-db

# 5. Start Nimbalyst
```

## If the newest backup is also bad

Open `backup-metadata.json` in the backup folder before you pick. It lists each slot with its `timestamp`, `sizeBytes`, and `verified` flag, so you can see how much work each choice costs you rather than guessing.

Then work back through the available slots. `previous` is one backup window older. If you configured three copies, `oldest` is two windows older.

```bash
# SQLite
cp sqlite-db.backups/nimbalyst.backup-previous.sqlite sqlite-db/nimbalyst.sqlite
cp sqlite-db.backups/nimbalyst.backup-oldest.sqlite   sqlite-db/nimbalyst.sqlite

# PGLite
cp -r db-backups/pglite-db.backup-previous pglite-db
cp -r db-backups/pglite-db.backup-oldest   pglite-db
```

Repeat the same quit, clear, copy, launch sequence each time.

## What a restore brings back

The database holds:

* AI session and conversation history
* Document edit history behind the History sidebar
* Session metadata, prompts, and drafts
* Local tracker data

The following live outside the database and are untouched by a database problem or a restore:

* Your document and project files on disk
* Application and workspace settings
* Anything already synced to a Nimbalyst team

Because a restore rewinds to the last snapshot, work done between that snapshot and the failure is not recovered. Files on disk are unaffected either way.

## Cleaning up

Once you have confirmed the restore worked and your sessions are back, delete the copy you set aside.

macOS and Linux:

```bash
rm -f  sqlite-db/nimbalyst.sqlite.bad     # SQLite
rm -rf pglite-db.bad                      # PGLite
```

Windows (PowerShell):

```powershell
Remove-Item sqlite-db\nimbalyst.sqlite.bad            # SQLite
Remove-Item -Recurse -Force pglite-db.bad             # PGLite
```

You may also see `temp-backup-*` entries in a backup folder after a crash. They are leftovers from an interrupted snapshot, Nimbalyst sweeps them on the next launch, and they are safe to delete.

## Still stuck

If none of the available backups will open, send us the contents of `backup-metadata.json` and the main log from the `logs` folder in the same application data directory. Reach out on Discord or at <support@nimbalyst.com>, see [Feedback, Discord, Support, Releases](/getting-started/feedback-discord-support-releases).

# Windows: Detailed Install Guide

Install Nimbalyst on Windows, open a project, and connect Claude Agent or OpenAI Codex using a plan login or API key.

This guide takes you from the Windows installer to your first agent session. Download the current `.exe` from the [Nimbalyst download page](https://nimbalyst.com/download/).

## Install the App

1. Open the downloaded Nimbalyst installer.
2. Choose the installation options you want and finish setup.
3. Launch Nimbalyst from the Start menu or the shortcut you created.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2FmAFREIYBbckdzLjrkVw8%2Fimage.png?alt=media&token=1209ac95-95c7-4821-a15d-2ff8d9be154b" alt="The Windows installer showing Nimbalyst installation options"><figcaption><p>Choose the shortcuts you want, then continue through the installer.</p></figcaption></figure>

## Open a Project

A project is a folder on your PC. It can be a Git repository or any other folder containing the documents and files you want to work with.

1. On the Project Manager screen, choose **Open Folder** or **New Folder**.
2. Complete the welcome screen. Choose Standard Mode for a simpler writing workspace or Developer Mode for Git, terminal, and worktree features; you can change this later.
3. Use **Start tutorial** if you want a disposable example project, or **Get started…** to open your own folder.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2FERG8tVZGleWZowVZf5Lw%2Fimage.png?alt=media&token=347f5aad-358c-4275-954e-9e3ad9337fef" alt="Nimbalyst Project Manager for choosing or creating a project folder" width="563"><figcaption><p>Each project is backed by a folder on your filesystem.</p></figcaption></figure>

## Connect an Agent

The standard Claude Agent and OpenAI Codex integrations are included with Nimbalyst. You do not need to install Git for Windows or a separate CLI for either one.

1. Open **Settings > Application > AI Providers**.
2. Select **Claude Agent** or **OpenAI Codex** and enable it.
3. Authenticate with a supported subscription login, or choose the API-key option and enter your own key.
4. Return to the workspace, create a session, and select that provider in the composer.

Claude plan login opens a terminal for the OAuth flow and may ask you to type `/login`; return to Settings and click **Refresh** when authentication finishes. Codex plan login opens the ChatGPT sign-in flow in your browser.

{% hint style="info" %}
Git for Windows is still useful for Git repositories and is required by some optional CLI-based providers, but it is not required for Nimbalyst's standard bundled Claude Agent or Codex integrations. See [AI Provider Setup](/setup-nimbalyst/ai-provider-setup-and-notifications).
{% endhint %}

## Windows Spellchecker

Nimbalyst uses Electron's Windows spellchecker, which defaults to English. You can turn it off in Settings.

## Start Working

Type a request in the agent panel. The agent can research, write and edit files, build mockups and diagrams, and work with the project context that you give it. You review file changes in Nimbalyst before accepting them.

# Mac: Detailed Install Guide

Install Nimbalyst on macOS, open a project, and connect Claude Agent or OpenAI Codex using a plan login or API key.

This guide takes you from the macOS disk image to your first agent session. Download the current installer from the [Nimbalyst download page](https://nimbalyst.com/download/).

## Install the App

1. Open the downloaded Nimbalyst `.dmg` file.
2. Drag Nimbalyst into **Applications**.
3. Open Nimbalyst from **Applications**.
4. If macOS asks whether you want to open an app downloaded from the internet, click **Open**.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2FRlRD5cc8N284ThTTmDzY%2Fimage.png?alt=media&token=5c7d0776-4fb6-421f-88cd-c116dbf57597" alt="The Nimbalyst disk image with an arrow from the app to the Applications folder"><figcaption><p>Drag Nimbalyst into Applications, then launch it from there.</p></figcaption></figure>

Nimbalyst updates itself after installation. If macOS blocks the first launch, open **System Settings > Privacy & Security** and use the option to open Nimbalyst there.

## Open a Project

A project is a folder on your Mac. It can be a Git repository or any other folder containing the documents and files you want to work with.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2FI6MthAn6ZWD1patQ1pTY%2Fimage.png?alt=media&token=669e5a74-571b-4e59-b38d-c2081eb27198" alt="Nimbalyst Project Manager for choosing or creating a project folder"><figcaption><p>Each project is backed by a folder on your filesystem.</p></figcaption></figure>

## Connect an Agent

The standard Claude Agent and OpenAI Codex integrations are included with Nimbalyst. You do not need to install a separate CLI for either one.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2Fgit-blob-ac8887ab7b6a64356819625db804833002e94f48%2Fdocs-ai-providers.png?alt=media" alt="Nimbalyst Application Settings with Claude Agent selected and other agent providers listed in the sidebar"><figcaption><p>The AI Providers settings on macOS. Leave Custom Claude Installation empty to use Nimbalyst's bundled runtime.</p></figcaption></figure>

Claude plan login opens Terminal for the OAuth flow and may ask you to type `/login`; return to Settings and click **Refresh** when authentication finishes. Codex plan login opens the ChatGPT sign-in flow in your browser.

{% hint style="info" %}
Nimbalyst also offers separate CLI providers for users who deliberately want a locally installed command-line agent. Those providers have their own installation checks. See [AI Provider Setup](/setup-nimbalyst/ai-provider-setup-and-notifications).
{% endhint %}

## Start Working