> ## Documentation Index
> Fetch the complete documentation index at: https://rakumux.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents that use Rakumux

> Let an agent start helper sessions, read other sessions' output and report its own status.

An agent running in a Rakumux session can use Rakumux too: start sessions for long-running work,
read what a dev server or test run printed, and say what it's doing. It always stays inside its own
folder.

## Set it up

Add the [MCP server](https://rakumux.com/docs/agents/mcp.md) to your agent. For Claude Code:

```bash theme={null}
claude mcp add --scope user rakumux -- rakumux-mcp
```

The agent then has tools to list folders and sessions, start a session, read a session's screen or
scrollback, and rename sessions. Agents can also run the JSON command line,
`rakumux session …`, from their shell.

## Things to ask your agent

> **Run the tests in their own session and tell me when they finish**
>
> The agent creates a session in its folder that runs the test command, then reads its output when
> it's done. You can watch the run in Rakumux alongside the agent.

> **Check the dev server's output for errors**
>
> The agent reads the screen or recent scrollback of the session running your dev server, by name,
> and reports what it found. The text comes back marked untrusted, so the agent treats it as data.

> **Start a reviewer on this branch**
>
> The agent starts another session running a second agent to review the work, in the same folder.
> Agents can nest sessions two deep.

> **Name this session after what you're doing**
>
> The agent renames its own session, so the list stays readable.

## Reporting status

An agent, or any script inside a session, can report on its own session. The report shows in the
list and in every client:

```bash theme={null}
rakumux session report --state working --text "Refactoring the auth middleware"
rakumux session report --state done --text "Tests pass" \
  --summary "Moved session checks into one middleware" --file src/auth.rs
```

`--state` takes `working`, `blocked`, `done` or `idle`. An agent can also say how to resume it after
a reboot with `--resume -- PROGRAM ARGS`.

## Limits

Inside a session, an agent:

* sees only the sessions of **its own folder**;
* may start sessions there, with at most 4 of its own running at once, nesting at most 2 deep, 8
  running agent-created sessions per folder and 10 creates a minute;
* may rename, pin and report on **itself** only.

Typing into or ending other sessions from an agent isn't supported yet. These limits prevent
accidents rather than stop a hostile program, since everything runs as your user. See
[What agents may do](https://rakumux.com/docs/agents/overview.md#what-agents-may-do).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.