Call peter() without
a prompt from an interactive R console to chat. It uses your current
environment and the configured model. Give it an explicit model when you
want to choose the route. The language-model guide covers API, CLI and
local setup.
On a new console with no explicit or configured model, Peter first
offers Codex CLI, Claude Code CLI and manual API/Ollama setup. Selecting
an installed CLI that reports Signed in saves its default
model in your user settings and opens the console. Unknown
permits your explicit choice with a notice; Not signed in
returns to R with terminal sign-in instructions. CLI-reported login does
not verify online access or subscription billing; an API-key login can
also count as signed in. Context-sharing acknowledgment remains
separate.
Manual setup prints API and local Ollama commands and returns to R;
cancellation, a missing CLI or a non-CLI replacement of a shortcut also
returns without saving a default. Configure a model as shown in Language models, then call
peter() again. An existing session, an explicit or
effective configured model, .stdin = TRUE and
noninteractive workflows skip setup. Calls with a prompt use their
normal model resolution.
The saved default applies in future R sessions and projects unless a
higher-priority setting overrides it. Use
gptr_config(model = "provider/model", .scope = "user") to
change it; see Configuration for
precedence and settings locations.
The default prompt is peter>; other permission modes
appear as peter[plan]>, peter[edits]> or
peter[auto]>. Enter /exit to return the
session invisibly to s. Objects created by the agent remain
in the environment where the console runs. R tools compute on those
in-memory objects across turns; you can inspect or reuse them at the R
prompt without exporting and reloading a dataset. Model context is a
separate, bounded description of that workspace; see Execution for copying and storage.
For input piped to an R process, peter(.stdin = TRUE)
explicitly reads standard input using the same syntax; end of input
returns the session. The console UI can consume permission answers from
that input too. Configure the model, credentials and permissions before
unattended work.
Ordinary responses, progress, setup and steering use normal console output. Actual failures use the error stream; handled guidance keeps a clear label without alarming error coloring. Reply and history formatting use the current console width; the client controls font size and zoom.
For programmatic event streams, select
.opts = list(frontend = "jsonl"). With
.stdin = TRUE, that frontend treats every input line as a
literal model prompt (or a JSON prompt record); /exit and
/quit end the stream. Slash commands and !
execution use the console frontend. JSONL stdout contains event records,
with human-readable notices on stderr.
An existing session can become a chat. This offline example creates one first:
library(gptr)
work = new.env()
work$x = 1:5
fake = gptr_fake_provider(list("The vector has five values.", "Their sum is fifteen."))
s = peter("Describe x.", x = work$x, model = fake, envir = work)
s$text
#> [1] "The vector has five values."Piping continues the same session and uses its kept workspace. To
explore independently, use gptr_fork(s) |> peter();
writes then stay in the fork’s overlay. /clear resets the
conversation while retaining workspace objects, model and mode.
Ordinary text is a prompt. @x attaches a visible R
object by name, and @analysis.R adds the beginning of a
text file. Quote a path containing spaces as
@"analysis notes.txt". Files take precedence when a mention
matches both a file and an object. A file mention sends at most its
first 40 lines; binary files contribute a description rather than their
contents. For a larger file, ask the agent to read the relevant
section.
peter> Compare @mtcars columns mpg and wt.
peter> Explain the approach in @analysis.R.
peter> !head(mtcars[, c("mpg", "wt")])
peter> Now suggest a diagnostic plot.!code runs your R code immediately in the console
environment, prints its output and adds a compact note of the code and
output to the next model prompt. It does not send a
prompt or spend model tokens by itself. The note is bounded to about 300
estimated tokens, so inspect large results in R and send the part the
model needs.
!!code also runs immediately, but does not add that
code/output note. Changes it makes are still part of the workspace that
later calls can inspect or describe. Neither prefix passes through the
model’s permission gate: you are explicitly running your own R code. Do
not paste unreviewed code merely because the agent suggested it.
In a native Unix R terminal with readline enabled, Tab retains R’s
completion after ! and !!, including objects
on R’s search path, namespaces and quoted file paths. Peter restores the
terminal’s completion setting when you leave and respects an existing
custom completer. Objects kept only in a private agent environment are
not added to R’s completion search path. RStudio, R.app, notebooks and
other editors own their input and completion UI; completion inside their
readline() prompt depends on the client. You can always run
ordinary R at the client’s R prompt, then return to Peter with the same
workspace.
peter> !fit = lm(mpg ~ wt, data = mtcars)
peter> !coef(fit)
peter> Explain the slope I just fitted.
peter> !!local_note = "Check the measurement units later"For multiple lines, use a triple-quoted prompt, a trailing backslash
to continue a prompt, or a fenced R block. The fenced block behaves like
!code. Incomplete !/!! R
expressions continue at the + prompt until they parse. Very
long single lines can exceed R’s console input limit; use an
@file or a multiline prompt instead.
peter> """
... Fit mpg on wt.
... Explain the units and give one diagnostic.
... """peter> ```r
... fit = lm(mpg ~ wt, data = mtcars)
... coef(fit)
... ```These input forms apply inside Peter’s chat; at the ordinary R
prompt, use normal R syntax. Console inputs may enter R’s history
(gptr.history), and an enabled transcript can record
user-run code. !! is a control over the next prompt note,
not a privacy boundary.
Streamed prose follows the available console width for newly received text. Previously printed scrollback, code blocks and long unbroken tokens keep their layout. Window resizing, font scaling and scrollback reflow are controlled by the terminal or editor.
These are all built-in slash commands. Arguments in brackets are
optional. /help lists the commands available in the current
session, including any supplied by plugins or prompt templates.
| Command | Effect |
|---|---|
/help [command] |
List input syntax and commands, or describe one command. |
/exit, /quit, /q |
Leave the chat and return its session. |
/model [provider/model or alias] |
Show the model or switch it from the next request; keeps the conversation. |
/mode [plan|manual|edits|auto] |
Show the mode or switch it from the next turn. |
/plan |
Switch to plan mode for read-only exploration and a proposed plan. |
/tools |
List direct tools and peter$ members. |
/env [pattern] |
Describe workspace objects whose names contain the pattern. |
/compact [focus] |
Compact the conversation now, optionally emphasizing a topic; may make a model request. |
/cost |
Show this session’s tokens and cost. |
/context |
Show the token ledger of the last request. |
/status |
Show session, model, mode, document and queued messages. |
/clear |
Start a new conversation while retaining workspace objects, model and mode. |
/resume [id] |
List stored sessions or continue the selected session in this console. |
/fork |
Continue on a new session with an overlay workspace. |
/doc [path] |
Show the recording document or bind one; binding authorizes writes to it. |
/skills |
List discoverable skills. |
/skill:<name> [request] |
Preload a skill and send the request; without a request, ask the agent to use that skill. |
/mcp |
List MCP servers. |
/permissions |
Show the permission rules. |
/permissions allow|ask|deny|remove <rule> |
Change a rule for this R process, for example
/permissions allow r(fn:saveRDS). |
/retry |
Undo the last turn and send its recovered prompt again; may make a model request. |
/undo |
Undo the last turn’s restorable objects, files and conversation. |
/redo |
Redo what the last rewind undid. |
/rewind [k] |
Offer a rewind menu, or retain turns 1 through k. |
/checkpoints [all] |
List current checkpoints, or all branches when all is
given. |
Undo and rewind report partial restores when something cannot be
captured or restored. External side effects are not generally
reversible. See ?gptr_rewind and
?gptr_security before relying on restoration.
In manual, known read-only actions and actions covered
by existing allow rules run directly; other changes ask for approval.
The prompt offers y for this action, a for a
session rule covering the flagged calls, n to deny, and
? for details. edits allows project file edits
while still asking about R changes unless an allow rule applies;
auto allows ordinary actions while retaining critical and
secret guards. plan offers read-only tools and level-1 R
exploration in a scratch environment, where intermediate bindings can
change while the user workspace is preserved. Settings and policies are
described in the configuration guide
and ?gptr_security.
While an answer or tool runs in a supported terminal, Ctrl-C opens a pause menu:
A foreground call, including a chat turn, can also offer
background when that experimental capability is
available. It returns to peter> while the run remains
active. Another prompt steers the running session;
!!gptr::gptr_wait(gptr::gptr_last()) waits for completion
without adding a code/output note to the next prompt. Returning to the
chat prompt does not guarantee progress while it waits for input. Under
Rscript, background runs advance only inside blocking gptr calls. Inline
R tools still occupy the same R process while they execute.
At the chat prompt, one Ctrl-C prints a hint; two consecutive interrupts leave the chat. IDEs that cannot resume an interrupted evaluation use an abort fallback; pause/resume behavior is not uniformly verified across front ends.
The equivalent session verbs work from R:
gptr_steer(s, "Use the existing fit instead of fitting again.")
gptr_steer(s, "Summarize the diagnostics at the end.", as = "follow_up")
gptr_wait(s)
gptr_cancel(s)For persistent conversation storage, initialize a project with
gptr_init(path) and review its trust decision.
gptr_sessions() lists stored sessions, and
gptr_resume(id) recovers one. The script-as-history guide covers
document recording, replay and transcripts; the language-model guide covers scripted
calls that need no interactive console.