hal: Chat with GitHub Copilot

In hal: Agentic Coding Assistants

Chat with GitHub Copilot

Description

The main entry point for conversational interaction with Copilot models. Maintains a persistent session across calls. The SDK agent has built-in tools for file operations, code search, and shell commands.

Usage

hal(..., model = NULL, use_env = NULL, reset = FALSE, inspect = FALSE)

Arguments

...	Character strings, concatenated as the user message.
model	Model identifier. If NULL, uses the session/configured default.
use_env	Logical or NULL; if TRUE, snapshots the caller's environment and injects it into the prompt so the model naturally uses eval_r to work with your R objects. If NULL (default), auto-detects: scans the prompt for R identifiers and injects the snapshot only when the prompt mentions an object that exists in the caller's environment. When auto-detect fires, a cli::cli_alert_info() announces the matched names (suppress with hal_configure(session_quiet = TRUE)). Set FALSE to disable.
reset	Logical; if TRUE, starts a fresh session before prompting.
inspect	Logical; if TRUE, returns session info instead of prompting.

Value

The assistant's text response (invisibly when displayed).

Errors in scripts

In an interactive session a transport failure prints an alert and returns invisible(NULL). In non-interactive contexts (scripts, R Markdown) it aborts with a classed condition instead, so programmatic callers can handle hal failures specifically: tryCatch(hal("..."), hal_transport_error = function(e) ...). All hal conditions inherit from hal_error / hal_warning; hal_do() signals hal_do_error / hal_do_warning, and hal_ask() signals hal_ask_warning.

Examples

## Not run: 
# Simple conversation
hal("What is R?")
hal("Can you explain more about data frames?")

# Environment access (auto-detected when objects exist)
df <- mtcars
hal("What's the mean mpg?")   # auto-detects df, injects env snapshot

# Reset and start fresh
hal("Hello", reset = TRUE)

# Inspect session
hal(inspect = TRUE)

## End(Not run)

hal documentation built on Oct. 6, 2026, 5:07 p.m.