Pairing with an AI agent

Step 1: Open the starter page

The page below has a heading, a green badge, a list and a script that writes a line to the console. Its <style o:=.css> element is an exported file, which you will meet again in step 3. Select Open in RTCode.io to open the page in a tab of its own.

<style o:=.css>
  :root    { color-scheme: light dark; }
  main     { display: grid; gap: 1rem; padding: 1rem; }
  #badge   { justify-self: start; padding: .25rem .6rem; border-radius: 1rem; background: oklch(.75 .15 150); }
</style>
<main>
  <h1>Pairing demo</h1>
  <span id=badge>new</span>
  <ul id=list><li>One<li>Two<li>Three</ul>
</main>
<script>
  console.log('page ready', document.querySelectorAll('#list li').length)
</script>

Step 2: Share a folder

Press Alt+A / ⌥+A, or choose Share in the Agent section of the Code menu. The Code menu is the logo button at the far left. The first time, the browser's folder picker opens. Choose or create your RTCode folder, and allow the browser to edit files in it. This folder is the root. You pick it once, and the browser remembers it.

The playground now creates the work folder inside the root. A playground without a route shares into a folder named Unrouted. Open a terminal there and look at what the share wrote:

cd ~/RTCode/Unrouted
ls -A

Step 3: Let the agent edit the page

Start your agent in the work folder. AGENTS.md is for Codex and other agents that read AGENTS.md, and CLAUDE.md is for Claude Code. They are identical copies of the current RTCode.io agent guide, which describes the files that the share creates. If your agent does not read the guide by itself, tell it to. Then give it a task:

Read CLAUDE.md first. Then add a fourth item, Four, to the list in 📄.html and make the heading dark green in .css. Do not touch anything else.

Name AGENTS.md instead of CLAUDE.md in the prompt if your agent reads that file. The agent edits 📄.html for the list. For the heading it can edit .css, which is the <style> element as a separate file. File Sync keeps both files and the editor in sync, so the agent can make a focused change without rewriting the page. See File Sync.

Step 4: Read the console

The starter page logs a line when it runs. Press F5: this forces a full refresh of the output from the input, so the script runs again. Then ask the agent what the console says. It reads the console file like this:

cat 📜.json*

The pattern 📜.json* matters. While you share, Chromium keeps the live console data in the swap file 📜.json.crswap, and 📜.json itself stays empty until you unshare. Every console call from the output is one JSON line, { "<method>": [ …arguments ] }.

Step 5: Show the agent a screenshot

An agent can look at the output through 📸.png, which exists while a screen capture runs. Click the editor, then press Ctrl+Alt+Shift+C / ⌘+⌥+⇧+C (Capture (output)). In the browser's dialog, choose this tab. Then ask your agent:

Look at 📸.png and tell me what color the heading is.

The playground refreshes 📸.png after edits that reach the output, after evals and when the output scrolls. An agent that wants a fresh picture can delete the file, and the playground takes a new one. Next time, Ctrl+Alt+A / ⌘+⌥+A (Share + 🔴 Output…) shares and captures in one step. See Screen capture.

Step 6: Leave a pin for the agent

A pin points at a part of the output and carries a comment. Press Ctrl+P / ⌘+P. The Pins panel opens at the bottom right and picking starts. Click the green badge in the output. The comment field in the new row of the panel has the focus, so type Make this pill smaller. To stop picking, click ⏸️ in the panel header, or press Ctrl+Alt+Shift+P / ⌘+⌥+⇧+P. Then ask your agent:

Read the pin files in this folder and do what the comment asks.

The agent reads 📍.0.json. Because the Output capture from step 5 runs, there is also 📍.0.png, a crop of the badge. This is the file, abridged:

{
  "version": 1,
  "type": "rtcode.pin",
  "id": "pin_mutrqtc0_a1b2c3",
  "image": { "file": "📍.0.png", "capture": { … } },
  "pin": {
    "kind": "element",
    "selector": "span#badge",
    "comment": "Make this pill smaller",
    "outerHTML": "<span id=\"badge\">new</span>",
    "linked": true
  }
}

The pin is linked to the badge, so its mark follows the element when the page changes. Edits to the pin files have no effect while the share runs: pins change through code, as step 7 shows. See Pins and comments.

Step 7: Run code in the playground

Agents control the playground by writing JavaScript to a request file and reading a result file. io.eval.js runs in the playground, and o.eval.js runs in the output. Ask your agent:

Use io.eval.js to tell me which routes this playground has, and use o.eval.js to list the headings in the output.

The agent should write a request in one piece, wait until the request file disappears, which means that the playground accepted it, and then read the result. This is what that looks like in a shell:

printf '%s' 'Code.D' > io.eval.tmp && mv io.eval.tmp io.eval.js
while [ -e io.eval.js ]; do sleep 0.05; done
until [ -e io.eval.json ] && [ ! -e io.eval.json.crswap ]; do sleep 0.05; done
cat io.eval.json

For the output, the request is JavaScript that returns plain data. This one lists the headings with their boxes:

[...document.querySelectorAll('h1, h2')].map(h => ({ tag: h.localName, text: h.textContent.trim(), box: h.getBoundingClientRect().toJSON() }))

Evals can also answer your pin. This request replaces the pin's comment with a reply, hands the output back to you, and returns a short summary:

await o.pins.setComment('Done: the badge is smaller now.', 0);
await o.pins.pause();
o.pins.map(p => `${p.index} ${p.kind} ${p.label}: ${p.comment}`)

Pin calls open the Pins panel and turn picking on, so pause() gives the output back to you. Write one request at a time, and wait for its result before the next. See File evals.

Step 8: End the share

First stop the screen capture that you started in step 5, with 🔴 ⏹️ Capture: Stop from the command palette (F1) or the Capture section of the Code menu. Stopping a capture deletes the pin images, 📍.0.png, and rewrites the pin JSON files without image references. Then choose Unshare in the Agent section of the Code menu, or run ✨ Agent: 🗂️ Unshare. Unshare leaves the other files in the folder and closes the console writer, which commits 📜.json. It stops a screen capture too, but only one that the share itself started.

cat 📜.json

Summary

• Agent 📂 Share™ connects a playground tab to a work folder inside a root folder that you pick once.
• The share writes AGENTS.md and CLAUDE.md, so Claude Code, Codex or any agent that reads those files knows the rules.
• File Sync maps 📄.html, exported files and workers to files that sync both ways.
• The agent reads the console with cat 📜.json*, and the output through 📸.png while a capture runs.
• Pins hand the agent elements and regions with comments, as 📍.<N>.json files.
• Evals run code in the playground or the output: write the request in one piece, wait, read the result.
• Unshare keeps the files.

Next steps

Agent 📂 Share™

Auto-Share, Share ← Folder, Explore, reload recovery and the cautions.

Agent files

Every file in the work folder, who writes it and its format.

File Sync

File names, content, conflicts and the Files differ dialog.

File evals

The request and result protocol, return values, timeouts and the diagnostics command.

Pins and comments

Picking, marks, the panel, image options and o.pins.

Screen capture

Capture kinds, screenshots, video and picture-in-picture.

Deploying

Publish your page, which an agent can also do with edge.save.limit().

See also

• Getting started
• Agent 📂 Share™
• Commands
• Keyboard shortcuts
• Browser support
• Troubleshooting