Claude Code
The Claude Code provider (providers/claudecode) implements llm.Provider on top of the official claude CLI (stream-json + control protocol) using an in-process mini-proxy.
It lets you run standard Loom graphs (Agent -> Tools -> Agent loops, model.BindTools, checkpoints, compaction, and retries) backed by your local Claude Code installation and authentication (Claude Pro/Max subscription, CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_API_KEY, or custom Anthropic-compatible endpoints such as Ollama).
1. Prerequisites & Authentication
Ensure the claude CLI is installed and authenticated:
claude auth login# or set one of:export CLAUDE_CODE_OAUTH_TOKEN='...'export ANTHROPIC_API_KEY='...'CLAUDE_CONFIG_DIR & Multi-Account Support
- Ephemeral isolated mode (default when
ConfigDiris empty): Creates a temporaryCLAUDE_CONFIG_DIR(removed onProvider.Close()) and syncs file-based.credentials.jsonfrom~/.claudewhen present. Ideal on Linux/CI or when usingCLAUDE_CODE_OAUTH_TOKEN/ANTHROPIC_API_KEY. - macOS Keychain & Multi-account directories: On macOS,
claude auth loginstores OAuth credentials in the macOS Keychain keyed byCLAUDE_CONFIG_DIR. To use an existing login or run multiple accounts concurrently (e.g., personal + work), passWithConfigDirexplicitly perProvider:
personal, _ := loomclaudecode.NewDefaultProvider( loomclaudecode.WithConfigDir(filepath.Join(home, ".claude")),)work, _ := loomclaudecode.NewDefaultProvider( loomclaudecode.WithConfigDir(filepath.Join(home, ".claude-work")),)2. Basic Usage
import ( "github.com/masterkeysrd/loom/llm" loomclaudecode "github.com/masterkeysrd/loom/providers/claudecode")
provider, err := loomclaudecode.NewDefaultProvider()if err != nil { // handle error}defer provider.Close()
model, err := llm.NewModel(provider, "sonnet", nil)if err != nil { // handle error}Model profiles are derived dynamically from providers/anthropic’s loomgen catalog alongside Claude Code aliases (sonnet, opus, haiku, default). Custom model IDs (e.g., Ollama models) are also accepted by llm.NewModel.
Always call defer provider.Close() so warm or parked CLI subprocesses and any temporary config directories are cleaned up when your application exits.
3. How Loops, Retries, Compaction & Caching Work
The in-process mini-proxy tags Assistant responses with claudecode.session_id, claudecode.turn_token, and claudecode.prefix_digest, and routes each Stream() call down one of three paths:
- Path A (Live Tip Match):
- In Loom
Agent -> Tools -> Agentloops,llm.Request.Toolsare advertised over the CLI’s in-process SDK MCPcontrolchannel (--mcp-configtype: "sdk", with built-in CLI tools disabled by default via--tools ""). - When the model invokes a tool, Loom receives
*message.ToolCall, executes your Go tool in theToolsnode, and the proxy delivers the resulting*message.Toolmessages back to the parked CLI process asmcp_responseframes—preserving Anthropic prompt caching with zero process respawn.
- In Loom
- Path B (Snapshot Fork):
- Clean
.jsonlsession transcripts are snapshotted per turn insideCLAUDE_CONFIG_DIR. - On
graph.RetryMiddlewareretries or parallel graph branches from an earlier checkpoint, the proxy clones the snapshot to a forked session and resumes via--resume, preserving the prompt-cache prefix without mutating the original session.
- Clean
- Path C (Fresh Session Fallback):
- On first turns, Loom-side conversation compaction (detected via
prefix_digestmismatch), history edits, or cold checkpoint restores across process restarts, a fresh CLI session is started fromrequest.Messages.
- On first turns, Loom-side conversation compaction (detected via
4. Permissions
Permissions depend on which tools are enabled:
- Loom-bound tools (
model.BindTools(...), default): Built-in Claude Code tools are disabled (--tools ""). The CLI’scan_use_toolcontrol checks auto-allowmcp__loom__*only so the CLI forwardstools/callup to Loom as*message.ToolCall. All actual execution, allowlists, HITL interrupts, and sandboxing happen inside your LoomToolsnode—identically to other providers. - Native Claude Code tools (
WithAllowedNativeTools/Session.NativeTools): Built-in tools enabled viaWithAllowedNativeTools("Read", "Grep")run inside the CLI subprocess and are gated byWithPermissionMode(...)(defaults to"bypassPermissions"for headless loops).
5. Configuration, Compaction & Sync-on-Write
Provider Options
provider, err := loomclaudecode.NewDefaultProvider( loomclaudecode.WithCLIPath("/usr/local/bin/claude"), loomclaudecode.WithConfigDir("/path/to/claude-config"), loomclaudecode.WithWorkingDir("/path/to/repo"), loomclaudecode.WithIdleTTL(10 * time.Minute), loomclaudecode.WithAllowedNativeTools("Read", "Grep"), loomclaudecode.WithTraceWriter(os.Stderr), // debug raw stdin/stdout/stderr frames)Per-Request Extension (claudecode.Session)
model = model.WithExtension(loomclaudecode.Session{ WorkingDir: "/path/to/workspace", NativeTools: []string{"Read", "Bash"}, ForceFresh: false,})
// Trigger native Claude Code compaction (`/compact`) for a single turn:resp, err := model.Invoke(ctx, msgs, llm.WithExtensionOption(loomclaudecode.Session{ Compact: true, CompactInstructions: "Preserve architecture decisions and open TODOs",}))When Claude Code compacts (either automatically via auto or manually via Session.Compact), the provider emits on_llm_compacting and on_llm_compacted events to stream.WriterFromContext(ctx) and tags Assistant.Metadata with claudecode.compacted, claudecode.compact_trigger, and claudecode.compact_pre_tokens.
Idle Notifications (llm.IdleMessageNotifier) & Sync-on-Write (*llm.OutOfSyncError)
To receive unsolicited events emitted while a CLI session is idle between turns (such as background compaction or unexpected exits) as standard message.Message values (carrying IdleEventExtension and SyncCheckpointExtension):
if notifier, ok := provider.(llm.IdleMessageNotifier); ok { unsub := notifier.OnIdleMessage(func(msg message.Message) { // Offload blocking I/O (e.g. webhooks) to your own goroutine/channel. }) defer unsub()}Enable WithSyncOnWrite(true) if you want Stream() to reject writes with *llm.OutOfSyncError (carrying Messages message.MessageList) whenever an idle compaction or out-of-band history edit diverges from the live CLI session, letting your graph rearrange state.Messages and resubmit on the same warm session:
provider, err := loomclaudecode.NewDefaultProvider( loomclaudecode.WithSyncOnWrite(true),)
resp, err := model.Invoke(ctx, state.Messages)var syncErr *llm.OutOfSyncErrorif errors.As(err, &syncErr) && len(syncErr.Messages) > 0 { state.Messages = append(slices.Clone(syncErr.Messages), pendingUserMsgs...) resp, err = model.Invoke(ctx, state.Messages)}Quota Inspection (llm.QuotaProvider)
When running with a claude.ai subscription credential, Provider implements llm.QuotaProvider by querying Claude Code’s /usage slash command and decoding usage_report.rate_limits (limits[] rolling windows and extra_usage credit pools):
if qp, ok := provider.(llm.QuotaProvider); ok { snap, err := qp.GetQuotaSnapshot(ctx) // cached 30s by default (WithQuotaCacheTTL) _ = snap _ = err}Unauthenticated sessions or plain ANTHROPIC_API_KEY environments return an empty snapshot without error. Use go run ./examples/claudecode --quota to inspect active pools from the CLI.
6. Running the Example & Local Endpoints (e.g. Ollama)
See examples/claudecode for a streaming interactive REPL + Agent -> Tools -> Agent demo:
# With your local Claude Code login (~/.claude):go run ./examples/claudecode --model sonnet
# Inspect subscription rate limits and extra usage via /usage:go run ./examples/claudecode --quota
# With a separate account config directory:go run ./examples/claudecode --config-dir ~/.claude-work --model sonnet
# With a local Anthropic-compatible endpoint (e.g. Ollama) and protocol trace:OLLAMA_CONTEXT_LENGTH=65536 ollama servego run ./examples/claudecode --debug --endpoint http://localhost:11434 --model qwen3-coder7. Limitations
- Sampling parameters not exposed by the
claudeCLI (Temperature,TopP,TopK,PresencePenalty,FrequencyPenalty,Stop,ContextWindow) are ignored;Thinking.Effortmaps to--effort <level>(low,medium,high,xhigh,max). - Multimodal media blocks (
ImageBlock,AudioBlock,VideoBlock,DocumentBlock) are not transported over theclaudeCLIstream-jsonprompt/MCP bridge and fail fast withprofile.ErrUnsupportedModalityinstead of being dropped; useproviders/anthropicfor multimodal image/PDF inputs. - Model swaps and permission-mode changes on sequential warm turns reuse the live session via
control_request(set_model,set_permission_mode), and context cancellation issues aninterruptcontrol request before shutdown. ListModels/GetModeldiscover models dynamically from the CLI’sinitializehandshake (matchingproviders/copilot, soListProfiles/GetProfilereturn cached discovered models + overrides without spawning eagerly) and enrich matched IDs with limits, pricing, and modalities fromproviders/anthropic.- When using a Claude Pro/Max subscription (
CLAUDE_CODE_OAUTH_TOKENor local login), reported dollar estimates are informational; token usage (Input,Output,CacheRead,CacheWrite) is still reported in Loom telemetry and Studio. - If you have an
ANTHROPIC_API_KEYand do not need theclaudeCLI harness or subscription auth,providers/anthropicremains the recommended choice for lowest latency and full parameter control.