Interactive console

Call peter() without a prompt from an interactive R console to chat. It uses your current environment and the configured model. Choose a route explicitly with peter(model = "openai/gpt-6-sol"). Language models covers API, CLI and local setup.

On a new console with no explicit or configured model, Peter first offers the Codex CLI, the 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.

library(gptr)
session = peter()
# At peter>, enter: Plot mpg against wt in mtcars.
# Then enter: /exit

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 session. 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 model 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.

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.

Continue the same session from R:

session |> peter()
# At peter>, enter: Explain the pattern in that plot.
# Then enter: /exit

Piping uses the session’s kept workspace. To explore independently, use gptr_fork(session) |> peter(); writes stay in the fork’s overlay. /clear resets the conversation while retaining workspace objects, model and mode.

Enter prompts, objects and your own R

Ask in ordinary language. @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 terminal R with readline, Tab completes R names and file paths after ! and !!; other front ends keep their own completion.

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.

Commands

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.

Approve, interrupt and continue

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 Configuration and ?gptr_security.

While an answer or tool runs in a supported terminal, Ctrl-C opens a pause menu:

• Steer delivers a new instruction after the current tool results.
• Follow-up queues a prompt for when the agent would otherwise stop.
• Continue resumes the current work.
• Abort stops it and retains the partial session.

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 interrupt prints a hint; two consecutive interrupts leave the chat. Use Ctrl-C in a terminal and the front end’s interrupt key in an IDE: Esc in RStudio, R.app, RGui and Positron. 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(session, "Use the existing fit instead of fitting again.")
gptr_steer(session, "Summarize the diagnostics at the end.", as = "follow_up")
gptr_wait(session)
gptr_cancel(session)

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. Script as history covers document recording, replay and transcripts; Language models covers scripted calls that need no interactive console.