SDK and CLI compatibility

SDK GitHub Copilot communicates with CLI de GitHub Copilot via JSON-RPC protocol. Features must be explicitly exposed through this protocol to be available in the SDK. Many interactive CLI features are terminal-specific and not available programmatically.

Feature comparison

Available in SDK

Not available in SDK (CLI-only)

Workarounds

Session export

The --share option is not available via SDK. To work around this:

• Collect events manually: Subscribe to session events and build your own export:

  TypeScript

  const events: SessionEvent[] = [];
  session.on((event) => events.push(event));
  // ... after conversation ...
  const messages = await session.getMessages();
  // Format as markdown yourself
  

• Use the CLI directly for one-off exports.

Permission control

The SDK uses a deny-by-default permission model. All permission requests (file writes, shell commands, URL fetches, and others) are denied unless your app provides an onPermissionRequest handler.

Instead of --allow-all-paths or --yolo, use the permission handler:

const session = await client.createSession({
  onPermissionRequest: approveAll,
});

const session = await client.createSession({
  onPermissionRequest: approveAll,
});

Token usage tracking

Instead of /usage, subscribe to usage events:

session.on("assistant.usage", (event) => {
  console.log("Tokens used:", {
    input: event.data.inputTokens,
    output: event.data.outputTokens,
  });
});

session.on("assistant.usage", (event) => {
  console.log("Tokens used:", {
    input: event.data.inputTokens,
    output: event.data.outputTokens,
  });
});

Context compaction

Instead of /compact, configure automatic compaction or trigger it manually:

// Automatic compaction via config
const session = await client.createSession({
  infiniteSessions: {
    enabled: true,
    backgroundCompactionThreshold: 0.80,  // Start background compaction at 80% context utilization
    bufferExhaustionThreshold: 0.95,      // Block and compact at 95% context utilization
  },
});

// Manual compaction (experimental)
const result = await session.rpc.compaction.compact();
console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);

// Automatic compaction via config
const session = await client.createSession({
  infiniteSessions: {
    enabled: true,
    backgroundCompactionThreshold: 0.80,  // Start background compaction at 80% context utilization
    bufferExhaustionThreshold: 0.95,      // Block and compact at 95% context utilization
  },
});

// Manual compaction (experimental)
const result = await session.rpc.compaction.compact();
console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);

Plan management

Read and write session plans programmatically:

// Read the current plan
const plan = await session.rpc.plan.read();
if (plan.exists) {
  console.log(plan.content);
}

// Update the plan
await session.rpc.plan.update({ content: "# My Plan\n- Step 1\n- Step 2" });

// Delete the plan
await session.rpc.plan.delete();

// Read the current plan
const plan = await session.rpc.plan.read();
if (plan.exists) {
  console.log(plan.content);
}

// Update the plan
await session.rpc.plan.update({ content: "# My Plan\n- Step 1\n- Step 2" });

// Delete the plan
await session.rpc.plan.delete();

Message steering

Inject a message into the current LLM turn without aborting:

// Steer the agent mid-turn
await session.send({ prompt: "Focus on error handling first", mode: "immediate" });

// Default: enqueue for next turn
await session.send({ prompt: "Next, add tests" });

// Steer the agent mid-turn
await session.send({ prompt: "Focus on error handling first", mode: "immediate" });

// Default: enqueue for next turn
await session.send({ prompt: "Next, add tests" });

Protocol limitations

The SDK can only access features exposed through the CLI's JSON-RPC protocol. If you need a CLI feature that's not available:

• Check for alternatives: Many features have SDK equivalents (see Workarounds above).
• Use the CLI directly: For one-off operations, invoke the CLI.
• Request the feature: Open an issue in the github/copilot-sdk repository to request protocol support.

Version compatibility

The SDK negotiates protocol versions with the CLI at startup. The SDK supports protocol versions 2 through 3. When connecting to a v2 CLI server, the SDK automatically adapts tool.call and permission.request messages to the v3 event model—no code changes required.

You can check versions at runtime:

const status = await client.getStatus();
console.log("Protocol version:", status.protocolVersion);

const status = await client.getStatus();
console.log("Protocol version:", status.protocolVersion);