GitHub Copilot
The GitHub Copilot provider (providers/copilot) implements llm.Provider on top of the official GitHub Copilot Go SDK (github.com/github/copilot-sdk/go), adding dynamic model discovery (llm.ModelLister), quota inspection (llm.QuotaProvider), and idle notifications / sync-on-write (llm.IdleMessageNotifier, *llm.OutOfSyncError).
It lets you run standard Loom graphs (Agent -> Tools -> Agent loops, model.BindTools, checkpoints, structured output, thinking effort, and compaction) backed by your GitHub Copilot subscription or a BYOK endpoint (OpenAI, Azure, Anthropic, or Ollama).
Note. See limitations for details about parameter support and the differences between Copilot and Claude Code.
1. Prerequisites & Authentication
Ensure the copilot CLI is installed (on PATH, via COPILOT_CLI_PATH, or passed with WithCLIPath) and authenticated:
copilot login# or set a fine-grained PAT / OAuth token:export COPILOT_GITHUB_TOKEN='...'Caution. GitHub Copilot does not support classic Personal Access Tokens (
ghp_...). IfGITHUB_TOKENcontains a classicghp_token, either unset it before runningcopilot login/go run ./examples/copilotor pass a fine-grained PAT (github_pat_...with Copilot Requests permission) orCOPILOT_GITHUB_TOKEN.
When WithBaseDirectory is unset, providers/copilot leaves BaseDirectory empty so the Copilot SDK uses its standard ~/.copilot directory. Pass WithBaseDirectory(...) explicitly if you want isolated session/config storage.
2. Basic Usage
import ( "github.com/masterkeysrd/loom/llm" loomcopilot "github.com/masterkeysrd/loom/providers/copilot")
provider, err := loomcopilot.NewDefaultProvider()if err != nil { // handle error}defer provider.Close()
model, err := llm.NewModel(provider, "auto", nil)if err != nil { // handle error}Model profiles are populated dynamically via provider.ListModels(ctx) (models.list or custom WithOnListModels) with OverrideProfile support. Discovered model IDs that match generated models.dev metadata (providers/copilot/profiles.gen.go, refreshed via go generate ./providers/copilot) are automatically enriched with family, release dates, descriptions, wire-supported input modalities (Image/PDF; Audio/Video claims are filtered out because the SDK has no attachment path for them), attachment support, USD reference pricing/tiers, and fallback context/reasoning metadata—while keeping live models.list limits/efforts authoritative, enforcing Capabilities.Temperature = false, and never exposing unadvertised static catalog entries in ListProfiles() or GetProfile(). Inline user-message images must be PNG, JPEG, WebP, or GIF (the only formats the Copilot runtime forwards to models); document attachments must be inline application/pdf bytes (sent as blob attachments, which Anthropic-backed sessions receive as citable document blocks). URL-only media is rejected. Always call defer provider.Close() so active/parked sessions and the SDK runtime stop cleanly.
3. How Loops, Retries & History Work
providers/copilot tags Assistant responses with copilot.session_id, copilot.turn_token, copilot.prefix_digest, and copilot.event_id, and routes each Stream() call down one of two paths:
- Path A (Live Tip Match):
- In Loom
Agent -> Tools -> Agentloops,llm.Request.Toolsare registered as customcopilot.Tooldefinitions (SkipPermission: true, with built-in CLI tools disabled by default). - When the model invokes a Loom tool, the SDK tool handler parks in-flight while
Stream()yields*message.ToolCallto Loom. Once Loom’sToolsnode executes your Go tool and sends*message.Toolback, Path A unblocks the parked handler withcopilot.ToolResultwithout recreating the session. - Sequential user turns reuse the same warm
*copilot.Session.
- In Loom
- Path C (Fresh Session Fallback):
- On first turns, Loom-side history edits or compaction (
prefix_digestmismatch),RetryMiddlewareretries / parallel graph branches, or cold checkpoint restores across restarts, a fresh*copilot.Sessionis created fromrequest.Messages. (The Copilot SDK does not currently expose a non-mutating session fork primitive.)
- On first turns, Loom-side history edits or compaction (
4. Permissions
- Loom-bound tools (
model.BindTools(...), default): Built-in Copilot CLI tools (builtin:*) and built-in subagents are disabled by default so Loom owns tool execution and permissions in itsToolsnode. - Runtime permission requests: To prevent pending-permission deadlocks,
providers/copilotalways installs anOnPermissionRequestcallback:- Custom
WithPermissionHandler(fn)if provided; copilot.PermissionHandler.ApproveAllifWithAllowAllPermissions(true)is set;- Otherwise an explicit rejection (
*rpc.PermissionDecisionReject).
- Custom
- Native Copilot tools (
WithAllowedNativeTools/Session.NativeTools): Enable specific built-in tools such as"view"or"grep"alongside aWithPermissionHandlerorWithAllowAllPermissions(true). Native tools execute inside the Copilot runtime turn rather than yielding*message.ToolCallto Loom.
5. Configuration, Compaction, Quotas & BYOK
Provider Options
provider, err := loomcopilot.NewDefaultProvider( loomcopilot.WithCLIPath("/opt/homebrew/bin/copilot"), loomcopilot.WithBaseDirectory("/path/to/copilot-home"), loomcopilot.WithWorkingDir("/path/to/repo"), loomcopilot.WithSystemMessageMode("replace"), // or "append" loomcopilot.WithIdleTTL(10 * time.Minute), loomcopilot.WithTraceWriter(os.Stderr), // structured SDK session trace lines)Per-Request Extension (copilot.Session) & Compaction
model = model.WithExtension(loomcopilot.Session{ WorkingDir: "/path/to/workspace", NativeTools: []string{"view", "grep"}, ForceFresh: false,})
// Trigger Copilot's native `session.history.compact` RPC for a single turn:resp, err := model.Invoke(ctx, msgs, llm.WithExtensionOption(loomcopilot.Session{ Compact: true, CompactInstructions: "Preserve architecture decisions and open TODOs",}))Manual or background compaction emits on_llm_compacting and on_llm_compacted events to stream.WriterFromContext(ctx) and tags Assistant.Metadata with copilot.compacted, copilot.compact_trigger, copilot.compact_tokens_removed, and copilot.compact_messages_removed.
Idle Notifications (llm.IdleMessageNotifier) & Sync-on-Write (*llm.OutOfSyncError)
provider, err := loomcopilot.NewDefaultProvider( loomcopilot.WithSyncOnWrite(true), loomcopilot.WithOnIdleMessage(func(msg message.Message) { // Offload blocking I/O (e.g. webhooks) to your own goroutine/channel. }),)When WithSyncOnWrite(true) is enabled, idle background compaction/truncation or session shutdown causes the next stale write to fail with *llm.OutOfSyncError (carrying reconciled syncErr.Messages), matching providers/claudecode.
Quota Inspection & Credit Consumption (llm.QuotaProvider, TokenMetrics.Credits)
snap, err := provider.GetQuotaSnapshot(ctx) // "premium_interactions", "chat", "completions"When Copilot reports AssistantUsageData, chunk.Metrics.Credits (message.CreditMetrics) is populated with server-reported ai_credits (TotalNanoAiu / 1e9) or premium_requests fallback, along with Multiplier (Cost) and Status (AiCreditsStatus).
BYOK / Local Endpoints (e.g. Ollama)
provider, err := loomcopilot.NewDefaultProvider( loomcopilot.WithBYOKProvider(&copilot.ProviderConfig{ Type: "openai", BaseURL: "http://localhost:11434/v1", }),)6. Running the Example
See examples/copilot for a streaming interactive REPL + Agent -> Tools -> Agent demo:
# Using your local `copilot login` session (`auto` model):go run ./examples/copilot
# Using a specific Copilot model:go run ./examples/copilot --model gpt-5.4
# Inspect account quota buckets:go run ./examples/copilot --quota
# Using a local OpenAI-compatible BYOK endpoint (e.g. Ollama) with trace logs:go run ./examples/copilot --debug --endpoint http://localhost:11434/v1 --model qwen3-coder7. Limitations
- Sampling and context parameters not exposed by the Copilot SDK (
Temperature,TopP,TopK,PresencePenalty,FrequencyPenalty,Stop,MaxTokens,ContextWindow) are ignored (except BYOKProviderConfig.MaxPromptTokens/MaxOutputTokens). - Inline
ImageBlockdata (len(Data) > 0) is supported on the activeUserprompt (viaAttachmentBlob) andToolresults (viaToolBinaryResult); URL-only/empty images, historical transcript media, andAudioBlock/VideoBlock/DocumentBlockinputs fail fast withprofile.ErrUnsupportedModality. ResponseSchemaandThinkingConfig(ReasoningEffort) are forwarded when supported.- Dynamic
ModelInfoentries report billing multipliers and AI-credit prices rather than USD token pricing;Profile.Pricingand long-context tiers are filled from generatedmodels.devreference data (profiles.gen.go) when the model ID matches, and remain zero for custom/BYOK or uncatalogued IDs unless overridden viaOverrideProfile.