copilot_sdk_dart 0.1.0

Community-maintained Dart SDK for the GitHub Copilot CLI agent runtime. Unofficial and not affiliated with GitHub or Microsoft.

Copilot SDK for Dart

A community-maintained Dart SDK for the GitHub Copilot CLI SDK. Enables programmatic access to Copilot agent capabilities via JSON-RPC 2.0 over stdio, TCP, or WebSocket.

This is an unofficial project and is not affiliated with, endorsed by, or sponsored by GitHub, Inc. or Microsoft Corporation.

Features

• Full protocol support — All JSON-RPC 2.0 methods from the Copilot CLI (protocol v2)
• Session management — Create, resume, list, and destroy sessions
• Event streaming — 25+ typed event classes with Dart 3 exhaustive pattern matching
• Custom tools — Register and handle custom tools with typed results
• Hooks — 6 lifecycle hooks (preToolUse, postToolUse, userPromptSubmitted, sessionStart, sessionEnd, errorOccurred)
• Permission & user input handlers — Approve/deny tool permissions, handle user input requests
• Pluggable transports — stdio (desktop), TCP (desktop), WebSocket (web via bridge)
• Idiomatic Dart — Sealed classes, Streams, Futures, strong typing throughout

Prerequisites

• Dart SDK ^3.6.0
• Copilot CLI installed
• Authenticated: copilot auth login

Quick Start

import 'package:copilot_sdk_dart/copilot_sdk_io.dart';

Future<void> main() async {
  // Create transport & client
  final transport = StdioTransport(
    executable: 'copilot',
    arguments: ['--headless', '--stdio', '--no-auto-update'],
  );
  await transport.start();

  final client = CopilotClient(
    options: const CopilotClientOptions(),
    transport: transport,
  );
  await client.start();

  // Create a session
  final session = await client.createSession(
    config: SessionConfig(
      onPermissionRequest: approveAllPermissions,
    ),
  );

  // Listen for events with exhaustive pattern matching
  session.on((event) {
    switch (event) {
      case AssistantMessageEvent(:final content):
        print(content);
      case SessionIdleEvent():
        print('--- Done ---');
      default:
        break;
    }
  });

  // Send a message and wait for the reply
  final reply = await session.sendAndWait('What is 2 + 2?');
  print('Reply: ${reply?.content}');

  // Cleanup
  await session.destroy();
  await client.stop();
}

Interactive Example App

For a full app-style sample (interactive chat + one-shot smoke mode), run:

# Interactive REPL chat
dart run example/chat_app.dart

# One-shot prompt (good for smoke testing)
dart run example/chat_app.dart --prompt "Explain JSON-RPC in one sentence."

# Optional model override
dart run example/chat_app.dart --model claude-sonnet-4.5

# Override CLI executable/args (for custom SDK server runtime)
dart run example/chat_app.dart --cli-path /path/to/copilot --cli-arg --headless --cli-arg --stdio --cli-arg --no-auto-update

The app validates auth status, creates a session, handles events, sends prompts, prints assistant replies, and performs graceful cleanup.

If startup times out on ping, your executable likely is not exposing the Copilot SDK JSON-RPC server methods (ping, session.create, etc.). Provide a compatible runtime via --cli-path / --cli-arg. You can also set COPILOT_CLI_PATH to point to a compatible runtime. When using the launcher CLI, include --no-auto-update to avoid silent runtime version drift.

Architecture

┌─────────────────────┐       JSON-RPC 2.0        ┌──────────────┐
│   CopilotClient     │ ◄─── Content-Length ────► │ Copilot CLI  │
│   CopilotSession    │       framed stdio/TCP    │ (--headless) │
│   Event handlers    │                           │              │
│   Tool handlers     │  Client → Server:         │  LLM proxy   │
│   Permission/Input  │   ping, session.create,   │  with tools  │
│   Hooks             │   session.send, ...       │              │
│                     │                           │              │
│                     │  Server → Client:         │              │
│                     │   session.event,           │              │
│                     │   toolCall.request, ...    │              │
└─────────────────────┘                           └──────────────┘

Transport Layer

Transport	Platform	Use Case
StdioTransport	Desktop/Server	Spawns copilot --headless --stdio process
TcpTransport	Desktop/Server	Connects to running CLI server
WebSocketTransport	Web	Connects to WebSocket bridge server

Imports

// Transport-agnostic (types, client, session)
import 'package:copilot_sdk_dart/copilot_sdk.dart';

// Desktop/Server (includes stdio & TCP transports)
import 'package:copilot_sdk_dart/copilot_sdk_io.dart';

// Web (includes WebSocket transport)
import 'package:copilot_sdk_dart/copilot_sdk_web.dart';

Custom Tools

final tool = Tool(
  name: 'get_weather',
  description: 'Get weather for a city',
  parameters: {
    'type': 'object',
    'properties': {
      'city': {'type': 'string', 'description': 'City name'},
    },
    'required': ['city'],
  },
  handler: (args, invocation) async {
    final city = (args as Map<String, dynamic>)['city'] as String;
    return ToolResult.success('Weather in $city: Sunny, 72°F');
  },
);

final session = await client.createSession(
  config: SessionConfig(
    tools: [tool],
    onPermissionRequest: approveAllPermissions,
  ),
);

Event Types

All 25+ event types are modeled as Dart 3 sealed classes for exhaustive pattern matching:

Category	Events
Session lifecycle	SessionStartEvent, SessionResumeEvent, SessionIdleEvent, SessionShutdownEvent, SessionErrorEvent
Session state	SessionTitleChangedEvent, SessionModelChangeEvent, SessionModeChangedEvent, SessionPlanChangedEvent, SessionTruncationEvent
Messages	AssistantMessageEvent, AssistantThinkingEvent, UserMessageEvent, SystemMessageEvent
Tools	ToolCallEvent, ToolExecutionStartEvent, ToolExecutionPartialResultEvent, ToolExecutionCompleteEvent
Skills & agents	SkillInvokedEvent, SubagentStartedEvent, SubagentCompletedEvent, SubagentFailedEvent, SubagentSelectedEvent
Hooks	HookStartEvent, HookEndEvent
Fallback	UnknownEvent (for forward compatibility)

Session API

// Send message
await session.send('Hello');

// Send and wait for complete reply
final reply = await session.sendAndWait('Explain X', timeout: Duration(minutes: 2));

// Model management
final model = await session.getCurrentModel();
await session.switchModel('claude-sonnet-4.5');

// Mode management
await session.setMode(AgentMode.autopilot);

// Plan management
final plan = await session.readPlan();
await session.updatePlan('Updated plan content');

// Workspace
final files = await session.listWorkspaceFiles();
final content = await session.readWorkspaceFile('src/main.dart');

// Fleet mode (parallel sub-agents)
await session.startFleet();

// Lifecycle
await session.abort();
await session.destroy();

Client API

// Server info
final status = await client.getStatus();
final auth = await client.getAuthStatus();

// Discovery
final models = await client.listModels();
final tools = await client.listTools();
final quota = await client.getAccountQuota();

// Session management
final sessions = await client.listSessions();
await client.deleteSession('session-id');

Web Support

The Copilot CLI only supports stdio and TCP. For web, use a WebSocket bridge server:

import 'package:copilot_sdk_dart/copilot_sdk_web.dart';

final transport = WebSocketTransport(
  uri: Uri.parse('ws://localhost:8765'),
);
await transport.connect();

final client = CopilotClient(
  options: const CopilotClientOptions(),
  transport: transport,
);

The bridge server (not included) relays WebSocket ↔ CLI stdio. Any language can implement it.

License

MIT — see LICENSE.

Legal and Trademark Notice

• The upstream github/copilot-sdk project is MIT licensed, which permits creating and publishing compatible ports.
• "GitHub" and "GitHub Copilot" are trademarks of GitHub, Inc.; "Microsoft" is a trademark of Microsoft Corporation.
• Trademarked names are used only to describe compatibility and do not imply affiliation or endorsement.