Create a codeagent client from any ellmer Chat — codeagent

Injects codeagent tools (Bash, Read, Write, Edit, Glob, Grep, LS, btw tools, skill tool) and rebuilds the system prompt. The returned CodeagentClient is the single object passed to codeagent() and codeagent_app().

Usage

codeagent_client(
  chat = NULL,
  permission_mode = "default",
  rules = list(),
  cwd = getwd(),
  max_turns = 100L,
  btw_groups = NULL,
  worktree_isolation = FALSE,
  verify_fn = NULL,
  mcp_config = NULL,
  register_tools = TRUE,
  data_shield = NULL,
  max_budget_usd = NULL
)

Arguments

chat: An ellmer::Chat object – any backend supported by ellmer: chat_openai_compatible(), chat_anthropic(), chat_ollama(), etc. If NULL, a chat is auto-built from CODEAGENT_BASE_URL/CODEAGENT_MODEL env vars (or Anthropic defaults).
permission_mode: Character. One of PermissionMode.
rules: List of PermissionRule() objects.
cwd: Character. Working directory (used for CLAUDE.md, skills, sessions).
max_turns: Integer. Maximum agentic loop turns.
btw_groups: Character vector or NULL. btw tool groups to register (e.g. c("docs","git","pkg")). NULL = all available groups.
worktree_isolation: Logical. Run sub-agents in isolated git worktrees.
verify_fn: Function or NULL. Optional output verifier; re-enters the loop when it reports failures (e.g. verify_r_tests()).
mcp_config: MCP client config (JSON path or inline list) to connect external MCP servers; see register_mcp_client(). NULL disables.
register_tools: Logical. If TRUE (default) register all tools now. FALSE returns a lightweight shell (chat + settings + system prompt, no tools) so callers (e.g. codeagent_app()) can render UI first and defer the expensive tool registration; call .register_all_tools() later.
data_shield: NULL (off), a strategy list from shield_*() (creates a private DataShield R6), or an explicit DataShield instance shared by selected chat threads. For a harness-only client, attach tools then call client$data_shield$install(client$chat).
max_budget_usd: Numeric or NULL (default). Hard dollar-cost cap for this client's chat (mirrors Claude Code's maxBudgetUsd), checked alongside the token budget in agent_loop() via chat$get_cost(). NULL (default) means no cap. Only takes effect where ellmer has price data for the provider/model; unpriced custom endpoints (e.g. a Databricks/Azure serving endpoint ellmer doesn't recognize) report cost $0 forever, so the cap silently never fires there – this is a known limitation, not a bug (see CODEAGENT_MAX_BUDGET_USD env var / max_budget_usd in settings.json for the same knob without a client-code change).

Value

Object of class CodeagentClient with $chat, $settings, and $data_shield (NULL when disabled).