Configuration

How to configure corteza for your workflow.

Config files

corteza reads two JSON files and merges them. Project config overrides global config.

Merge semantics: project keys replace global keys at the top level; no deep merge.

Precedence: CLI flags > project config > global config > built-in defaults.

Example project config:

{
  "provider": "ollama",
  "model": "llama3.2",
  "context_files": ["README.md", "PLAN.md"],
  "approval_mode": "ask"
}

Create the directory first:

dir.create(".corteza", showWarnings = FALSE)

CLI flags

corteza [options]

Flags override config values for the current run.

JSON config keys

All keys shown with type and default, current as of corteza 0.6.3. Most defaults live in R/config.R::load_config(); a few (memory keys and the CLI port fallback) live in inst/bin/corteza.

Core

Context

Safety

Skills

Diagnostics

Rate limiting

Subagents

Presets. /spawn --preset <name> picks a fixed tool list at spawn time:

• investigate (default): read_file, grep_files, r_help, web_search, fetch_url (read/search/help, plus network reads).
• minimal: read_file, grep_files.
• work: investigate + bash, write_file, replace_in_file, list_files, git_status, git_diff, git_log, run_r.

/spawn --tools <comma-list> overrides the preset with an explicit tool list.

Permission model. Subagents have no interactive approval channel back to the parent or user. A child’s tool list is fixed at spawn time — via the --preset or --tools flags on /spawn, or the preset / tools arguments to subagent_spawn(). There is no mid-run path to escalate to a riskier capability: the child’s approval callback denies by default, and the parent cannot grant new tools after the fact. If a task may need shell, write, or network capability, choose a preset or explicit tool list that includes it at spawn time; otherwise the child should report that it is blocked.

Workspace

Channels

Matrix

Matrix channel requires mx.api (Suggests). Configured via a separate helper, not the main JSON config.

corteza::matrix_configure(
  server = "https://matrix.example.com",
  user = "corteza_bot",
  password = "verysecure",
  room = "#general:example.com",
  model = "llama3.2",
  provider = "ollama"
)

Legacy memory

Slash commands

In-chat commands prefixed with /.

Skills

Skills are SKILL.md files loaded at startup. Built-in R skills are always registered.

Search paths:

Nested (skill/SKILL.md) and flat (skill.md) layouts both work.

Package skills: register R packages as tools via skill_packages in config.

MCP server

Expose corteza tools to external MCP clients. serve() supports two transports:

# stdio transport (Claude Desktop, Claude Code, other MCP clients)
corteza::serve()

# socket transport (corteza CLI, R-to-R clients)
corteza::serve(port = 7850)

# restrict the toolset
corteza::serve(port = 7850, tools = "core")

port = NULL (the default) selects stdio. cwd = NULL (the default) leaves the working directory alone; pass an explicit path to anchor the server elsewhere. Tools execute in a persistent R session, so objects and loaded packages survive across calls.

Claude Desktop config (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "corteza": {
      "command": "Rscript",
      "args": ["-e", "corteza::serve()"]
    }
  }
}

Session tuning

new_session() is the programmatic entry point for embedding corteza in your own R code: a Shiny app, a batch script, a custom approval flow, or tests. The CLI and Matrix channels build on this same primitive.

library(corteza)

s <- new_session(
  channel = "cli",
  provider = "anthropic",
  max_turns = 20L,
  verbose = FALSE
)

result <- turn("What packages are loaded?", session = s)

The session is an environment that carries history, the active provider/model, and the approval callback. turn() mutates it in place and also returns the updated session, so you can chain calls or persist s$history between runs.

Session parameters

systemd service

matrix_run() is designed for a systemd user unit.

~/.config/systemd/user/corteza-matrix.service:

[Unit]
Description=corteza Matrix bot
After=network.target

[Service]
Type=simple
ExecStart=Rscript -e 'corteza::matrix_run()'
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

Enable and start:

systemctl --user daemon-reload
systemctl --user enable corteza-matrix.service
systemctl --user start corteza-matrix.service

View logs:

journalctl --user -u corteza-matrix.service -f

Environment variables

Set API keys in ~/.Renviron:

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

R options

Set in ~/.Rprofile or per-session via options().

Guide version: 0.6.3