@aiderdesk/extensions

TypeScript type definitions and examples for building AiderDesk extensions.

Installation

npm install @aiderdesk/extensions
# or
yarn add @aiderdesk/extensions
# or
pnpm add @aiderdesk/extensions

Usage

Import both types and runtime values from a single entry point:

import type { Extension, ExtensionContext, ToolDefinition } from '@aiderdesk/extensions';
import { ToolApprovalState } from '@aiderdesk/extensions';
import { z } from 'zod';

export default class MyExtension implements Extension {
  async onLoad(context: ExtensionContext) {
    context.log('Extension loaded!', 'info');
    
    // Runtime values are available too
    const approval = ToolApprovalState.Always;
  }
}

Note: The package provides both TypeScript type definitions and runtime JavaScript values (like enum values) from the same entry point. You can use import type for type-only imports, or regular imports for runtime values.

Example Extensions

This directory contains example extensions demonstrating various capabilities of the AiderDesk extension system.

Documentation

For comprehensive documentation on creating and using extensions, see the Extensions documentation:

Extensions Overview - What extensions can do
Creating Extensions - How to build extensions
Installation Guide - Install extensions globally or per-project
API Reference - Complete API documentation
Events Reference - All available events
Examples Gallery - Browse all examples

Example Extensions

Extension	Description	Capabilities
chunkhound-on-semantic-search-tool/	Overrides `power---semantic_search` to use ChunkHound for better semantic understanding	`search`
chunkhound-search/	Provides `chunkhound-search` tool using ChunkHound for semantic code search	`search`, `tools`
context-autocompletion-words/	Automatically extracts symbols from context files and adds them to autocompletion	`context`
external-rules.ts	Includes rule files from Cursor, Claude Code, and Roo Code configurations	`context`
generate-tests.ts	Adds `/generate-tests` command to generate unit tests for files	`commands`
lsp/	LSP integration for automatic error detection after file edits and code intelligence tools (find references)	`tools`, `code-intelligence`
permission-gate.ts	Prompts for confirmation before running dangerous bash commands (`rm -rf`, `sudo`, `chmod/chown 777`)	`security`
pirate.ts	Adds a Pirate agent that speaks like a swashbuckling sea dog	`agents`, `example`
plan-mode.ts	Adds a Plan mode that enforces planning before coding	`modes`
plannotator/	Plan-based development workflow with planning mode and plan review utilizing plannotator.ai	`modes`, `tools`, `commands`, `workflow`
programmatic-tool-calls/	Execute JavaScript code in a sandbox with access to all tools as async functions	`tools`
protected-paths.ts	Blocks file operations on protected paths (`.env`, `.git/`, `node_modules/`)	`security`
providers-quota-extension/	Displays API quota information for Synthetic and Z.AI providers in the task status bar	`ui`
redact-secrets/	Redacts secret values from `.env*` files in file read results	`security`
rtk/	Transparently rewrites shell commands to RTK equivalents, reducing LLM token consumption by 60-90%	`optimization`, `commands`
sandbox/	OS-level sandboxing for bash commands using `@anthropic-ai/sandbox-runtime`	`security`
sound-notification.ts	Plays a "Jobs Done" sound when a prompt finishes	`notifications`
theme.ts	Adds `/theme` command to switch AiderDesk themes	`commands`
tree-sitter-repo-map/	Enhanced repository map using tree-sitter parsing with PageRank-based symbol ranking	`context`, `commands`
ultrathink.ts	Detects prompts like "ultrathink" / "think hard" and increases OpenAI/OpenAI-compatible reasoning effort (`xhigh` for `-max` models, otherwise `high`)	`optimization`
wakatime.ts	Tracks coding activity by sending heartbeats to WakaTime via wakatime-cli	`tracking`
ui-placement-demo.ts	Demonstrates all available UI component placement locations for extension development	`ui`, `example`
multi-model-run/	Run the same prompt across multiple models simultaneously with a UI selector	`ui`

Quick Start

1. Install an Extension

The easiest way to install extensions is using the CLI:

# Interactive selection - choose from all available extensions
npx @aiderdesk/extensions install

# Install a specific extension by ID
npx @aiderdesk/extensions install sound-notification

# Install to global extensions (available to all projects)
npx @aiderdesk/extensions install sound-notification --global

# Install from a URL (e.g., your own repository)
npx @aiderdesk/extensions install https://raw.githubusercontent.com/username/my-extension/main/my-extension.ts

Alternatively, manually copy extension files:

# Global extensions (available to all projects)
cp extensions/sound-notification.ts ~/.aider-desk/extensions/

# Project-specific extensions
cp extensions/sound-notification.ts .aider-desk/extensions/

2. Hot Reload

Extensions are automatically reloaded when files change. No restart needed!