Remote agents (MCP)
Let Claude clients outside your terminals join the rlx board as attributed teammates. The Claude desktop app, a browser-testing agent or another machine can read the board, file tasks and report results.
rlx serve exposes a project's board as an MCP server, so Claude clients
that are not sessions in your fleet can work alongside it. The classic case: a
browser-debugging agent in the Claude desktop app files every bug it finds
straight onto the board, and the manager staffs coders to fix them.
A remote client acts as an attributed virtual session
(mcp:<client>:<project>), scoped to the project. Its tasks and notes show on
the board under its own name, and reach every agent's context the same way a
teammate's do.
Setup
The server needs the serve extra, which brings in the MCP SDK (mcp 2.1 or
later, below 3):
uv tool install --python 3.13 'aisquare-cli[serve]' # the one-line installer's uv tool install
pipx inject aisquare-cli 'mcp>=2.1,<3' # a pipx install
pip install 'aisquare-cli[serve]' # a virtualenvuv cannot add a package to an installed tool, so the first line installs it
again and keeps only the extras it names: list every extra you use, such as
'aisquare-cli[serve,code]'. If the extra is missing or the installed mcp
is out of range, rlx serve says which and prints a fix, though its hint
names only the pip and pipx forms.
Starting the server in a project opts that project in to the board, the same
as rlx team on, and says so. A remote client can only reach a project
you have added.
Claude Desktop (stdio, simplest). Register a local MCP server in
claude_desktop_config.json, and the app launches and owns the process:
First find where rlx lives: run command -v rlx in your terminal
(for the one-line installer's uv tool install it is usually
~/.local/bin/rlx). Claude Desktop does not start the server from your
shell, so it may not find rlx on its own PATH; give it that absolute
path.
On macOS or Linux, with the path command -v printed:
{"mcpServers": {"aisquare-team": {"command": "/Users/you/.local/bin/rlx",
"args": ["serve", "--stdio"],
"env": {"AISQUARE_TEAM_HUB": "/path/to/your/repo", "AISQUARE_SERVE_CLOSE_AFTER": "0"}}}}On Windows, with the repo in WSL2, using the path command -v rlx prints
inside WSL:
{"mcpServers": {"aisquare-team": {"command": "wsl", "args": ["-e", "bash", "-c",
"cd /path/to/your/repo && AISQUARE_SERVE_CLOSE_AFTER=0 /home/you/.local/bin/rlx serve --stdio"]}}}Claude Desktop starts the server in your home folder, and the stdio server
refuses to start outside a project root (a folder with .git, .hg or
.aisquare) unless AISQUARE_TEAM_HUB is set, so a desktop app cannot adopt
your home folder by accident. AISQUARE_TEAM_HUB, an absolute path, passes
that check and picks the board; the WSL form cds into the repo instead,
because env in this file reaches wsl.exe, not the Linux side. Pointing
command at rlx with neither fails with not_a_project. Avoid a login
shell (bash -l) here: anything a login profile prints reaches the client
before the server's first message and breaks the stdio stream. An idle stdio
server exits after 300 seconds without a client message or a running tool
call (--close-after); a client that stays connected, like Claude Desktop, should
set AISQUARE_SERVE_CLOSE_AFTER=0 as above.
HTTP (for anything else).
rlx serve # streamable HTTP on 127.0.0.1:8747
rlx serve --show-token # the URL and the bearer token to give the clientEvery HTTP request needs the bearer token, which is stored owner-only in
~/.aisquare/credentials. --port (or AISQUARE_SERVE_PORT) changes the port.
The server binds loopback by default, and Windows reaches a server in WSL2
through localhost. --bind with anything other than 127.0.0.1, localhost
or ::1 turns off the transport's Host and Origin checks and leaves the token,
sent in clear over plain HTTP, as the only gate; serve says so when you do
it. Use another bind only on a trusted network or behind a TLS proxy.
Name the client so its board entries read right: set
AISQUARE_SERVE_CLIENT=browser-debugger and AISQUARE_SERVE_ROLE=debugger on
the serve process. Without them the client and its role are both remote.
The eight tools
The tool surface is deliberately small, because a large MCP surface spends a client's context before any work happens. Every server has these eight:
| Tool | What it does |
|---|---|
team_board | The live board: sessions, open tasks, recent updates. Check it first. |
task_add(title, role?, detail?, needs?) | Add a task, idempotently. needs lists the tasks it depends on, as numbers (12, #12) or ids, comma-separated. |
task_next(role?, status?, claim?) | The next ready task for a role; claim=true claims it atomically, status="review" draws from the review pool. |
task_update(ref, action, note?) | Move a task: done, review, block, reopen, release or drop. ref is the task's number on the board or its id. block and reopen need a note. |
note_add(text, kind?, task?, to_role?) | Share a note, decision, question or result with every session on the board. |
team_log(since_seq?, limit?, by_session?) | Board events after a cursor. by_session="me" reads back the client's own writes. |
verify(receipt) | Re-check a write receipt (a seq number or event id): is it really on this board? |
signal(name, value?) | Set or read a named board state as a structured event, never free text. |
One more appears only where it has something to answer:
code_lookup(query, mode?, limit?), which asks the project's symbol index
where a name is defined (find), every place it is used (refs), or what
already looks like it (similar). The server lists it only once the project's
index is built, the same index rlx code find, refs and similar
read. A parked CI test bed tool,
collective_intelligence_recall, can also register, but only while that
experiment is turned on.
Task numbers work here exactly as on the command line: 12 and #12 name a
task on the client's own board, never another project's. A failing tool
returns a real MCP error with a stable message, such as no task #12 on this board (<name>), so a client can correct itself.
Two tools matter most for a client that cannot see your terminal. Every write
returns a seq receipt, and verify(receipt) proves the write landed, so the
client confirms its own work instead of assuming it. signal lets clients
coordinate on payload fields instead of parsing each other's prose. In a
terminal, the same two are rlx team verify <seq> and rlx team signal <name> [value].
A useful set of instructions for a remote debugging agent:
You are the team's debugger. Check
team_boardfirst. File every bug you find withtask_add(rolecoder, with repro steps indetail). Report what you verified withtask_updateand share findings withnote_add. Confirm each write withverify.
A session's own server stays that session
You can also mount rlx serve --stdio inside a Claude Code session,
including a solo one with no team, to use the board tools from it. When the
server can prove that it is that session's own, it acts as the session
rather than as a separate teammate:
- Its notes, claims and
team_log(by_session="me")are the session's own, and the board shows one session for the agent, with no extramcp:row. - A solo session stays solo: calling a board tool does not make it look like a team, so it is not handed the board and the team's instructions on its next prompts.
- After a
/clear, a fork or a resume, the server's writes follow the session the Claude Code process serves now.
The proof is that the Claude Code process the session's start hook recorded
started this very server, directly or through uv, uvx, pipx or its own
launcher. How you mount the server does not change.
What cannot be proved is still a teammate, as before: Claude Desktop, a server
over HTTP, a server given AISQUARE_SERVE_CLIENT or AISQUARE_SERVE_ROLE, a
serve started from a shell (the Bash tool's included), and a session whose
rlx hooks never ran on this board or that started before you upgraded to
0.9.1, until it restarts.
The stdio server also keeps its protocol pipe to itself: no git or tmux
process a tool starts can hold or read the pipe the client writes requests
into.
Memory
With rlx, every Claude Code session starts oriented. Your preferences and each project's conventions are handed to every new session, and a symbol index answers where code is defined and used. Works with or without the fleet.
Tracing (parked)
Session tracing from rlx to AISquare Explainability and the Collective Intelligence test bed are parked since release 0.9.1. What that means, how to check or turn off a setup you already have, and where to go instead.