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, temporary files and
fake-provider calls. Examples that write configuration files are not
executed.
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.
cost = 2 in
the user file, cost = 1 and turns = 10 for
this R process (as below) and budget = list(turns = 5) in
the call, the call takes its token limit from the package defaults, its
cost limit from this R process and its turn limit from the call.| 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" |
settings.json in the user configuration directory |
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. |
The user configuration directory is
tools::R_user_dir("gptr", "config").
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. At the console,
gptr_init() then asks whether to trust the project (its
settings, extensions and MCP servers); the default is No:
Run that line on its own: the question takes a line pasted after it,
ignores it and asks again, so the pasted line never runs. In a script,
where nobody can answer, no decision is recorded; record one there, or
change an earlier answer, with gptr_trust(), which without
trust reads it back as TRUE,
FALSE or NA:
Then choose settings for every project and for this one:
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. A trusted project may
also set the mode, though never to "yolo", but it still
cannot loosen context or recording. 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.
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", "yolo". An
untrusted project file can only tighten it; a trusted one sets any mode
but "yolo". |
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:
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. |
undo |
list(capture_max = 1e8, memory = 1e9, disk = 2e9, turns = 20).
Before a call that runs R code, undo keeps every object up to
capture_max bytes and each object the code is predicted to
change up to memory. A session’s undo images stay within
memory bytes in memory and disk bytes on disk,
for at most turns turns. The options
gptr.undo.capture_max, gptr.undo.memory,
gptr.undo.disk and gptr.undo.turns set the
same limits. |
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. In
particular, context = "none" retains project instructions
and environment details; it does not waive provider egress consent. A
remote provider still asks once interactively, or requires a saved
acknowledgment for unattended calls. After reviewing
?gptr_egress, save consent for the provider you use,
preserving any other acknowledgments:
gptr_config(egress = utils::modifyList(gptr_config()$egress, list(openai = "ack")),
.scope = "user")Offline providers and local loopback routes remain exempt, with
Ollama exempt only while its local-only inference is on. 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 Typed decisions.
Recording and replay are separate controls; see Record, replay and export and Token efficiency.
Undo keeps old values by reference; see Execution model for what that costs and
?gptr_rewind for what undo restores. When an object is too
large to keep, the approval question and the undo report name the limit
to raise. To keep up to 4 GB of undo images in memory in every
project:
| 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. |
type_ahead |
What Enter does with a message typed in a terminal console while the
agent works (Tab does the other); in other consoles, what a typed line
does: "steer" reaches the agent at its next step,
"follow_up" is the next prompt once the run ends. |
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.
?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.
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.
gptr_login() takes a key through hidden input, or signs
in through the browser where the provider offers it. Its
scope keeps the credential in gptr’s auth.json
in the user configuration directory (the default), in this R process
only, or in the operating system’s credential store; see Language models and
?gptr_login. Hidden input is not encryption.
gptr replaces registered secrets with markers such as
[secret:OPENAI_API_KEY] when they enter a transcript, a
cache or a history document. A value that reached a file before it was
registered, such as a key pasted into a prompt and loaded with
gptr_env() only later, stays there.
gptr_scrub() finds it. Without paths it scans this
workspace’s sessions, caches, plans, transcripts and bound documents; a
dry run reports the file, the secret’s name and a count, never the
value. This example registers a made-up token without exporting it:
key_file = tempfile(fileext = ".env")
writeLines("DEMO_SERVICE_TOKEN=demo-not-a-real-token-4821", key_file)
gptr_env(key_file, set_env = FALSE, quiet = TRUE)
notes = tempfile("notes")
dir.create(notes)
writeLines("Connected with demo-not-a-real-token-4821.", file.path(notes, "log.txt"))
found = gptr_scrub(notes)
found$secret
#> [1] "DEMO_SERVICE_TOKEN"
found$count
#> [1] 1dry_run = FALSE rewrites those files, replacing each
value with its marker:
gptr_scrub(notes, dry_run = FALSE)
readLines(file.path(notes, "log.txt"))
#> [1] "Connected with [secret:DEMO_SERVICE_TOKEN]."error = TRUE signals
gptr_error_secret_found when a file still holds a
registered secret, for a pre-commit hook or a CI step. A key that
reached a model or a commit must still be rotated.
gptr_redact() applies the same redaction to your own text
or logs; besides registered values, it recognizes common credential
shapes such as bearer tokens: