Peers API
Finding peers
Section titled “Finding peers”peers.list() # [{name, cwd, pid, socket_path, started_at, self}]peer = peers.get(target) # a path, or the basename of one live kernelpeer = peers.get(target, start=True) # a call may start it if it is not runningpeer = peers.get("host:target") # the same on another machine, over sshpeers.get is synchronous. target is a path (it contains a / or starts with . or ~) or a bare name that matches exactly one live kernel’s directory. The handle is cached per project directory. "host:target" names a kernel on another machine: host is anything ssh accepts and target is resolved there.
The handle
Section titled “The handle”peer.cwd # the resolved project directorypeer.name # its basenamepeer.start # whether a call may start itpeer.host # the ssh destination of a remote peer, else None
await peer.call(target, /, *args, **kwargs) # the JSON value the target returnedawait peer.info() # identity and callable surfaceawait peer.inspect(target) # what a name resolves to; runs nothingtarget is positional-only, so a remote parameter may itself be called target. There is no timeout=: use asyncio.timeout().
info() returns {peer_protocol, kernel, gists, main}: kernel has cwd, pid, socket, started_at, python and venv; gists lists each public gist with its functions’ signatures; main lists callables defined in its __main__.
inspect() returns {target, kind, signature, async, doc, module, file}.
Errors
Section titled “Errors”All derive from PeerError and are also attributes of peers.
| Error | Meaning | Ran? |
|---|---|---|
PeerNotFound(candidates) | A name that matches no live kernel, or several | no |
PeerUnavailable | No kernel there, or it predates peers | no |
PeerRefused(reason, code, data) | Declined before running; reason is unresolved, bad_args, cycle, depth or self | no |
PeerCallError | The target raised, or its result cannot travel; has remote_type, remote_message, remote_traceback, output, spill_path, task_id | yes |
PeerDisconnected(clean) | The connection ended before an answer; clean means the peer said goodbye first | unknown |
Inside a called function
Section titled “Inside a called function”import repld
repld.peer_caller() # dict | None: kernel, claude_session_id, project_dir, session_kind, task_id, chain, pid_verifiedCommands
Section titled “Commands”repld gist stub <peer> <gist>[.fn,...] [--as NAME] [--global] [--start] [--force]repld gist stub --check [NAME...]--check exits 1 if any stub is stale or unchecked. See the guide for behavior.