peter(..., background = TRUE) returns the session at once while its run keeps going.
A timer from the later package advances the run every 50 ms while the R console is
idle, so you can keep working. Piping into the running session,
session |> peter("..."), queues a steer that the agent receives after its current
tool result; gptr_wait() waits for the session, gptr_cancel()
aborts its run and gptr_jobs() lists it. Background sessions are
experimental: they need the later package, and they are never used in
examples or in CRAN tests.
Background work is not an independent R execution thread: an inline R tool occupies the
process while it runs. Returning a session does not establish idle progress in an
unverified front end; inspect its status and use a blocking wait when needed.
How a background run behaves
Streams progress at every idle tick. While a blocking gptr call runs (
peter(),gptr_wait(),gptr_step()or a console turn), that call advances the background runs as well and the background timer does nothing.R tools of a background run execute at an idle tick when
options(gptr.background_tools = "idle")(the default). The console is busy while such a tool runs; Ctrl-C then opens the pause menu. With"wait"they run only inside a blocking gptr call such asgptr_wait().A background run never asks a question at the idle console. When it needs an approval or an answer at an idle tick, the action is not performed: the agent is told that the user will be asked, its run stops, and the session moves to status
"waiting"with a notice. At your nextgptr_wait(),peter()call or console turn the session continues with one more model request, the agent repeats the call, and you are asked as usual. A message piped into a waiting session is delivered when it continues.gptr_cancel()stops a running background session. A waiting session has no run to cancel:gptr_jobs(kill = TRUE)stops it (together with every other job).When an R tool changed objects in your workspace at an idle tick, one notice names them.
Under Rscript, knitr and Quarto there is no idle console: background runs progress only inside blocking gptr calls.
Support matrix
| Front end | Status |
| Terminal R on macOS | verified: idle ticks, pause menu, pipe steering |
| Terminal R on Linux | unverified (the same later event loop as macOS) |
| Rscript, knitr, Quarto | no idle ticks by design; progress inside blocking gptr calls |
| RStudio | unverified (later is expected to run callbacks at its idle console) |
| Positron, Jupyter (IRkernel), Rgui | unverified |
| Windows consoles | unverified; a timer polls the reactor, so child pipes are served |
Options
gptr.background_tools"idle"(default) or"wait": whether R tools of background runs execute at idle ticks or wait for the next blocking gptr call.