SKILL.md · 24000
on | Type | Default | Description |
|--------|------|---------|-------------|
| cliPath | string | Auto-detected | Path to Copilot CLI executable |
| cliUrl | string | — | URL of external CLI server |
| githubToken | string | — | GitHub token for auth |
| useLoggedInUser | boolean | true | Use stored CLI credentials |
| logLevel | string | "none" | "none" | "error" | "warning" | "info" | "debug" |
| autoRestart | boolean | true | Auto-restart CLI on crash |
| useStdio | boolean | true | Use stdio transport |
Session Configuration
| Option | Type | Description |
|--------|------|-------------|
| model | string | Model to use (e.g., "gpt-4.1", "claude-sonnet-4") |
| sessionId | string | Custom ID for resumable sessions |
| streaming | boolean | Enable streaming responses |
| tools | Tool[] | Custom tools |
| mcpServers | object | MCP server configurations |
| hooks | object | Session hooks |
| provider | object | BYOK provider config |
| customAgents | object[] | Custom agent definitions |
| systemMessage | object | System message override |
| skillDirectories | string[] | Directories to load skills from |
| disabledSkills | string[] | Skills to disable |
| reasoningEffort | string | Reasoning effort level |
| availableTools | string[] | Restrict available tools |
| excludedTools | string[] | Exclude specific tools |
| infiniteSessions | object | Auto-compaction config |
| workingDirectory | string | Working directory |
SDK vs CLI Feature Comparison
✅ Available in SDK
Session management, messaging (send/sendAndWait/abort), message history (getMessages), custom tools, tool permission hooks, MCP servers (local + HTTP), streaming, model selection, BYOK providers, custom agents, system message, skills, infinite sessions, permission handlers, 40+ event types.
❌ CLI-Only Features
Session export (--share), slash commands, interactive UI, terminal rendering, YOLO mode, login/logout flows, /compact (use infiniteSessions instead), /usage (use usage events), /review, /delegate.
Workarounds:
- Session export → Collect events manually with
session.on()+session.getMessages() - Permission control → Use
onPermissionRequesthandler instead of--allow-all-paths - Context compaction → Use
infiniteSessionsconfig instead of/compact
Debugging
Enable debug logging:
const client = new CopilotClient({ logLevel: "debug" });
Custom log directory:
const client = new CopilotClient({ cliArgs: ["--log-dir", "/path/to/logs"] });
Common Issues
| Issue | Cause | Solution |
|-------|-------|----------|
| CLI not found | CLI not installed or not in PATH | Install CLI or set cliPath |
| Not authenticated | No valid credentials | Run copilot auth login or provide githubToken |
| Session not found | Using session after destroy() | Check listSessions() for valid IDs |
| Connection refused | CLI process crashed | Enable autoRestart: true, check port conflicts |
| MCP tools missing | Server init failure or tools not enabled | Set tools: ["*"], test server independently |
Connection State
console.log("State:", client.getState()); // "connected" after start()
client.on("stateChange", (state) => console.log("Changed to:", state));
Key API Summary
| Language | Client | Session Create | Send | Resume | Stop |
|----------|--------|---------------|------|--------|------|
| Node.js | new CopilotClient() | client.createSession() | session.sendAndWait() | client.resumeSession() | client.stop() |
| Python | CopilotClient() | client.create_session() | session.send_and_wait() | client.resume_session() | client.stop() |
| Go | copilot.NewClient(nil) | client.CreateSession() | session.SendAndWait() | client.ResumeSession() | client.Stop() |
| .NET | new CopilotClient() | client.CreateSessionAsync() | session.SendAndWaitAsync() | client.ResumeSessionAsync() | client.DisposeAsync() |