core

Files (2)

• SKILL.md
• python-api.md · references/

SKILL.md (first lines)

# Working in a recurse session

You have one tool, `ipython`. Each call runs a cell in a **persistent Python
kernel** (Python ≥ 3.11) in the session's working directory. Everything else —
files, shell commands, skills, child agents — is reached from Python.

Full signatures: `print(read_skill("core", "references/python-api.md"))`.

## Cells

- State persists across calls, turns, and host compaction: variables,
  imports, functions, parsed data, and handles are still there next turn.
  It is lost only on `kernel.restart` or a daemon restart.
- Top-level `await` works. Do not call `asyncio.run()`.
- The cell returns captured stdout/stderr (≤ 64 KiB each, tail kept) and the
  `repr` of the last expression (≤ 16 KiB). Print summaries, not whole files.
- Errors come back as a traceback with frames named `<cell N>`.
- Long cells are interrupted at the daemon's timeout (default 600 s); state
  survives. Background asyncio tasks keep running between cells; their output
  appears at the start of the next cell's output.

## Files

Use plain Python. Keep results in variables instead of re-reading.

```python
from pathlib import Path
src = Path("src/auth.py").read_text()
Path("src/auth.py").write_text(src.replace("md5(", "sha256("))
hits = [p for p in Path(".").rglob("*.py") if "TODO" in p.read_text(errors="ignore")]
```

## Shell: `bash()`

Each `bash(cmd)` is its own process in its own process group, using the
kernel's current `os.getcwd()` and `os.environ` (so `os.chdir` and
`os.environ[...] = ...` apply to later commands).

```python
r = await bash("npm run check")     # BashResult(output, exit_code, stdout, stderr)
print(r.exit_code, r.output[-2000:])
```

For anything slow (test suites, builds, servers), keep the live handle and
**end your turn** instead of blocking:

```python
tests = bash("npm test")
tests.pid                            # then stop and reply; you will be woken
```

When an unread handle's process group finishes, you receive
`[recurse] Background command finished: pid …, exit … (…)`. Then inspect it:
`tests.poll()`, `tests.tail(60)`, `tests.output()`, or `await tests`.
Reading a finished handle from a cell cancels a notice that is still queued.
`await bash(...)` never produces a notice. `h.kill()` stops the group.
`bash(cmd, timeout=30)` kills it after 30 s. Background jobs (`cmd &`) keep
the handle alive until the whole group exits.

## Child agents

`rlm.spawn` creates a native child session of the host with its own context
and its own kernel. It returns at admission with a handle — never the answer.

```python
api = await rlm.spawn("Review the public API in src/api for breaking changes. "
                      "Reply with a bullet list of findings.", name="api-reviewer")
tests = await rlm.spawn("Find untested branches in src/auth.", name="test-gaps")
```

Rules:

1. Give each child a complete, self-contained task: goal, paths, constraints,
   and what to send back. Children see nothing of your context.
2. Spawn independent children in separate calls, then **end the turn**. Do not
   poll or sleep waiting for them.
3. Results arrive only as `agent_message` replies (they wake you with
   `[recurse] message from child <name> …`) or as files the child writes. For
   large results, ask the child to write a file and message you its path.
4. Names match `^[a-z0-9][a-z0-9-]{0,62}$` and are unique among your live
   children. At most 16 live children.
5. Follow up with a retained child:
   `await agent_message.send("Also check pagination.", receiver_role="child", receiver_name="api-reviewer")`
6. Inspect and clean up: `for c in await rlm.list_subagents(): print(c.session_name, c.status, c.active_session_id)`;
   `await rlm.delete_subagent(api)` when its context is no longer needed.

Status: `pending` (being created), `running`, `failed` (you get a message with
the reason), `deleted`.

### If you are a child

Your first prompt says so. Do the task, then reply:

```python
await agent_message.send("Found 2 issues:\n- …\n- …", receiver_role="parent")
```

Your final chat answer is not seen by the parent — only `agent_message` and
files are. Children cannot spawn children unless `rlm.max_depth > rlm.depth`.

## Skills

`skills()` lists skill metadata; `read_skill(name)` returns its `SKILL.md`
(`read_skill(name, "references/x.md")` for bundled files). Read a skill when a
task matches its description, then follow it. Python-backed skills are
preloaded under the skill name with `-` → `_` (`repo-map` → `repo_map`); call
them directly, and `await` them if the skill says they are async.

## Errors

Host bridge failures raise `rlm.RecurseError` subclasses with `.code`:
`rlm.UnsupportedHost` (this host cannot create children — e.g. MCP or CLI; do
the work yourself), `rlm.DepthExceeded`, `rlm.LimitExceeded`, `rlm.NotFound`,
`rlm.InvalidRequest`. Catch them and adapt; do not retry blindly.

## Trust model

The kernel runs your Python and shell commands with the user's operating-system
permissions, outside the host's per-tool permission prompts. It is not a

From StevenJPx2/recurse, MIT.

More from StevenJPx2/recurse