Working with agents
Agents run code in your console with corral eval, so their objects, plots and tables land in the session you are looking at. Claude Code learns how from Corral's skill.
corral eval
corral eval runs code in your console and prints what it printed. R is the default; --lang python runs Python, and starts the Python console if it isn't there yet. You see each command appear in the console after a # corral eval line, and the objects, plots and tables stay in your session.
It works from any terminal or script, too:
$ corral eval 'summary(mtcars)'
$ corral eval --file analisis.R
$ corral eval --lang python 'df.describe()'
$ corral vars --json
It also reads the code from stdin. If the console isn't there, isn't in view, or was quit, corral eval brings it into view or starts it first.
What comes back
The code, echoed (> in R, >>> in Python), followed by what it printed. In R every top-level value prints, messages included, and warnings come after the output as [corral] warning: .... In Python, as in IPython, only the value of the last expression prints.
Output longer than 20,000 characters is cut in the middle, and the path to the full text is printed. --max-chars changes that limit.
| Exit code | Meaning |
|---|---|
| 0 | It ran without errors. |
| 1 | Error. The message is the last line; statements before the failing one already ran. |
| 2 | The console was still busy after --wait-idle, it had a half-typed line, or --timeout ran out (the code may still be running). |
Plots
Each new plot is saved as a PNG and reported as [corral] plot N saved to <path>, numbered as you see it in Mirador. That way the agent can look at what it drew.
Claude looks at each plot it draws, and sometimes fixes it: it moves labels or changes a scale. So that you don't end up with near-identical versions in Mirador, the fix goes with corral eval --replace, and the new plot replaces the ones from the previous request. If you ask for a different plot, or want to compare versions, it is added to the history as usual.
Waiting and taking turns
If the console is busy, corral eval waits up to 20 seconds (--wait-idle). If you have a half-typed line, it runs nothing and says so. Several agents can use the same console: their requests run one at a time.
--timeout (300 seconds by default) is how long it waits for the result. After that, it exits with code 2 and the code may still be running. A request the console only reaches after its agent gave up doesn't run at all.
Check the console
$ corral eval --check
$ corral eval --check --lang python
With a console, it prints the console and its session as JSON: the pane, the language, the session, the R or Python version, the folder, and active, which says whether that console is the one in view.
Options
| Option | What it does |
|---|---|
--lang r|python | The console to use (r by default) |
--file FILE | Run a file |
--timeout S | Seconds to wait for the result (300) |
--wait-idle S | Seconds to wait for a busy console (20) |
--max-chars N | Longest output before it is cut (20000) |
--check | Only check the console |
--replace | Its plots replace the ones from the previous request |
Corral's skill
Corral's skill, skills/corral-r in Corral's folder, follows the open Agent Skills standard. The installer links it into ~/.agents/skills/corral-r, where Codex and other agents look for skills, and into ~/.claude/skills/corral-r for Claude Code. With it, Claude runs its code in your console instead of opening an R or a Python of its own. It switches on when Claude works inside herdr and a Corral layout exists.
What it does
- It checks first, with
corral eval --check. If there is no R console, or Corral isn't active in it, it tells you that ctrl+b a opens one and ctrl+b m switches Corral on in an R you already have. For Python, no console yet is normal: its first request starts one. - It looks before it runs, with
corral vars --json, so it uses your object names and doesn't overwrite your objects. - It runs code with
corral evaland reads the PNG of each plot before it describes or adjusts the plot. It uses--replaceonly to fix a plot its own previous request drew. - It keeps the output small (
head(),str(),summary(),df.head()), and does scratch work inlocal({ ... })in R, or in a function in Python, so your environment stays clean. - To show you a table, it runs
View(df)throughcorral eval, and the table opens in your viewer. - When you ask, it rearranges the panes (
corral toggle,corral switch), and reads or changes your shortcuts (corral keys).
What it asks before doing
- Anything destructive or global:
rm(list = ls()),q(),setwd()oros.chdir(), resettingoptions(), installing or removing packages (uv addchanges your project), overwriting an object you created, writing files outside the project. - Changes to what you see: adding the editor (
corral script), opening the variables window, opening a new layout and, always, closing Corral (corral close). - Replacing your draft, or saving it. It never saves the draft on its own initiative.
- Taking a key from another shortcut (
--force). - Using
Rscriptor a separate Python when your console isn't available.
It never types keys into your console. If the console has a half-typed line, it asks you to finish or clear it.
It still uses Rscript or a separate Python for package checks (devtools::test(), R CMD check, pytest), and for work you want kept apart from your session.
Agents in your draft
$ corral script --read
$ echo 'modelo <- lm(mpg ~ wt, data = autos)' | corral script --write
$ corral script --save analisis/modelo.R
--read prints the draft, unsaved edits included. --write adds text at the end, as one edit you can undo with Ctrl+Z; with --replace it replaces everything. --save writes the draft into your project, and refuses to replace a file unless you add --force. The script editor has the details.
Without a Corral console
Claude uses your console only if the workspace has an active Corral console. Otherwise, it works as usual. If Claude opens its own R instead of using yours, corral eval --check should answer with your console; if it doesn't, switch Corral on in that R with ctrl+b m.