Interactive console

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. A path of letters and digits in any script, ., _, -, ~ and / needs no quotes; quote any other path, such as @"analysis notes.txt" (Tab leaves the quotes to you). When no file or object has the whole name, a mention reads its leading ASCII letters, digits, ., _, -, ~ and /, so @x may run into text written without spaces. A mention is a word that starts with @, so me@example.org stays text. Files take precedence when a mention matches both a file and an object. A file mention sends at most its first 40 lines, and the files of one prompt share about 2,000 tokens; binary files contribute a description rather than their contents. For a larger file, ask the agent to read the relevant section. Under the prompt you send, a dim line says what each mention attached, such as @ mtcars (data.frame, 32 x 11) or @ analysis.R (first 40 lines), or that a name was not found and was sent as text.

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.

Tab completes only after @ (objects, then files), @obj$ (its members), peter$, a leading / (commands) and on a ! or !! line (R code), never in plain text. This holds in terminal R, R in an IDE’s Terminal tab, Windows’ Rgui and Rterm, and RStudio’s console, which completes only what its popup inserts as offered: the commands after / and R code after !, not words holding @ or $, which it would wrap in backticks. In a terminal Tab completes a draft typed while Peter works the same way. R.app, radian and Positron’s console keep their own completion. gptr never changes RStudio’s preferences: as you type in its console, RStudio adds closing brackets and quotes unless insert_matching is off, and opens completions unless console_code_completion is off (Tools > Global Options > Code).

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. A fence marked r, R, {r} or unmarked behaves like !code; any other fence, such as one marked python, is sent as prompt text. 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.

In CRAN’s R for macOS in a terminal a pasted block is one input: its lines join the first one and ... waits for Enter, where text you type is added. A pasted fence or """ block is read up to its closer at once, a block pasted at an approval or a choice is kept in the console history and the question asked again, and one pasted at the pause menu’s ? Steer or ? Follow-up is the whole text. A last pasted line without a newline waits for Enter at the next prompt, so a two-line paste without a final newline answers a question with its first line. Homebrew or conda R, Linux terminals, RStudio, R.app, Positron and Windows deliver pasted lines one at a time, as typed lines (at a question the first one answers it), so wrap a multi-line paste in """ there. Lines typed, pasted or run from a script before a question appears (an approval, a choice) never answer it: while an answer runs they are queued for the agent as type_ahead says (a /command or !code line waits for the next prompt), otherwise they go to the console history. Answer after the prompt.

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.

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 changes

In manual, known read-only actions run directly and changes ask for approval under the call they gate, unless a permission rule applies (an allow rule never approves a critical action); you type the answer on the row below. The question lists the flagged calls, riskiest first (at most five; ? shows all), and offers y for this action, a for a session rule covering them when one can be written (p for the same rule in this project), n to deny, and ? for details. n <text> (or no, <text>) denies the action and gives the agent your text as its instruction. A sub-agent’s question names it (? sub-agent A: allow r?); an answer that is none of these is explained, and five such answers refuse the action. 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 R calls known to be read-only 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.

Type while Peter works

A message you type while Peter works is queued as one of two kinds. A steer reaches the agent at its next step boundary: when the response in flight ends, after the results of all its tool calls. The agent reads it on its very next request, and an answer that was about to end gets one more request; a steer never interrupts a request or a tool. A follow-up waits for the whole answer and is then sent as the next prompt, its own run. What you type, and the key that pauses Peter, depend on the console:

In terminal R and an IDE’s Terminal tab what you type is a draft on the bottom row, under the transcript, so it never mixes into the answer; a block pasted there is one message where the terminal supports bracketed paste. The row also shows what Peter is doing and how many messages are queued. Enter sends the draft as a steer, and it shows as your own line where the agent reads it. Tab sends it as a follow-up, which appears at the next peter> prompt. With gptr_config(type_ahead = "follow_up", .scope = "user") the two keys swap. A draft that starts with / or ! is always a follow-up: /commands and !code run at the next prompt, in the order typed. Up on an empty draft takes back the newest message not yet delivered, to edit and send again; Ctrl-U clears the draft. A recording document keeps what you sent, steers included (Record, replay and export).

A question (an approval, a choice) waits until you stop typing for a second, or three seconds while the draft has text, so a key meant for the draft never answers it. The draft stays through questions, through Ctrl-C and the pause menu, and to the next prompt, where Enter sends it. Keys typed while R code runs in this R process (the r tool) show when it returns. A steer the answer did not take (it ended first) is the next prompt. After an abort or an error nothing you queued is sent: the queued text and the draft go to the console history, and Up recalls them. On the CLI routes (claude-cli, codex) the agent reads a steer after the CLI’s answer, which is often the whole run.

RStudio, R.app, Positron and Windows consoles hold what you type until R reads again, so gptr cannot read it while Peter works:

• In RStudio, R.app and Windows consoles a line typed during an answer is the next prompt, one prompt per line, unless a question comes first: the question reads the line, queues it as type_ahead says and asks again. RStudio hides such a line at its next output, and its bottom row says typed lines run next.
• Positron’s console keeps typed text as R code, which runs after peter() returns, and clears it at Ctrl-C.
• To steer in these consoles, pause and press s (Windows’ Rgui cannot pause). In RStudio an Esc first closes RStudio’s own completion list, if open, then clears a line being typed, so the menu comes at the next Esc.

During peter("...") at R’s prompt, outside the chat, typed lines stay R’s next input in every console.

Pause, continue and leave

The pause key opens a pause menu while an answer or tool runs:

• s steer asks for a new instruction and delivers it at the next step boundary.
• f follow-up queues a prompt: in the chat it is the next prompt, sent once the answer ends; in a peter("...") call it is sent when the agent would otherwise stop.
• c continue resumes the work as if it had not paused.
• a abort stops it and retains the partial session; what you queued and the draft go to the history, unsent.
• b background, for a foreground call (a chat turn included) when that experimental capability is available, returns to peter> while the run goes on.

A key typed right after the pause key answers the menu, and pressing the pause key again aborts. After background, what was queued for after the answer and the draft go to the history, unsent, as after an abort. 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. Where an interrupt cannot be resumed (Windows’ Rgui, Jupyter) the key stops the answer instead. In a terminal the chat reads keys with the echo off and restores it when it returns, on an error, at an interrupt and at q(). If R is killed or crashes while Peter works, type reset and press Enter to get the terminal back, its echo and its paste mode.

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