The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

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

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.