Configuration • gptr

Use gptr_config() for named settings, options(gptr.*) for process-level controls, and arguments to peter() for the call you are making. Inspect the effective settings before changing them; each value has a source layer. This guide executes only temporary process changes and fake-provider calls. Examples that write configuration files are not executed.

Scope and precedence

library(gptr)
cfg = gptr_config()
cfg[c("mode", "context", "record", "replay", "budget")]
#> $mode
#> [1] "manual"
#>
#> $context
#> [1] "summary"
#>
#> $record
#> [1] "ask"
#>
#> $replay
#> [1] "auto"
#>
#> $budget
#> $budget$tokens
#> [1] 2e+06
#>
#> $budget$cost
#> [1] 5
#>
#> $budget$turns
#> NULL
attr(cfg, "sources")[c("mode", "context", "budget")]
#>      mode   context    budget
#> "default" "default" "default"

Ordinary settings resolve from lower to higher priority as follows: package defaults, user settings, project settings, user-level project permission rules, R options, then settings for this R process. Explicit call arguments choose the values for that call. Safety and trust restrictions still apply; an explicit call cannot disable the inherited permission guards.

Scope	Lifetime and location	Use it for
`"session"`	This R process; no settings file	Temporary defaults for scripts or exploration. It is not limited to one `gptr_session` conversation.
`"project"`	`.gptr/settings.json` in an initialized project	Shared project defaults and stricter context/permission policy.
`"user"`	`tools::R_user_dir("gptr", "config")/settings.json`	Personal defaults across projects and provider egress acknowledgments.
`NULL`	Project when a `.gptr/` workspace exists; otherwise this R process	Convenient interactive changes; use an explicit scope in scripts.

gptr_config() with no settings reads the effective values; it does not read only the scope named in .scope. A setter returns the previous values in the chosen scope invisibly. Setting a key to NULL removes that override and exposes the lower layers. Unknown setting names are errors; plugins can add registered settings. A setter replaces the supplied key’s stored override at that scope, so include entries you want to retain in the same named object.

previous = gptr_config(mode = plan, budget = list(cost = 1, turns = 10),
                       .scope = "session")
gptr_config()$mode
#> [1] "plan"
gptr_config()$budget
#> $tokens
#> [1] 2e+06
#>
#> $cost
#> [1] 1
#>
#> $turns
#> [1] 10
gptr_config(mode = previous$mode, budget = previous$budget, .scope = "session")

Create the project workspace and choose whether to trust its executable resources:

gptr_init("/path/to/project")
gptr_trust("/path/to/project", trust = TRUE)
gptr_config(model = "openai/gpt-6-sol", .scope = "user")
# Run from the project after inspecting its contents:
gptr_config(context = "names", record = "off", .scope = "project")

Creating .gptr/ consents to storage there; trust is a separate decision. An untrusted project can tighten mode, context, recording, permission rules and local-only inference, but its other settings and executable resources are ignored. Even a trusted project cannot loosen settings marked for tightening. Changes to trust-gated files require renewed trust. Project provider endpoint overrides also require a separate confirmation.

gptr_permissions(scope = "project") stores personal project rules in the user configuration directory, not the shared project tree.

Settings by purpose

The tables cover the public core settings. Nested values are named lists and merge with lower layers when settings are resolved. The file’s version field is format metadata; keep it at 1. gptr_config() also shows setting keys registered by installed extensions.

Model and execution setting	Default and purpose
`model`	`NULL`: try configured Anthropic, OpenAI, Google, Claude Code CLI, then Codex CLI routes in that order. Set a canonical reference for other routes or reproducible routing.
`small_model`	`NULL`: the main model’s small sibling when available, otherwise the main model.
`system1`	`NULL`: hosted Jev when its key exists, otherwise a verified local decision model already discovered. Set an explicit typed model or opt-in `"emulate:<model>"` route.
`mode`	`"manual"`; also `"plan"`, `"edits"`, `"auto"`.
`preset`	`"standard"`; built-in alternatives are `"minimal"`, `"readonly"`, `"extended"`.
`tools`	Enable/disable lists and model-glob preset mappings: `list(enable = ..., disable = ..., presets = ...)`.
`budget`	`list(tokens = 2000000, cost = 5, turns = NULL)` per top-level call; `NULL` entries remove individual limits.
`output_tokens`	Registered output-limit setting, default `NULL`. Current built-in request construction uses model output metadata; do not rely on this key to impose a request limit.
`providers`	Provider objects with endpoint, models, headers, `enabled` and protected `local_only` overrides.

gptr_config(
  model = "openai/gpt-6-sol",
  budget = list(cost = 2, turns = 20),
  tools = list(disable = "write", presets = list("google/gemini-*" = "extended")),
  .scope = "session"
)

Use a call’s budget to limit total work, and review gptr_usage() for actual or unknown usage:

session = peter("Summarize mtcars in three sentences.")
gptr_usage(session)

A cost limit uses the route’s available prices; unknown prices or usage are not a guarantee of free execution. Disabling a direct tool does not make in-process R a sandbox.

Context and history setting	Default and purpose
`context`	`"summary"`; `"names"` uses workspace names and attachment headers; `"none"` omits built-in workspace and attached-object descriptions. R objects remain available to tools.
`record`	`"ask"`; `"auto"` allows automatic document recording and `"off"` prevents it. An explicit `gptr_doc(path)` binding supplies recording consent.
`replay`	`"auto"`; `"replay"`, `"live"`, `"record"` choose how recorded blocks are used.
`transcript`	`"ask"`; `"file"`, `"active-document"`, `"off"` select console recording.
`doc`	`list(outputs = TRUE, output_lines = 12)` for recorded outputs.
`cache_commit`	`list(s1 = TRUE, s2 = FALSE)`; `s1` controls the System 1 cache’s ignore policy. `s2` is registered but has no current built-in consumer. Review content before committing caches.
`cache`	`list(ttl = "gap")`; prompt-cache TTL policy, with supported `"5m"` and `"1h"` alternatives.
`compact_at`	`200000` estimated tokens; a soft compaction cap, also bounded by the model’s context.
`compactor`	`"checkpoint"`; selects a registered compactor.
`checkpoint`	`"on"`; `"files"` or `"off"` changes checkpoint capture.
`plot`	Registered defaults `list(width = 768, height = 512, res = 120)`. Current renderers read `gptr.plot_width`, `gptr.plot_height` and `gptr.plot_res` options; use those to change model-bound plots.

The context setting controls built-in generative-model descriptions, rather than R object availability. Prompt text, tool results, images and other context blocks can still be sent. System 1 decisions encode their supplied input states separately; context = "none" is not a way to omit those states. See Execution model, Token efficiency and System 1 decisions.

Recording and replay are separate controls; see Script as history and Token efficiency.

Extension and interaction setting	Default and purpose
`permissions`	Named `allow`, `ask`, `deny` rule lists; use `gptr_permissions()` to manage rules.
`egress`	Provider acknowledgments, for example `list(openai = "ack")`; accepted only at user scope.
`plugins`, `filters`	Empty vectors; enable plugins or filter registry records such as `"-builtin:mcp"`. Protected permission components cannot be removed.
`skills`	`list(budget = 1500)`; optional `paths = list(project = ..., user = ...)` adds discovery directories.
`mcp`	`exposure = "r"`, `budget = 1500`, and an `import` list of supported harness configuration names.
`subagents`	`max_depth = 1`, `max_active = 8`, `max_workers = NULL`, `max_cli = 4`, `max_tasks = 8`; workers default to at most four.
`ui`, `frontend`	`NULL` selects by context; set the name of a registered UI or front end.
`store`, `evaluator`	`"jsonl"` and `"r"`; extension selection for session storage and R evaluation.

Extending gptr explains registered components. MCP tools are R members by default; imported configuration discovery does not authorize a project server. Read ?gptr_mcp_add and ?gptr_security before enabling executable project resources.

Provider overrides are set as a whole named object. Keep secrets in gptr_env() or the credential store rather than embedding literal values in settings:

gptr_config(providers = list(ollama = list(
  base_url = "http://127.0.0.1:11434/v1", local_only = TRUE
)), .scope = "user")
gptr_config(egress = utils::modifyList(gptr_config()$egress, list(openai = "ack")),
            .scope = "user")
gptr_permissions(allow = "r(fn:summary)", scope = "session")

Ollama local-only inference defaults to TRUE. Only an explicit human setting at user or session scope can relax it; project files, ordinary R options, model code and per-call switches cannot do so. A local endpoint still needs verified local execution metadata. See Language models for the supported connection routes.

R options

?gptr_options documents every gptr.* option with its type, default and units; use options() for these controls.

A function can temporarily limit model-visible R output and restore the caller’s option on exit. This example uses a fake provider so it runs offline:

short_run = function() {
  previous = options(gptr.r_output_tokens = 1000L)
  on.exit(options(previous), add = TRUE)
  fake = gptr_fake_provider(list("A compact answer."))
  peter("Give a compact answer.", model = fake)$text
}
short_run()
#> [1] "A compact answer."

Options generally apply when the next call reads them. A run freezes its safety controls at start, and a session freezes its prompt/tool array, so a change need not alter work already in progress. gptr.interactive does not create a usable UI in an unattended process. The default gptr.noninteractive_ask = "stop" raises a condition with the blocked session; "deny" returns a denial to the model instead.

Environment and credentials

GPTR_PROJECT_ROOT selects a project root; gptr.project_root takes precedence. GPTR_REPLAY selects the replay mode below the call’s replay argument and gptr.replay option. Provider keys include ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY or GOOGLE_API_KEY, and TYPESAFE_API_KEY; other routes name their keys in gptr_providers(). Load a private file explicitly with gptr_env(path), or use interactive gptr_login() for supported API/MCP credentials. Sign in to subscription CLIs using their own tools.