Exec & channels
exec(code, timeout=2.0)Execute Python in the shared __main__. Returns inline within timeout; otherwise returns the line [task <id> still running after <timeout>s; completion will arrive via channel], followed by any output so far, and pushes a channel notification on completion.
The result is text. The task id is in that line, not a field, and a value is shown as its Python repr, so print(json.dumps(x)) when the caller will parse it. One session’s calls (exec, get_task, cancel, gist and browser tools) run one at a time on its connection: concurrent calls run in sequence, and an exec with a long timeout holds the others until it returns.
Code Mode sessions
Section titled “Code Mode sessions”REPLD_CODE_MODE=1 in the bridge’s environment, read once at bridge start, shapes that session’s exec results for a script instead of a reader (Claude Code’s Code Mode, where a script calls await mcp__repld__exec({code})):
| Result | Unset | REPLD_CODE_MODE=1 |
|---|---|---|
| A cell’s value | Python repr | JSON when json.dumps accepts it, else the repr |
| No output, no value | (no output) | null |
Cell past timeout | the [task <id> ...] line | the JSON text {"task_id": "...", "done": false}, nothing else |
| Output past the preview size | head+tail preview and the path | {"truncated": true, "spill_path": "/path", "bytes": N} |
| cancel | cancel task=<id>: accepted | {"task_id": "...", "cancelled": true} |
A cell that raises is the same in both: the call fails with the traceback text. get_task, cancel and gist tools answer such a session in JSON text alone, with no structuredContent and no outputSchema in tools/list, because a script receives structuredContent as a string and JSON text as an object. A gist tool’s output past the preview size is the same {"truncated": true, ...} pointer. The browser_* tools stay prose meant for a model; a script that wants browser data calls exec on the browser object ((await browser.get('x')).network()) and gets a JSON value. print() output is untouched, so a cell that prints and also returns a value is still mixed text.
To await a backgrounded cell from a script, run repld tasks wait <task_id> --json through its shell helper (with --project DIR first when outside the project). It blocks until the task ends, exits 0 (1 if it raised) and prints the get_task snapshot, where text is the output preview: parse it, or read spill_path when truncated is true.
The variable is a promise by whoever sets it. repld cannot see whether Code Mode is really on (Claude Code can refuse it at start-up with the variable set), and an ordinary session with it set is shown {"task_id": ..., "done": false} with no sentence. Set it only for an interactive Code Mode launch, never for claude -p or --bg.
Output spills to $XDG_RUNTIME_DIR/repld/{pid}-{tid}.out from byte 1. The inline response carries a head+tail preview and the spill path.
Result history
Section titled “Result history”| Variable | Description |
|---|---|
_ | Last result |
__, ___ | Previous two |
_N | Result of cell N |
Top-level await is supported, and it decides where the cell runs. A cell with a top-level await runs on the kernel’s shared loop, so sync I/O in it (a big file read, requests.get) stalls every session and cell until it returns, and triggers loop_blocked. A cell without one runs in a worker thread, where the same sync I/O stalls nothing.
no_display
Section titled “no_display”no_display(value) → valueReturn a value from a cell without the auto-display hook re-printing it — still binds _/_N, and still unwraps on direct assignment (x = no_display(await foo())). For functions that already print their own output.
defer(coro, label=None) → task_idFire-and-forget. The coroutine runs in the background; a task_done channel notification pushes on completion. Visible to get_task and cancel.
@every
Section titled “@every”@every(seconds, label=None, delay=0, tab=None)def fn(): ...Periodic ticker. The first tick runs immediately unless delay= holds it back — use that when you’re watching something you just started, or the first check races its warmup and a false negative sends the ticker after something that was about to be fine. The decorated function gets a .cancel() method. Errors don’t stop the ticker — they push an every channel notification with the traceback.
tab=<pattern> resolves browser.get(pattern) fresh on every tick and passes the live Tab to fn, so a ticker acting on a browser tab across hours or days doesn’t need a captured-once Tab that goes stale across a navigation or crash. A missing match errors that tick but the ticker survives, and self-heals once a matching tab reappears. Registering with tab= on a kernel with no browser builtin refuses immediately rather than erroring on every tick forever.
A ticker outlives the cell that registered it, so its output is ambient: rendered unattributed and uncapped, not charged against that cell’s budget.
every.list() # active EveryHandlesevery.cancel_all() # stop all tickersnotify
Section titled “notify”notify(content, *, session=None, exclude=None, **meta)Push a channel notification to the agent. Metadata appears as extra fields in the notification payload.
session=<claude_session_id> targets one connected Claude Code session instead of broadcasting — returns True if delivered, False if that session isn’t connected (no fallback to broadcast). exclude=<claude_session_id> — only meaningful with session left at its default — skips that one session from an otherwise-broadcast push, e.g. a self-report whose caller already has the result synchronously and doesn’t need it echoed back.
claude_sessions() → [(claude_session_id, project_dir, kind), ...]current_session_id() → str | Noneclaude_sessions() lists every connected MCP session. kind is "bg" for a claude --bg worker, else None. current_session_id() returns the id of whoever triggered the code currently running — the same id notify()’s session=/exclude= take — or None with nothing to attribute to.
The id is read once from CLAUDE_CODE_SESSION_ID when the bridge starts. A claude --resume or --continue pane can carry a throwaway id there, and nothing on the MCP wire names the resumed conversation, so a SessionStart hook (source resume or clear) must re-key it: repld rebind does it from the hook payload ({"matcher": "resume|clear", "hooks": [{"type": "command", "command": "repld rebind"}]} under hooks.SessionStart), or call ipc.rebind_claude_session(new_id, pid) directly.
Human gates
Section titled “Human gates”await ask(prompt, *, tab=None, default=None, timeout=None, secret=False) → strawait confirm(prompt, *, tab=None, default=None, timeout=None) → boolawait choose(prompt, options, *, tab=None, default=None, timeout=None) → strtab= routes the gate to a pinned tab’s pill (requires tab.pin()); ask accepts it for symmetry but the pill has no text input. Without a default, an expired timeout raises TimeoutError.
These block the exec until a human responds. There are exactly three answering surfaces, and they race — first to resolve wins:
- The kernel’s own pane, if you started it with
repldand it has a terminal. - A pinned browser tab’s pill UI, for
confirmandchoose(the pill is a row of buttons with no text input, so anasknever renders there). repld gate answer <id> <value>from any terminal.
The third is the one that always exists. Since the bridge spawns kernels lazily, the common kernel is headless with no pane at all — so when there’s no terminal and no pill, the awaiting_human push carries the literal command to run:
repld gate # list what's pendingrepld gate answer g3f2a1 yesrepld gate answer g3f2a1 deploy now # free text, no quoting neededy/n, an option name, and a 1-based option number all mean the same thing whichever surface answers. Pass timeout= to stop a gate parking a cell indefinitely.
Gates are deliberately not MCP tools — an agent able to answer its own confirm() defeats the primitive.
Channel notification kinds
Section titled “Channel notification kinds”| Kind | Source |
|---|---|
task_done | exec or defer finished |
every | periodic tick result or error (label in meta) |
awaiting_human | ask/confirm/choose/form pending (carries the answer command when headless) |
bg_task_error | uncaught exception in background task |
loop_blocked | asyncio loop blocked > 5s |
loop_kill | watchdog cancelled the task holding the loop |
loop_unblocked | a reported block ended |
init_loaded | repld_init.py ran at boot — __main__ is pre-populated |
init_error | repld_init.py raised |
venv | a project venv was adopted onto the running kernel |
kernel_started | the bridge’s lazy spawn landed; the full tool list follows |
kernel_crashed | the kernel died without a goodbye; __main__ is gone |
console_error | console.error or uncaught exception on a tab you claim |
pin_lost | a pinned tab navigated cross-origin |
controls | window.controls action observation |
dialog | native JS dialog answered, or waiting for the human |
filechooser | native file chooser opened: resolved (pre-armed) or left open |
captcha | a captcha needs a human, or was solved |
auth | HTTP auth challenge cancelled (no pre-arm) or left to Chrome’s prompt |
download_started / download_done / download_canceled | a download on a tab you claim |
tab_crashed | a tab’s renderer crashed; navigate or reload revives it |
tab_closed | a tab you claim was closed from outside repld |
browser_disconnected | a url= browser was retired (reason in the text); broadcast |
browser_reconnected | Chrome reconnected and some tabs were lost; broadcast |
browser_warning | a drag endpoint was occluded |
browser_connect / browser_disconnect / browser_watch / browser_unwatch | dashboard browser actions |
loop_blocked fires once a probe on the kernel loop misses REPLD_LOOP_BLOCK_THRESHOLD (default 5 s). It names the task holding the loop and the top of its stack, led by a blocked at: line naming the innermost frame outside the stdlib and installed packages (the call that chose to block), and a loop_unblocked with blocked_s follows when the block ends. Past REPLD_LOOP_KILL_THRESHOLD (default 30 s; 0 disables) the watchdog asks that task to cancel. The cancel can’t interrupt synchronous code; it lands at the task’s next await.
A bare notify("...") carries no kind at all — meta is whatever keywords you passed. Pass kind= yourself if you want to filter on it.
A task’s completion is pushed to the session that started it; ambient output (@every, browser connect/disconnect, bare notify()) is broadcast. Console errors and controls observations go to the session that last drove that tab, and loop_blocked/loop_kill/loop_unblocked to the session whose task holds the loop; both broadcast when that session is gone.
get_task / cancel
Section titled “get_task / cancel”get_task(task_id) → {done, text, spill_path, ...}cancel(task_id) → {cancelled: bool}The snapshot’s push_delivered is true/false once a completion push was sent to the session that started the task, and null when none was owed. false means that session had disconnected, so nobody has seen the result.
cancel only works on await-yielding code — tight sync loops (while True: pass) can’t be preempted.
A session that ends its turn does not reliably see a later channel push: a one-shot client (claude -p) never does, and an idle claude --bg worker is woken only without bypassPermissions and before the host retires the idle job. If you need a deferred task’s result, poll get_task(task_id) yourself in a loop before ending your turn rather than trusting the push to bring you back.
From a terminal instead of the agent, repld tasks wait <task_id> blocks on the same task and exits 0 on success or 1 on an exception or unknown id; repld tasks cancel <task_id> is the CLI face of cancel, exiting 0 if accepted. repld tasks alone lists every in-flight task and ticker.