repld

A live Python kernel for your agent. Shared namespace, channel push, a scriptable browser, and one-off code that hardens into tools.

uv tool install repld-tool

What it does

• Persistent kernel — one long-running Python process in your project directory. State survives across turns.
• Shared namespace — you and the agent operate on the same __main__. Inspect its variables, patch its functions, take over mid-task.
• Channel push — long jobs, timers, file watchers, and webhooks push back as notifications. The agent reacts; it never polls.
• Browser — attach to your logged-in Chrome via CDP. Every mutation settles, then returns the accessibility tree, network delta, and console delta.
• Gists — plain Python files the kernel hot-reloads. Reverse-engineer an API once, import it forever, link it across projects, register it as an MCP tool.

Install

uv tool install repld-tool        # global install (recommended)

cd your-project
claude mcp add repld -- repld bridge   # register it with the client

# channel push is a research preview, so it takes a development flag
claude --dangerously-load-development-channels server:repld

You don't have to start the kernel yourself: repld bridge spawns a headless one for the project if none is running, and restarts it if it dies. Run repld in a terminal when you want the live display instead — either way, repld log -f tails it, repld status shows what's running, and repld stop shuts it down. Runtime state lives under $XDG_RUNTIME_DIR/repld/, so nothing lands in your project directory and there's nothing to .gitignore.

Coming from 0.1.x, that last part is new, and the files the old version wrote into your projects are still there — see Upgrading to 0.2.

For browser integration, start the kernel with repld browser instead of repld — it re-execs under uv run with the browser extra (duckdb, websockets, pillow) for that invocation, so no project changes are needed. Or install the extra permanently with uv tool install repld-tool[browser].

Quick example

# runs inline — result returned immediately
import httpx
httpx.get("https://api.example.com/status").json()

# long-running — returns task_id, pushes channel notification on completion
await asyncio.sleep(30)
notify("done", kind="migration")

Autonomous worker:

@every(300)
async def check_overdue():
    for inv in await erp.get_overdue():
        notify(f"Overdue: {inv.customer} — {inv.amount}",
               kind="overdue", invoice_id=inv.id)

The kernel runs the watcher; the agent reacts to each channel notification.

With an existing app

repld inherits your project's environment. A repld_init.py at the project root is executed into __main__ when a kernel boots — by every kernel for that project, including the headless one the bridge starts for you:

from myapp.main import app
from myapp.db import async_session_maker
import asyncio, uvicorn

asyncio.create_task(uvicorn.Server(
    uvicorn.Config(app, host="127.0.0.1", port=8000, log_level="warning")
).serve())

session = async_session_maker()
print("FastAPI on :8000, db session ready")

Nothing to pass — open claude (or run repld for the live display) and the agent has a live handle on your running app: inspect routes, query the ORM, call handlers directly.

Tools

Core:

repld_restart is served by the bridge rather than the kernel, since a kernel can't answer "restart yourself" without the reply dying in flight.

Browser (run repld browser instead of repld, or uv tool install repld-tool[browser]):

Output from every cell spills to $XDG_RUNTIME_DIR/repld/ — the inline response carries a head/tail preview plus the spill path. Use standard Read/Grep tools for full output.

Kernel builtins

notify(content, **meta)              # channel push to the agent
await ask(prompt)                    # block on free-form human input
await confirm(prompt)                # block on yes/no
await choose(prompt, options)        # block on pick-one
defer(coro, label=None)              # fire-and-forget, channel push on completion
@every(seconds)                      # periodic ticker, fn.cancel() to stop

A kernel you started with repld takes gate answers in its own pane, and a pinned browser tab takes them through its pill. The headless kernel the bridge spawns has neither, so it says so in the notification — repld gate lists what's pending and repld gate answer <id> <value> resolves it.

Browser

repld[browser] attaches to Chrome via CDP (--remote-debugging-port=9222, Chrome 140+). You log in normally; the agent sees your traffic, discovers the API surface, and works with your authenticated sessions.

tab = await browser.get("*example.com*")     # find tab by URL glob
tab = await browser.open("https://...")      # open new tab
await browser.watch("*pattern*")             # auto-attach matching tabs

await tab.js("document.title")               # eval JS (top-level await works)
await tab.fetch("/api/data")                 # in-page fetch (inherits session)
await tab.click("#submit")                   # click, settle, return observation
await tab.type_text("#search", "query")      # type into element
tab.network(url="*api*")                     # query captured traffic

Body capture via Fetch interception means login flows, redirects, and CSRF exchanges are never lost. See docs/browser.md for the full design.

Gists

Gists are Python modules in ./gists/ (project) or ~/.repld/gists/ (global) that wrap anything into a callable API. The browser supplies auth; the gist captures the pattern.

# gists/myapp.py
"""MyApp — accounts and transactions."""

class MyApp:
    def __init__(self, tab): self._tab = tab

    @classmethod
    async def connect(cls):
        from __main__ import browser
        tab = await browser.get("*myapp.com*")
        return cls(tab)

    async def accounts(self):
        return (await self._tab.fetch("/api/accounts"))["body"]

from myapp import MyApp
app = await MyApp.connect()
await app.accounts()

Re-importing after edits auto-reloads. Gists can declare dependencies (__repld_deps__), register MCP tools (typed _tool_* functions, with Annotated[T, "..."] for per-parameter descriptions), and link across projects (repld gist add <name>). repld gist fetch <gist-url> copies someone else's gist in, and repld gist lint checks all of it. See repld help gists for details.

Scope

repld executes arbitrary Python in your project environment. It is a dev-time tool — never a runtime dependency. The IPC socket is localhost-only with user-only permissions.

Channel push is a research preview, so it takes a development flag: claude --dangerously-load-development-channels server:repld.

License

MIT