Reference
The rlx command tree, global flags, configuration and its defaults, environment variables, the ~/.aisquare layout, the Claude Code hooks, doctor, and a troubleshooting table.
Everything here describes release 0.10.1. Every command prints its own
help (rlx <command> --help), and that help is the final word on flags.
Commands
The package is aisquare-cli, and the command is rlx. Bare rlx at a
terminal opens the fleet UI.
Set up and keep healthy
| Command | What it is for |
|---|---|
init [path] | Register a repo as a project and connect your coding agent (--local, --agent claude-code, --yes). |
doctor | Check the machine and the current project, and print the fix for anything wrong (--live, --fix). More below. |
status | Installation health, the active project and the connected agents. |
agents | Connect or disconnect a coding agent's hooks: connect claude-code, connect codex, disconnect, list, status, scan; use chooses the coding agent for future launches. |
instances | The rlx UIs running on this home: kind, host, pid, version, since and heartbeat. |
upgrade | Update this install in place (--check, --version V, --dry-run). See Install. |
uninstall | Take the hooks out of Claude Code, then remove the package (--purge, --dry-run). |
config | Read and change settings: list, get, set, reset, redaction. More below. |
Memory and code
| Command | What it is for |
|---|---|
remember <text> | Save a preference or convention (--user for every project). |
context (alias ctx) | List, search, show, edit, remove, promote, import and export what is remembered; preview shows what a session will get. |
inject · why · log | Print the context block, explain the last one, show this project's prompt history. |
code | The project's symbol index: find, refs, similar, index. |
See Memory.
Projects and the fleet
| Command | What it is for |
|---|---|
ui | Open the fleet UI explicitly (what bare rlx does at a terminal). |
project (alias workspace) | Projects: list, info, onboard, switch, link, rename (the nickname), pin, unpin, move, group, fresh (alias reset), forget, prune. |
fleet | The agents: spawn, ls, status, top, tell, stop, restart, switch, shutdown, attach, reap, rename, relabel, adopt, capacity, gate, pause, resume. top is what each live agent consumes; relabel renames a running agent. |
launch <role> | Start one Claude Code session in a role, outside the fleet UI. See Launching sessions. |
watch | One watcher for the whole fleet, with no model: dialogs, limits, stalls and pull requests wake a manager only when something is new. |
outcomes | What your agents achieved in one week, against the week before, and how much of it you steered. |
accounts | Claude Code and Codex accounts: list, add, remove, run, usage, sessions, statusline, default, alias, order, move, enable, disable, trust, settings, share. |
persona | Personas: list, show, new, edit, rm, validate, import, export, attach. |
metrics | What sessions spent: stats, backfill, tokens, ledger, show, list, and opt-in share. Hidden from rlx --help in 0.10.1, and works as listed. |
remote | The fleet on your phone: serve, status, needs, allow-write, regenerate-password, revoke, install-page. |
See Run a fleet, Accounts and usage, Personas, See where your usage goes and Your fleet on your phone.
The board
| Command | What it is for |
|---|---|
task | Tasks: add, list, show, next, claim, review, reopen, done, block, drop, release. A task is its id, or its number on the board (12 or #12). |
note <text> | Post a note, decision, question or result to the board (--kind, --task, --to). |
board | Print the board, or watch it live with -w. |
brief | Work briefs: numbered requirements linked to board tasks, with recorded checks (create, list, show, update, link, evidence, check, finding). |
exec · reports | Run a command once and save a report of how it ended (rlx exec -- pytest); read the reports back. |
team | Board and harness plumbing: on, status, log, show, verify, signal, signals, spawn, bind, harness, focus, role, prune, and standby, with which a manager waiting on you stops watch's routine lines waking it. |
serve | The board as an MCP server, for Claude clients that are not local terminals. |
See The board, Tasks and the work cycle and Remote agents.
AISquare platform
| Command | What it is for |
|---|---|
aisquare login · aisquare logout · aisquare whoami | Sign this machine in to AISquare (only needed when a command acts as you there). |
aisquare auth | status and token for the current sign-in. |
Parked
| Command | State |
|---|---|
explainability | Parked. Session tracing; out of doctor and every screen. See Tracing (parked). |
A few commands are registered but hidden from --help because they are cloud
roadmap and do nothing yet (sync, connectors, capture, policy,
enforce, open). They say so and exit with code 70.
Global flags
Global flags work before the command or after it, except --version, which
goes first. Before is the safer habit: rlx --json fleet ls also reports
usage errors as JSON, and after fleet spawn <role> everything past its own
options goes to the agent.
| Flag | Meaning |
|---|---|
--json | Machine-readable JSON on stdout. Every command supports it. |
-V, --version | Print the version and exit. |
-v, --verbose / -q, --quiet | More or less output. |
--no-color | No coloured output. |
--profile NAME | Accepted, and in 0.10.1 read by nothing: every command uses ~/.aisquare/config.toml as it is. |
Options that many commands share, written after the command:
| Option | Meaning |
|---|---|
--project P, -P P | Act on project P (by nickname, name, codename, id prefix or path) instead of the one you are in. |
--as SESSION | Act as a board session; the hooks tell each agent its own id. |
--yes, -y | Do not ask. Commands that change things ask first at a terminal and need --yes off one. |
--dry-run | Show what would happen, change nothing (upgrade, uninstall, project fresh). |
Ids everywhere are time-sortable and work by any unique prefix, as in git.
Configuration
Settings live in ~/.aisquare/config.toml, and that file holds only what you
changed. The defaults are built in, so a setting you never touched follows
the current default even when a release changes it. (Each
[fleet.roles.<role>] table is the one exception: it is written whole.)
rlx config list # every setting, defaults included
rlx config list --overrides # only what you changed
rlx config get accounts.pick
rlx config set fleet.max_agents_per_project 6
rlx config reset # everything back to default; asks firstconfig reset moves your file aside to config.toml.bak-<stamp>, so moving it
back undoes the reset. ⚙ Settings ▸ App settings in rlx writes the same
file, and its Save writes only the fields you changed on the page. For the
fleet, a flag on one spawn beats the config file, which beats the default.
The settings people change most:
| Setting | Default | What it does |
|---|---|---|
accounts.pick | headroom | Where a launch goes when nothing names an account: the first account in your order with room (headroom), or rank 1 (default). |
accounts.prefer | priority | Which account under the line a headroom pick takes: in rank order (priority), or the one whose week resets first (reset-soonest). |
accounts.switch_at | 85 | Percent used at which an account counts as full. |
accounts.on_limit | switch | An agent that hits a usage limit moves to an account with room (switch), or stays parked (wait). |
accounts.before_limit | off | Move a fleet agent at a turn end once its account reads over switch_at (switch), or only note it on the board (warn). |
accounts.wait_if_reset_within_minutes | 15 | Do not move an agent whose limit resets this soon. |
accounts.share_trust | true | A folder trusted on one Claude account is trusted on all of them at launch. |
accounts.share_settings | false | Link every added account's settings.json to your main one. |
accounts.share | none | What else accounts share, from memory, skills, agents, commands, claude_md (CLAUDE.md) and plugins. |
projects.capture | false | Off: only folders you add are projects. On: every folder a hooked session runs in is recorded. |
capture.enabled | true | Record your prompts in projects you added. Off: nothing is stored. |
fleet.escape_key | f12 | The key that hands focus from an agent's pane back to the sidebar. |
fleet.max_agents_per_project | auto | The cap on agents per project, for the manager and for you. auto admits a spawn unless the machine is busy; a whole number is a fixed cap. |
fleet.max_agents_total | 0 | A cap across every project; 0 sets none. |
fleet.min_free_mb | 2048 | A spawn is refused when the machine has less free memory than this. |
fleet.auto_stop_finished | true | Stop a tester, reviewer, validator or ui-tester whose task is closed and who has sat idle for auto_stop_idle_minutes (5). A running rlx watch stops them too while watch.auto_stop is true, whatever this says. |
fleet.first_prompt | argv | How an agent gets its first message: on its command line (argv), or typed once its input box is drawn (type). |
fleet.worktree_dir | .aisquare-worktrees | Where coder and reviewer worktrees go, relative to the repo root. |
fleet.roles.<role>.permission_mode | auto | The Claude Code permission mode each role launches in. |
fleet.roles.<role>.worktree | true for coder and reviewer | Whether the role gets its own git worktree. |
fleet.roles.<role>.remote_control | false | Start the role's agents with Claude Code's own Remote Control. See Control the fleet remotely. |
fleet.roles.<role>.persona | none | The persona the role's agents are spawned as. |
fleet.disable_native_agent_teams | true | Keep Claude Code's own experimental agent teams off in fleet launches, so every agent is visible in rlx. |
code.enabled | true | Build the symbol index when a project is added. |
updates.check | true | Ask PyPI once a day whether a newer release is out. |
sharing.enabled | false | Send anonymous daily usage counts. See See where your usage goes. |
default_pool | project | Where remember saves without --user or --project. |
redaction.level | standard | How much is scrubbed from what leaves the machine: off, standard, strict. |
No [fleet] setting is read from the environment. A role's model and effort
come from the spawn's own flags, then the role's settings (extra_args, a
binding's --arg), then your last /model and /effort pick; see
Run a fleet. rlx team bind pins a
role's binary, environment, arguments and account; see
Launching sessions.
Environment variables
| Variable | Effect |
|---|---|
AISQUARE_HOME | Move the whole ~/.aisquare tree somewhere else. |
AISQUARE_TOKEN | An AISquare sign-in token to use instead of the stored session. |
AISQUARE_ROLE | The role of a Claude Code session started by hand; launching with it opts the repo in to the board. |
AISQUARE_TEAM=0 | Master off switch: hooks and board commands do nothing. |
AISQUARE_TEAM_HUB | Point sessions from several repos at one shared board. |
AISQUARE_TEAM_DELTA=0 | Mute the per-prompt teammate updates for one session. |
AISQUARE_TEAM_LEASE_MIN | Task-claim lease in minutes (default 120). |
AISQUARE_MODEL_<ROLE> | Pin a role's model outright, skipping the harness ladder, for rlx team spawn, team harness and persona import. A fleet spawn does not read it. |
AISQUARE_EFFORT / AISQUARE_EFFORT_<ROLE> | The base effort for that ladder, or one role's effort exactly. Read by team spawn, team harness and persona import, not by a fleet spawn. |
AISQUARE_BIN_<ROLE> | The executable a role launches, over its binding. See Which binary a role runs. |
AISQUARE_AGENT_BIN | The executable every role launches when neither a flag nor AISQUARE_BIN_<ROLE> names one, over a binding. |
AISQUARE_HARNESS_PROBE=0 | Never probe model availability. |
AISQUARE_SERVE_CLIENT, AISQUARE_SERVE_ROLE | Name an MCP client and its role on the board. See Remote agents. |
AISQUARE_REMOTE_PORT, AISQUARE_REMOTE_AUTO_OFF, AISQUARE_REMOTE_NGROK_URL | Defaults for rlx remote serve. |
AISQUARE_NO_TELEMETRY=1, DO_NOT_TRACK=1 | Force usage sharing off, and skip the question. Any CI run does the same. |
AISQUARE_PASTE_LOG | Record each paste rlx receives (its length, first 80 characters and the focused widget) in a file, to check what a terminal sends. |
The tracing variables (EXPLAINABILITY_API_KEY,
AISQUARE_EXPLAINABILITY_TARGET, AISQUARE_PIN_SESSION_ID) belong to the
parked tracing commands.
The ~/.aisquare directory
Everything rlx keeps is in one place, in your home directory:
~/.aisquare/
├── context.db # memory, projects, prompt history, boards, sessions, fleet agents, usage (SQLite)
├── config.toml # your settings: only what you changed
├── state.json # small UI state: theme, active project, sidebar and board sizes
├── agents.json # the coding agents you connected
├── credentials # your AISquare sign-in (readable by you only)
├── fleet-tmux.conf # the fleet's private tmux config (regenerated; do not edit)
├── claude-accounts/ # one Claude Code config directory per account you added
├── codex-accounts/ # the same for each Codex account you added
├── claude-shared/ # memory/ shared across accounts, with [accounts] share
├── personas/ # your user-layer personas (a project's are in <repo>/.aisquare/personas)
├── projects/<id>/ # per project: code/ (the symbol index), manager/state.md
├── briefs/ # evidence kept by work briefs
├── reports/ # command reports from rlx exec (owner-only)
├── remote.json # Remote's settings and secrets (owner-only)
├── remote-audit.log # every write made from the phone (owner-only)
├── remote-needs.json # Remote's needs-you feed state
├── remote-push.json # Remote's notification subscriptions
├── cache/ # disposable: usage readings, statusline/ session records
└── log/ # capture and diagnostic logsThe remote* files appear only once you use
Remote. rlx uninstall --purge removes
the whole tree. Outside it, rlx writes its hooks (and, once you install
it, its status line) into each Claude Code directory's settings.json, as
described below, and one small file: the Claude Code plugin's answers about
uv, in ~/.cache/aisquare.
The Claude Code hooks
rlx agents connect claude-code (and init, and the one-line installer)
merges six hooks into Claude Code's settings.json. It never touches your
other hooks, and rlx agents disconnect claude-code removes exactly these.
| Hook | What it does |
|---|---|
SessionStart | Hands the session its orientation: your context, and on a team its role and board briefing. |
UserPromptSubmit | Records the prompt in a project you added, delivers what teammates did since the last prompt, and heartbeats. |
Stop | Marks the session waiting, renews its task leases, records the turn's tokens, and notes a /model or /effort you picked. |
Notification | Flags NEEDS YOU when Claude Code needs a human (a permission prompt, a question). |
SessionEnd | Releases claims and marks the session gone. |
StopFailure | On a usage limit, marks the session limited with its reset time, wakes the manager, and (with on_limit = "switch") moves a fleet agent to another account. |
Every hook is fail-open: an error inside one is swallowed and the session
carries on. SessionStart and UserPromptSubmit get a 120-second timeout;
if you declare the hooks yourself (with home-manager, say), give those two the
same.
Doctor
rlx doctor # this machine and the project you are in
rlx doctor --live # also the checks that leave the machine
rlx doctor --fix # create a missing ~/.aisquare, then check again
rlx --json doctor # the same report, for a scriptdoctor checks Python and the install, the ~/.aisquare home, the config and
the store, Claude Code and its hooks (per account), each Claude account's login
and any usage back-off, tmux and gh, the symbol index, the model harness, the
fleet (dead managers, agents that can be resumed, first-message delivery,
memory headroom, the watcher, the fleet terminal), the tools each role is
launched without, browser tools for the ui-tester, and whether anything routes
an agent's model traffic somewhere unexpected. Each row that is not green
carries the command that fixes it. It exits 1 when any check fails.
Some rows appear only when they apply: remote control while a role has
Claude Code's Remote Control on, role bindings while a team bind binding sets
CLAUDE_CONFIG_DIR or CLAUDE_CODE_TMPDIR, and fleet model pick after a /model or /effort answer it could
not read.
--live adds what needs the network: the TLS handshake and the trust source
in use, your Claude accounts' usage, and your AISquare workspace's balance.
In rlx the same report is ⚙ Settings ▸ Doctor, where a known fix is one
click. Tracing has its own doctor, aisquare explainability doctor; see
Tracing (parked).
Troubleshooting
| Symptom | Cause and fix |
|---|---|
rlx prints usage instead of opening | It is not at an interactive terminal (a pipe, or TERM=dumb). Run it in a terminal; rlx ui says why. |
Fleet commands refuse with fleet_unavailable | tmux is missing or older than 3.2. Install it (see Install); everything outside the fleet keeps working. |
An agent's row says no hooks, or sessions never show a state | Hooks load when Claude Code starts. Run rlx agents connect claude-code, then restart sessions that were already running. rlx doctor checks every account. |
| An agent sits at Claude Code's "trust this folder?" question | No account trusts the folder yet. Answer it once in the pane, or run rlx accounts trust <dir> to trust it on every account. |
An agent shows 🔔 (🔔 NEEDS YOU in fleet ls) | It is waiting on a permission prompt or a question. Click it and answer in its pane, or rlx fleet attach. If prompts are routine, change the role's permission_mode. |
| An agent shows ⏳ limited | Its account hit a usage limit. With more than one account it moves on its own; to move it now, rlx fleet switch <label>. With one account, add another. |
| A spawn is refused for memory or a cap | fleet.min_free_mb, max_agents_per_project or max_agents_total stopped it, and the refusal names the numbers. rlx fleet capacity shows them all. |
| An agent started on a model you did not expect | A spawn runs its own flags, then the role's settings, then your last /model pick. A /model typed while a turn runs is not recorded; change the model at the prompt. |
| Rows say ✗ lost | The tmux server was killed or a pane vanished. rlx fleet reap reconciles the rows; uncommitted or unpushed work is never deleted. |
A board command is refused with not_added | The folder is not a project. Add it with rlx project onboard <path>. |
A session shows (stale) on the board | It has not checked in for 30 minutes: a crashed terminal, or one long tool call. rlx team prune retires the row, and frees its claims only if it has been silent for 4 hours; for a session you know is dead, add --release-claims. See Ghost sessions. |
| The board looks quiet | You are in a different project from the agents. Run it from their repo, pass --project, or export the same AISQUARE_TEAM_HUB. |
| An agent says it finished but its task is still in review | A task closes only when rlx task done runs, and a task a work brief links needs a fresh pass for each of its requirements. Check rlx team log, and tell the agent to run the command. |
An account reads ! on the Accounts page | Its usage could not be read. Hover it for the cause and the fix, or run rlx accounts usage. |
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.
API Reference
Generated, per-operation API reference with a Try-it playground.