codeagent

Language: English | 简体中文文档

An R-native agentic coding assistant built on ellmer and btw. It reimplements a coding-agent harness in R: the agent loop, permission system, context compaction, hook system, skill system, tool execution, session management, multi-agent coordination, a CLI REPL, and an interactive Shiny UI.

Not a wrapper. codeagent reimplements the harness from scratch rather than shelling out to an external CLI.

Installation

# DESCRIPTION pins the verified GitHub builds of all eight core packages.
pak::pak("kaipingyang/codeagent")

# Recommended: install the pinned btw development build for R-environment tools.
pak::pak("posit-dev/btw@473d1d8e3114ed9136692ff3fb6b88ed0474ba66")

Configuration

Step 1 — Create settings file

codeagent::use_codeagent_settings()   # creates ~/.codeagent/settings.json

Edit the generated file with your endpoint:

{
  "provider": "openai_compatible",
  "model": "main",
  "env": {
    "CODEAGENT_BASE_URL": "https://YOUR-WORKSPACE/serving-endpoints",
    "CODEAGENT_MODEL": "your-main-endpoint",
    "CODEAGENT_FAST_MODEL": "your-fast-endpoint",
    "CODEAGENT_API_KEY": "your-token"
  }
}

CODEAGENT_* vars in the env block are loaded at startup even under --vanilla, so you do not need to set them separately in .Renviron.

Step 2 — Install the CLI (once)

codeagent::install_codeagent_cli()   # puts `codeagent` on your PATH

codeagent           # interactive REPL (default permission mode)
codeagent -y        # bypass mode (skip all permission prompts)
codeagent "query"   # one-shot query

Quick start (R)

library(codeagent)

# Option A: auto-build client from settings.json
client <- codeagent_client()

# Option B: explicit ellmer Chat
chat   <- ellmer::chat_openai_compatible(
  base_url    = Sys.getenv("CODEAGENT_BASE_URL"),
  model       = Sys.getenv("CODEAGENT_MODEL"),
  credentials = function() Sys.getenv("CODEAGENT_API_KEY")
)
client <- codeagent_client(chat)

# One-shot query
codeagent(client, "List all .R files in R/")

# Interactive Shiny app
codeagent_app(client)

# Interactive CLI REPL
codeagent_console(client)

Features

Agent harness

Feature	Details
Agent loop	agent_loop() with max_turns, token budget tracking, an optional hard max_budget_usd dollar-cost cap (codeagent_client(max_budget_usd=) / CODEAGENT_MAX_BUDGET_USD / max_budget_usd in settings.json; checked via chat$get_cost(), only fires where ellmer has price data for the model/provider), and compaction
Permissions	7 modes: default, plan, accept_edits, bypass, dont_ask, auto, bubble; fine-grained rules match tool arguments
Hooks	27 Claude Code-aligned lifecycle events (tool, permission, message, session, task, worktree, compaction), configurable from settings.json. PreToolUse can rewrite tool arguments (SDK-style updatedInput) or deny a call
Compaction	Dynamic per-model context window + adaptive request-boundary flow (cheap result controls → micro snip → fresh structural recount → conditional incremental/full summary), structured tool-aware summary input, post-action validation, default-zero implicit token-count network calls, pair-safe PTL/413 recovery, an "N% context left" indicator (REPL + Shiny), and per-request coverage across internal tool-loop rounds through a Claude Agent SDK-compatible lifecycle
System prompt	Tone, task, convention, tool-use, and R-specific behavioural guidance
Error recovery	PTL/rate-limit/network/auth classification; exponential backoff; one finish-reason mapper reports completed/truncated/filtered/incomplete-tool-use consistently across sync, stream, and Shiny paths
Verification	verify_fn param + verify_r_tests() re-enters loop on test failures
Plan mode	Model enters/exits read-only planning mid-turn
Rewind	truncate_chat_turns() / REPL /rewind roll the conversation back
Model switch	switch_model(client, model) uses verified name-only in-place switching; provider/config changes rebuild a new client while preserving history, hooks, tools, budgets, and the live Data Shield engine

Pricing data is never refreshed automatically during startup or model requests. Opt in to the network request explicitly when you want to refresh ellmer's public pricing snapshot:

price_update <- update_model_prices()
price_update$message

Custom or private provider endpoints may still have no matching price after a refresh. In that case chat$get_cost() may remain zero and a max_budget_usd cap cannot trigger; token budgets continue to work normally.

Tools

Group	Source	Tools
Core	codeagent	Bash, Read, Write, Edit, MultiEdit, Glob, Grep, LS
docs	btw	help pages, vignettes, NEWS
env	btw	describe data frames / R environment
files	btw	hash-anchored precise editing + atomic multi-file patch
git	btw	status, diff, log, commit, branches
pkg	btw	document, check, test, coverage, load_all
web	btw	URL → Markdown
agent	btw	hierarchical subagent delegation
data	codeagent	ExploreData — arbitrary model-generated R execution over a data.frame (exec-gated, not a sandbox); DescribeData — strict protected-data metadata (Data Shield)
genui	codeagent	canvas_value_box, canvas_data_table, canvas_scatter_plot, canvas_histogram, canvas_update, canvas_remove, canvas_clear, canvas_state — Shiny app only, see Generative UI canvas

Selecting tools

codeagent_client(tools=) picks what gets registered, in one capability namespace shared by codeagent-native and btw groups:

This is the beginning of the README. Read the rest at the original. Read the full README ↗