Agent Extension Authoring Guide

A precise, step-by-step reference for agents writing Copilot CLI extensions programmatically.

Workflow

Step 1: Scaffold the extension

Use the extensions_manage tool with operation: "scaffold":

extensions_manage({ operation: "scaffold", name: "my-extension" })

This creates .github/extensions/my-extension/extension.mjs with a working skeleton. For user-scoped extensions (persist across all repos), add location: "user".

Step 2: Edit the extension file

Modify the generated extension.mjs using edit or create tools. The file must:

Be named extension.mjs (only .mjs is supported)
Use ES module syntax (import/export)
Call joinSession({ ... })

Step 3: Reload extensions

extensions_reload({})

This stops all running extensions and re-discovers/re-launches them. New tools are available immediately in the same turn (mid-turn refresh).

Step 4: Verify

extensions_manage({ operation: "list" })
extensions_manage({ operation: "inspect", name: "my-extension" })

Check that the extension loaded successfully and isn't marked as "failed".

File Structure

.github/extensions/<name>/extension.mjs

Discovery rules:

The CLI scans .github/extensions/ relative to the git root
It also scans the user's copilot config extensions directory
Only immediate subdirectories are checked (not recursive)
Each subdirectory must contain a file named extension.mjs
Project extensions shadow user extensions on name collision

Minimal Skeleton

import { joinSession } from "@github/copilot-sdk/extension";

await joinSession({
    tools: [], // Optional — custom tools
    hooks: {}, // Optional — lifecycle hooks
});

Registering Tools

tools: [
    {
        name: "tool_name", // Required. Must be globally unique across all extensions.
        description: "What it does", // Required. Shown to the agent in tool descriptions.
        parameters: {
            // Optional. JSON Schema for the arguments.
            type: "object",
            properties: {
                arg1: { type: "string", description: "..." },
            },
            required: ["arg1"],
        },
        handler: async (args, invocation) => {
            // args: parsed arguments matching the schema
            // invocation.sessionId: current session ID
            // invocation.toolCallId: unique call ID
            // invocation.toolName: this tool's name
            //
            // Return value: string or ToolResultObject
            //   string → treated as success
            //   { textResultForLlm, resultType } → structured result
            //     resultType: "success" | "failure" | "rejected" | "denied"
            return `Result: ${args.arg1}`;
        },
    },
];

Constraints:

Tool names must be unique across ALL loaded extensions. Collisions cause the second extension to fail to load.
Handler must return a string or { textResultForLlm: string, resultType?: string }.
Handler receives (args, invocation) — the second argument has sessionId, toolCallId, toolName.
Use session.log() to surface messages to the user. Don't use console.log() (stdout is reserved for JSON-RPC).

Registering Hooks

hooks: {
    onUserPromptSubmitted: async (input, invocation) => { ... },
    onPreToolUse: async (input, invocation) => { ... },
    onPostToolUse: async (input, invocation) => { ... },
    onPostToolUseFailure: async (input, invocation) => { ... },
    onSessionStart: async (input, invocation) => { ... },
    onSessionEnd: async (input, invocation) => { ... },
    onErrorOccurred: async (input, invocation) => { ... },
    onSubagentStart: async (input, invocation) => { ... },
    onSubagentStop: async (input, invocation) => { ... },
}

All hook inputs include sessionId, timestamp (Date) and workingDirectory. All handlers receive invocation: { sessionId: string } as the second argument. All handlers may return void/undefined (no-op) or an output object.