Extension Creator
Create AiderDesk extensions that extend functionality through events, commands, tools, agents, and modes.
When to Use
Use this skill when:
- Building a new AiderDesk extension
- Creating extension commands, tools, or event handlers
- Implementing the Extension interface
- Setting up extension metadata and documentation
Do not use when:
- Simply activating an existing extension
- Making general code changes unrelated to extensions
- Running tests or builds
Rules
Rule: Choose installation target first
When: Starting extension creation
Then: Ask the user where to install the extension
If: Working inside the AiderDesk project (the current project is the aider-desk repository)
Then: Offer three options:
- Current Project — Install to
.aider-desk/extensions/in the current project (project-scoped) - Global — Install to
~/.aider-desk/extensions/(available in all projects) - In-Repo — Create inside
packages/extensions/extensions/(ships with AiderDesk app)
If: Working outside the AiderDesk project
Then: Offer two options:
- Current Project — Install to
.aider-desk/extensions/in the current project (project-scoped) - Global — Install to
~/.aider-desk/extensions/(available in all projects)
Must: Wait for user's choice before proceeding. The chosen target determines the entire workflow.
Reference: references/install-targets.md for full details on each target.
Rule: Follow the correct flow for the chosen target
When: User has chosen an installation target
If: Target is Current Project or Global
Then: Follow the Project / Global Flow:
- Determine extension type (single-file or folder)
- Create extension file(s) in the target directory (
.aider-desk/extensions/or~/.aider-desk/extensions/) - Implement Extension interface methods
- Export metadata and default class
- Verify the extension loads (auto-discovered, no registry needed)
If: Target is In-Repo
Then: Follow the In-Repo Flow:
- Determine extension type (single-file or folder)
- Create extension file(s) in
packages/extensions/extensions/ - Implement Extension interface methods
- Export metadata and default class
- Register in
packages/extensions/extensions.json - Document in
docs-site/docs/extensions/extensions-gallery.md - Install npm dependencies if folder extension
- Verify with type checking
Rule: Determine extension type
When: Creating extension files (after target is chosen)
Then: Check if extension needs npm dependencies or multiple files
If: Extension needs dependencies or multiple files
Then: Create folder extension
If: Extension is simple with no dependencies
Then: Create single-file extension
Rule: Implement Extension interface
When: Creating extension file
Then: Implement required methods from Extension interface
Must: Define static metadata property on the class with name, version, description, author, capabilities
Must: Export class as default (e.g., export default class MyExtension implements Extension)
Never: Use @/ imports in extension files
Rule: Integrate custom providers with the host contract
When: Registering an LLM provider, especially one wrapping an external coding-agent SDK/server
Then: Read external-agent-providers.md and the current ExtensionProviderStrategy in packages/common/src/extensions.ts before implementation
Must: Keep the complete positional createLlm contract: profile, model, settings, projectDir, toolSet?, systemPrompt?, providerMetadata?, tlsRegistrar?, sessionId?, approveTool?. Providers can omit unused trailing arguments.
Must: Use the optional ProviderToolApprovalHandler for native-tool decisions, mapping tool names/inputs to Power schemas. Reject native execution if the callback is absent; do not replace the shared autonomy, approval settings, bash patterns and veto hooks with unconditional questions.
Must: Keep one execution owner, preserve original UI tool-result shapes, and deduplicate continuation replays. Separate persistent native sessions from transient processes/bridges, and scope parent/subagent conversations independently.
Must: Tell the user when the extension requires core changes, document native execution limitations, and verify against the matching core build. Extension reload or renderer refresh cannot update an older main process.
Rule: Add UI components when needed
When: Extension needs to display UI elements in task page placements
Then: Implement getUIComponents() method
Must: Return array of UIComponentDefinition objects with id, placement, jsx
Must: Define components as JSX strings or load from .jsx files
If: Component needs data, set loadData: true and implement getUIExtensionData()
If: Component triggers actions, implement executeUIExtensionAction()
Rule: Keep extension model catalogs and favorites independent
When: Extension UI uses ui.ModelSelector with a custom catalog or extension-owned favorites
Then: Read ModelSelector props and preference semantics and use the public ModelSelectorProps contract
Must: Pass models to restrict the catalog (including displayed favorites); pass providers only when overriding core provider labels and disabled-state lookup
Must: For extension-owned favorites, supply preferredModels and handle onPreferredModelsChange(next) by updating extension state and persisting independently through an extension action. Initialize preferredModels to [] while loading so selection cannot accidentally update core favorites.
Note: Supplied preferences without a callback are read-only. Out-of-catalog IDs are hidden, not deleted from saved preferences. Omitting preferredModels retains core favorite persistence; a callback alone does not enable controlled mode. skipPreferredModelsUpdate suppresses selection-driven updates, not explicit removal.
Rule: Use external libraries when UI components need npm packages
When: Extension UI components need third-party npm packages (charts, calendars, kanban boards, etc.)
Then: Implement getUIComponentsLibraries() returning a Record<string, string> mapping camelCase keys to npm package specs
Must: Access loaded libraries in JSX via props.libraries.<key>
Must: Handle the loading state — libraries are async and props.libraries.<key> will be undefined on first render
Never: Bundle or import React in library specs — AiderDesk's React instance is externalized automatically
Reference: external-libraries.md for full details, loading patterns, and examples
Rule: Add config component for extension settings
When: Extension needs user-configurable settings (shown in gear icon dialog)
Then: Implement three methods: getConfigComponent(), getConfigData(), saveConfigData()
Must: Return JSX string from getConfigComponent() — use external .jsx file for components > 20 lines
Must: Load/merge defaults in getConfigData(), persist merged data in saveConfigData()
Must: Store config file in extension directory via join(__dirname, 'config.json')
Must: Use ui.* components (ui.Input, ui.Checkbox, etc.) instead of raw HTML elements
Should: Avoid inner state (useState/useEffect) for simple form fields — read directly from config prop, call updateConfig on change. Only use local state for derived values or transient UI state.
Never: Use 'extension-settings' placement — it was removed; use the dedicated config API instead
Rule: Validate UI components after creation
When: Any UI or config component (.jsx file) was created or modified
Then: Run the validator script and fix all reported issues
Must: Run node <skill-dir>/assets/scripts/validate-extension-ui.mjs <file-or-dir> where <skill-dir> is this skill's directory
Must: Ensure every file passes — exit code 0, all lines say PASS
Must: Fix all [SYNTAX] issues (the component would crash at render time) and [TYPE] issues (typos in props, React API, or ui.* component names)
If: A file uses config-style props (config, updateConfig) but is not named Config*.jsx
Then: Add --type=config (conversely, --type=ui forces UI-component props)
Note: The script needs sucrase, typescript, and @types/react resolvable (they are, when the aider-desk repo is available); otherwise it degrades to whatever checks are possible and says so in a warning
Rule: Update registry and docs (In-Repo only)
When: Target is In-Repo and extension file is created
Then: Add entry to packages/extensions/extensions.json
Must: Include id, name, description, file or folder path, type, capabilities
Must: Set hasDependencies: true for folder extensions
Then: Add entry to docs-site/docs/extensions/extensions-gallery.md table
Must: Include extension name, description, capabilities, and type
When: Target is Project or Global
Then: Do NOT modify extensions.json or extensions-gallery.md — these are only for built-in extensions
Rule: Use proper TypeScript config for folders
When: Creating folder extension
Then: Include tsconfig.json with module: ES2020+
Must: Include package.json with name, version, main, dependencies
Rule: Store config in extension directory
When: Extension needs persistent config
Then: Store config files in extension directory
Never: Store user-editable config outside the extension directory
Note: Native session databases and runtime state are not user-editable config. They may use a separate documented, access-restricted extension-owned location; see external-agent-providers.md. Temporary process cleanup must not erase sessions intended for reuse.
Process Overview
For Project / Global targets:
- Ask user: Current Project or Global?
- Determine extension type (single-file or folder)
- Create extension file or directory structure in target dir
- Implement Extension interface methods
- Export metadata and default class
- Verify extension loads (auto-discovered)
Between steps 3 and 5:
- If extension needs config storage, create config.ts (or use inline getConfigData/saveConfigData)
- If extension has a settings UI (config component), create ConfigComponent.jsx and implement the three config methods
- If extension needs logging, create logger.ts
- If extension needs constants, create constants.ts
- If extension has placement-based UI components, create .jsx files for components (recommended for components > 20 lines)
After any .jsx file is created:
- Validate it:
node <skill-dir>/assets/scripts/validate-extension-ui.mjs <extension-dir>— all files must pass
For In-Repo target:
- Confirm user wants In-Repo (only available in aider-desk project)
- Determine extension type (single-file or folder)
- Create extension file or directory structure in
packages/extensions/extensions/ - Implement Extension interface methods
- Export metadata and default class
- Register in
packages/extensions/extensions.json - Document in
docs-site/docs/extensions/extensions-gallery.md - Run
npm installinpackages/extensions/(folder extensions) - Verify with type checking
Between steps 3 and 5:
- Same optional files as Project/Global flow above
After any .jsx file is created:
- Validate it:
node <skill-dir>/assets/scripts/validate-extension-ui.mjs <extension-dir>— all files must pass
Preconditions
Before using this skill, verify:
- Installation target has been chosen by the user
- Extension purpose and required capabilities are clear
- Extension type (single-file or folder) is determined
- Extension interface and types are understood
IMPORTANT: The reference files below are comprehensive but may lag behind the latest code. For the authoritative and complete API, always refer to these source files:
- Types source: packages/common/src/extensions.ts — Extension interface, all contexts (ExtensionContext, TaskContext, ProjectContext), event payloads, UI component definitions
- Context message types: packages/common/src/types/context.ts — ContextMessage, ContextFile, message part types
- Task/common types: packages/common/src/types/common.ts — TaskData, Model, AgentProfile, CreateTaskParams, etc.
When you need a method or type that's not in the reference docs, fetch the raw source first before guessing.
Built-in extension examples are available at:
- Online extensions gallery — documented overview
- Source code for each built-in extension is in the AiderDesk repo at
packages/extensions/extensions/[extension-name]/— browse these for real-world patterns
Reference docs
- references/install-targets.md for target options
- references/event-types.md for event types
- references/command-definition.md for command structure
Postconditions
After completing this skill, verify:
- Extension implements Extension interface correctly
- Static
metadataproperty on the class includes all required fields (name, version) - Default export is the extension class
- No
@/imports used - All UI/config .jsx components pass
assets/scripts/validate-extension-ui.mjs - If In-Repo: extensions.json updated correctly
- If In-Repo: docs-site/docs/extensions/extensions-gallery.md updated
- If In-Repo: Type checking passes
- Extension loads without errors
- Extension appears in extensions list
- Extension capabilities work as expected
- If provider: Current signatures and host compatibility checked; native approvals, streaming/result shapes, session continuity, subagent isolation and cleanup verified as applicable
- If core changes are required: README and user handoff explicitly require the matching core build and main-process restart
Success metrics:
- Extension loads without errors
- Extension appears in extensions list
- Extension capabilities work as expected
Common Situations
Situation: Extension needs to handle events
Pattern:
- When: Extension needs to modify agent behavior
- Then: Implement event handler methods (onAgentStarted, onToolCalled, etc.)
- Return: Partial event object to modify behavior
Situation: Extension needs to create subtasks and coordinate between them
Pattern:
- Create:
const newTask = await projectContext.createTask({ parentId: currentTaskId, name: 'Subtask' }) - Access another task:
const subtaskContext = projectContext.getTask(newTask.id) - Execute commands in subtask:
await subtaskContext?.runCustomCommand('scope:start') - Read subtask conversation:
const messages = await subtaskContext?.getContextMessages() - List all tasks:
const allTasks = await projectContext.getTasks() - Reload tasks from disk after external task-folder changes:
const allTasks = await projectContext.reloadTasks() - Fork at specific message:
await projectContext.forkTask(taskId, messageId) - Duplicate a task:
await projectContext.duplicateTask(taskId) - Delete a task:
await projectContext.deleteTask(taskId)
Situation: Extension needs to make direct LLM calls without the full agent loop
Pattern:
- Get model ID:
const profile = await taskContext.getTaskAgentProfile(); const modelId = profile ? \${profile.provider}/${profile.model}` : 'openai/gpt-4o'` - Generate text:
const result = await taskContext.generateText(modelId, 'You are a helpful assistant', 'Summarize this code') - Generate structured data:
const result = await taskContext.generateObject(modelId, systemPrompt, prompt, z.object({ category: z.string() }))
Situation: Extension needs to read conversation history
Pattern:
- Get messages:
const messages = await taskContext.getContextMessages() - Extract text: ContextMessage content can be a string or an array of parts. For simple text extraction:
function extractText(content: ContextMessage['content']): string { if (typeof content === 'string') return content; if (Array.isArray(content)) { return content .filter((part): part is TextPart => part.type === 'text') .map(part => part.text) .join('\n'); } return ''; } - Reference: context.ts for full ContextMessage type
Situation: Extension needs to run shell commands
Pattern: Node.js built-in modules (fs, path, child_process, os, etc.) are available in extensions.
- Synchronous:
import { execSync } from 'node:child_process'; const output = execSync('git status', { encoding: 'utf-8' }); - Asynchronous:
import { exec } from 'node:child_process'; import { promisify } from 'node:util'; const execAsync = promisify(exec); - File operations:
import { readFileSync, writeFileSync } from 'node:fs'; import { join } from 'node:path';
Situation: Extension needs to manage todos
Pattern:
- Get todos:
const todos = await taskContext.getTodos() - Add todo:
const todos = await taskContext.addTodo('Implement feature X') - Update todo:
const todos = await taskContext.updateTodo('Implement feature X', { completed: true }) - Delete todo:
const todos = await taskContext.deleteTodo('Implement feature X') - Replace all:
await taskContext.setTodos([{ name: 'Task 1', completed: false }])
Situation: Extension needs to register commands
Pattern:
- When: Extension provides slash commands
- Then: Implement getCommands() method
- Return: Array of CommandDefinition objects
Situation: Extension needs to add UI components
Pattern:
- When: Extension needs to display information in UI
- Then: Implement getUIComponents() method
- Return: Array of UIComponentDefinition objects
- Use: JSX strings or external .jsx files
- Built-ins: Use
props.ui.CodeBlockfor syntax-highlighted code, JSON, and diffs; useprops.ui.ExpandableMessageBlockfor collapsible tool-style message renderers - Load data: Implement getUIExtensionData() if component needs data
- Handle actions: Implement executeUIExtensionAction() for user interactions
Situation: Extension needs to log messages
Pattern:
- If: Debug/internal logging (developer diagnostics, not shown to users)
- Then: Use
context.log(message, type)— logs to backend console only - If: User-visible output (showing results, status, timing info in the chat)
- Then: Use
context.getTaskContext()?.addLogMessage(level, message)— displays in task's chat UI - When ambiguous: If the user says "log", "show", "display", or "report" something, default to
addLogMessage(user-visible). Usecontext.logonly for internal diagnostics. - Note:
context.logis always available;getTaskContext()returnsnulloutside a task, so always use optional chaining (?.)
Situation: Extension needs to manage resource cleanup (timers, watchers, child processes)
Pattern:
- When: Extension creates resources in
onLoad,onProjectStarted, or event handlers that need cleanup - Then: Use
context.addDisposable()to co-locate setup and cleanup logic - Setup runs immediately; if it returns a function, that function is called on unload (LIFO order). The cleanup may be sync or async (
Promise) — async cleanups are awaited during unload - Disposers run before
onUnloadis called, so both patterns work together - Example:
async onLoad(context: ExtensionContext) { // Setup and cleanup are co-located — no need to track in onUnload context.addDisposable(() => { const timer = setInterval(() => doWork(), 1000); return () => clearInterval(timer); }); } // onUnload still works as a fallback for anything not registered via addDisposable - If setup returns
void, no cleanup is registered — useful for fire-and-forget side effects
Situation: Extension needs to store or retrieve memories
Pattern:
- When: Extension wants to persist knowledge across tasks (user preferences, code patterns, architectural decisions)
- Then: Use
context.getMemoryContext()to access the Memory API - Check: Always call
isMemoryEnabled()before using memory operations - Store:
memory.storeMemory(scopeId, taskId, type, content)— returns the created memory ID - Retrieve:
memory.retrieveMemories(scopeId, query, limit?)— returns semantically similar memories - Types: Use
MemoryEntryTypeenum ('task', 'user-preference', 'code-pattern') - Scope: use the project directory (
context.getProjectDir()) for project-scoped memories, oragent-profile:{profileId}to share memories across projects for agents with memory isolation (useAgentMemoryScope) enabled - Note: Works outside of project/task scope — pass empty strings for
scopeId/taskIdif not applicable - Example:
async onAgentFinished(event: AgentFinishedEvent, context: ExtensionContext) { const memory = context.getMemoryContext(); if (!memory.isMemoryEnabled()) return; const scopeId = context.getProjectDir(); const taskId = context.getTaskContext()?.data.id ?? ''; await memory.storeMemory(scopeId, taskId, 'code-pattern', 'Always use clsx for conditional classes'); const memories = await memory.retrieveMemories(scopeId, 'React class naming'); context.log(`Found ${memories.length} relevant memories`, 'info'); }
Situation: Extension UI components need third-party npm packages
Pattern:
- When: Extension needs a library like a chart, calendar, kanban board, etc. that isn't in the built-in
uiprop - Then: Implement
getUIComponentsLibraries()returning{ key: 'package@^version' } - Access: Use
props.libraries.<key>in JSX — check forundefined(async loading) - Example:
getUIComponentsLibraries() { return { chart: 'recharts@^2.12.0' } } - Reference: external-libraries.md
Situation: Extension needs to customize message rendering
Pattern:
- When: Extension wants to replace how messages (user, assistant, tool, log, etc.) are displayed
- Then: Use the
task-messageplacement with amessageFilterto specify which messages to handle - Must: Set
messageFilter.typesto the message types to match (e.g.'user','response','assistant-group','tool','log','loading') - Must: For tool-specific filters, set
messageFilter.serverNameand/ormessageFilter.toolName - Props: Component receives
messageprop — forassistant-grouptype, accessmessage.responseMessageandmessage.toolMessages - Style: Prefer
props.ui.ExpandableMessageBlockfor the standard collapsible tool-message layout andprops.ui.CodeBlockfor code or structured results - Reference: ui-components.md for full details,
MessageFiltertype, and JSX examples
Situation: Extension needs custom actions in the message context menu
Pattern:
- When: Extension wants to add extra actions to a message's vertical-dots dropdown menu (e.g. "undo changes")
- Then: Use the
task-message-bar-menuplacement — components render as menu items below the built-in actions, separated by a divider - Props: Component receives
messageprop for the specific message - Must: Style JSX as a menu item (flex row,
hover:bg-bg-tertiary,text-2xs) to match built-in menu entries - Note: The menu button appears when there are built-in menu actions or components registered for this placement; use
task-message-barfor inline actions shown directly in the bar instead - Reference: ui-components.md
Situation: Extension needs a floating panel
Pattern:
- When: Extension needs a draggable, resizable panel (dashboard, inspector, toggle panel)
- Then: Use the
floatingplacement and setnamefor the panel title - Must: Set
nameonUIComponentDefinition— used as the floating panel title bar text - Must: Use
loadData: true+getUIExtensionData()for panel data; implementexecuteUIExtensionAction()for actions - Must: Use
context.triggerUIDataRefresh(componentId)to refresh panel data,context.triggerUIComponentsReload()to re-register components after state changes - Reference: ui-components.md for full details, including toggle panel pattern
Situation: Extension needs config storage
Pattern:
- Check: Extension needs persistent settings
- If yes: Create config.ts with loadConfig and saveConfig functions
- Store: Config files in extension directory
Situation: Extension needs a settings UI (config component)
Pattern:
- When: Extension has user-configurable options that should appear in the Settings dialog
- Then: Implement
getConfigComponent(),getConfigData(),saveConfigData()methods - JSX: Return a
.jsxfile content viareadFileSync(join(__dirname, './ConfigComponent.jsx'), 'utf-8') - Props: Component receives
{ config, updateConfig, ui, icons, models, providers, ... } - Flow: Dialog opens → loads data via getConfigData → renders JSX with props → user edits → Save calls saveConfigData
- Reference: config-components.md for full guide and examples
References
Target Selection
- install-targets.md - All three installation targets, when to use each, key differences
Flows
- project-global-flow.md - Step-by-step for Project and Global installations
- in-repo-flow.md - Step-by-step for In-Repo (packages/extensions/) installations
Technical Reference (all targets)
- packages/common/src/extensions.ts - Extension types and interfaces
- external-agent-providers.md - Custom provider signatures, native approvals, MCP execution ownership, streaming, persistent sessions and host compatibility
- extension-interface.md - Full Extension interface, ExtensionContext, TaskContext, ProjectContext, MemoryContext, and all supporting types
- extension-types.md - Single-file vs folder extensions, examples, extensions.json format
- event-types.md - All event types, payloads, and extension method mappings
- command-definition.md - Command structure
- ui-components.md - UI component system, placements, and available components
- external-libraries.md - Loading third-party npm libraries in UI components (getUIComponentsLibraries)
- config-components.md - Config component API (settings UI), methods, JSX format, and patterns
- examples-gallery.md - Real extension examples
Assets
- scripts/validate-extension-ui.mjs - UI component validator (syntax + type check)
- templates/single-file.ts.template - Single-file template
- templates/folder-extension/ - Folder template (basic)
- templates/folder-extension-with-config/index.ts.template - Folder template with config component API
- templates/ui-component.ts.template - UI component inline template
- templates/ui-component-external.ts.template - UI component with external JSX
- templates/Component.jsx.template - Placement-based JSX component template
- templates/ConfigComponent.jsx.template - Config/settings JSX component template