Backends: vscode, Copilot, Claude

Pick a backend

library(hal)

hal_configure(backend = "vscode")    # default in Positron
hal_configure(backend = "copilot")   # default elsewhere
hal_configure(backend = "claude")

hal_config()$backend

The setting takes effect on the next session init – call hal_reset() if you already have an active session and want to swap backends immediately.

Everything after that point is identical:

hal("explain this error")
mtcars |> hal_ask("summarize in 3 bullets")
iris |> hal_do("add petal_area = Petal.Length * Petal.Width")

vscode: when to pick it

• You’re using Positron (it’s the smart default there).
• You want zero extra CLI installs – no Node.js, no @github/copilot npm package, no claude binary.
• You want to reuse your existing Positron Copilot sign-in – no separate OAuth flow, no API keys.
• You’re sensitive to install friction on teammate machines: the bridge ships inside hal itself (inst/extdata/hal-bridge-X.Y.Z.vsix) and installs via the Positron CLI in one call.
• You want eval_r to round-trip through R directly without an MCP subprocess – the bridge speaks HTTP to your R session, so tool calls don’t fork another process.

Setup:

library(hal)
hal_install_bridge()                  # one-shot: installs bundled VSIX
# Fully quit Positron and reopen -- "Reload Window" is not enough on a
# fresh install; the extension host only loads new extensions cold.
hal_bridge_status()                   # confirms the extension is live
hal_available()                       # TRUE when port file + bridge are up

hal_install_bridge() requires only the Positron CLI on PATH (or POSITRON_BIN env var). No GitHub auth, no network call.

Models surface whatever vscode.lm exposes to your Positron Copilot session:

hal_models()                          # lists what vscode.lm has registered
hal("explain this error", model = "claude-3-5-sonnet")

If models you expect are missing, that’s a Positron / Copilot extension state issue – restart Positron or sign in again from the Copilot pane.

Copilot: when to pick it

• You already have a Copilot subscription – nothing extra to install beyond the CLI.
• You want model variety (GPT-5, Gemini, multiple Claude versions) all through one endpoint.
• You want mid-session model switching – start with a cheap 0x model for exploration, hot-swap to Opus for hard reasoning, no context loss.
• You rely on Plan or Autopilot mode.

Setup:

library(hal)
hal_setup()                           # installs Copilot CLI + guides login
hal_available()                       # TRUE when ready

Claude: when to pick it

• You have a Claude.ai subscription and want to drive it from R without an API key.
• You care about the Claude Code ecosystem – skills, hooks, subagents, MCP servers plug in directly.
• You want live quota visibility (hal_quota() shows the 5-hour window status).
• You’re doing many disposable pipe-verb calls and want Haiku’s $0.005 per-resume price tag.

Setup:

# Install Claude Code from https://claude.ai/download
claude               # run once interactively to complete OAuth

hal_configure(backend = "claude")
hal_available()                       # TRUE when `claude` is on PATH
hal("hello")                          # Haiku 4.5 by default

hal_configure(default_model = "claude-opus-4-5-20250902")

hal("deep reasoning", model = "claude-opus-4-5-20250902")

Quota: hal_quota()

Every Claude response stream carries a rate_limit_event with the 5-hour window status. hal_quota() surfaces it:

hal("hello")
hal_quota()
#> -- hal quota (claude) ----------------------------------------
#> i Window: "five_hour"
#> v Status: "allowed"
#> i Resets: 2026-04-23 17:30:00 PDT
#> i Overage: "allowed"

hal_quota() returns NULL on the Copilot backend (flat subscription – there’s nothing to show).

Fields returned as a hal_quota list:

• type – currently always "five_hour"
• status – "allowed" or "rate_limited"
• resets_at – POSIXct; when the window clears
• overage_status – "allowed" or "rejected"
• overage_disabled_reason – e.g. "out_of_credits" when relevant
• backend – "claude"

What Claude doesn’t support

hal’s Claude client stubs these with a warning rather than pretending:

chat <- hal_chat()

chat$switch_model("claude-opus-4-5-20250902")
#> ! Mid-session model switching not available on Claude backend.
#> i Start a new session with `hal_reset()` and a different default model.

chat$set_mode("plan")
#> ! Session modes (plan/autopilot) not available on Claude backend.

To switch models on Claude, reset the session:

hal_configure(default_model = "claude-opus-4-5-20250902")
hal_reset()

Mock CLI for offline testing

The Copilot and Claude backends each ship with a mock CLI under inst/mock-cli/ so CI and local unit tests don’t need network, login, or credits:

• inst/mock-cli/mock_copilot.R – NDJSON ACP server
• inst/mock-cli/mock_claude.R – stream-json per-turn

The vscode backend has no mock equivalent – its transport is a real localhost HTTP server inside Positron. vscode-backend tests stub the bridge at the R level (port file + handler shim) rather than running a fake extension.

Scenarios are passed as the first positional arg (basic, echo, thinking, tool_use, tool_roundtrip, multi_turn, rate_limit, error, slow). See tests/testthat/helper-mock-client.R for the harness pattern.

See also

• ?hal_configure – the backend argument and all other session settings
• ?hal_quota – structure of the returned object
• vignette("getting-started") – end-to-end walkthrough
• vignette("agent-tools") – built-in tools, eval_r, custom MCP tools