AISquare
rlx

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

CommandWhat it is for
init [path]Register a repo as a project and connect your coding agent (--local, --agent claude-code, --yes).
doctorCheck the machine and the current project, and print the fix for anything wrong (--live, --fix). More below.
statusInstallation health, the active project and the connected agents.
agentsConnect or disconnect a coding agent's hooks: connect claude-code, connect codex, disconnect, list, status, scan; use chooses the coding agent for future launches.
instancesThe rlx UIs running on this home: kind, host, pid, version, since and heartbeat.
upgradeUpdate this install in place (--check, --version V, --dry-run). See Install.
uninstallTake the hooks out of Claude Code, then remove the package (--purge, --dry-run).
configRead and change settings: list, get, set, reset, redaction. More below.

Memory and code

CommandWhat 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 · logPrint the context block, explain the last one, show this project's prompt history.
codeThe project's symbol index: find, refs, similar, index.

See Memory.

Projects and the fleet

CommandWhat it is for
uiOpen 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.
fleetThe 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.
watchOne watcher for the whole fleet, with no model: dialogs, limits, stalls and pull requests wake a manager only when something is new.
outcomesWhat your agents achieved in one week, against the week before, and how much of it you steered.
accountsClaude Code and Codex accounts: list, add, remove, run, usage, sessions, statusline, default, alias, order, move, enable, disable, trust, settings, share.
personaPersonas: list, show, new, edit, rm, validate, import, export, attach.
metricsWhat sessions spent: stats, backfill, tokens, ledger, show, list, and opt-in share. Hidden from rlx --help in 0.10.1, and works as listed.
remoteThe 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

CommandWhat it is for
taskTasks: 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).
boardPrint the board, or watch it live with -w.
briefWork briefs: numbered requirements linked to board tasks, with recorded checks (create, list, show, update, link, evidence, check, finding).
exec · reportsRun a command once and save a report of how it ended (rlx exec -- pytest); read the reports back.
teamBoard 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.
serveThe 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

CommandWhat it is for
aisquare login · aisquare logout · aisquare whoamiSign this machine in to AISquare (only needed when a command acts as you there).
aisquare authstatus and token for the current sign-in.

Parked

CommandState
explainabilityParked. 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.

FlagMeaning
--jsonMachine-readable JSON on stdout. Every command supports it.
-V, --versionPrint the version and exit.
-v, --verbose / -q, --quietMore or less output.
--no-colorNo coloured output.
--profile NAMEAccepted, 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:

OptionMeaning
--project P, -P PAct on project P (by nickname, name, codename, id prefix or path) instead of the one you are in.
--as SESSIONAct as a board session; the hooks tell each agent its own id.
--yes, -yDo not ask. Commands that change things ask first at a terminal and need --yes off one.
--dry-runShow 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 first

config 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:

SettingDefaultWhat it does
accounts.pickheadroomWhere a launch goes when nothing names an account: the first account in your order with room (headroom), or rank 1 (default).
accounts.preferpriorityWhich account under the line a headroom pick takes: in rank order (priority), or the one whose week resets first (reset-soonest).
accounts.switch_at85Percent used at which an account counts as full.
accounts.on_limitswitchAn agent that hits a usage limit moves to an account with room (switch), or stays parked (wait).
accounts.before_limitoffMove 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_minutes15Do not move an agent whose limit resets this soon.
accounts.share_trusttrueA folder trusted on one Claude account is trusted on all of them at launch.
accounts.share_settingsfalseLink every added account's settings.json to your main one.
accounts.sharenoneWhat else accounts share, from memory, skills, agents, commands, claude_md (CLAUDE.md) and plugins.
projects.capturefalseOff: only folders you add are projects. On: every folder a hooked session runs in is recorded.
capture.enabledtrueRecord your prompts in projects you added. Off: nothing is stored.
fleet.escape_keyf12The key that hands focus from an agent's pane back to the sidebar.
fleet.max_agents_per_projectautoThe 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_total0A cap across every project; 0 sets none.
fleet.min_free_mb2048A spawn is refused when the machine has less free memory than this.
fleet.auto_stop_finishedtrueStop 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_promptargvHow an agent gets its first message: on its command line (argv), or typed once its input box is drawn (type).
fleet.worktree_dir.aisquare-worktreesWhere coder and reviewer worktrees go, relative to the repo root.
fleet.roles.<role>.permission_modeautoThe Claude Code permission mode each role launches in.
fleet.roles.<role>.worktreetrue for coder and reviewerWhether the role gets its own git worktree.
fleet.roles.<role>.remote_controlfalseStart the role's agents with Claude Code's own Remote Control. See Control the fleet remotely.
fleet.roles.<role>.personanoneThe persona the role's agents are spawned as.
fleet.disable_native_agent_teamstrueKeep Claude Code's own experimental agent teams off in fleet launches, so every agent is visible in rlx.
code.enabledtrueBuild the symbol index when a project is added.
updates.checktrueAsk PyPI once a day whether a newer release is out.
sharing.enabledfalseSend anonymous daily usage counts. See See where your usage goes.
default_poolprojectWhere remember saves without --user or --project.
redaction.levelstandardHow 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

VariableEffect
AISQUARE_HOMEMove the whole ~/.aisquare tree somewhere else.
AISQUARE_TOKENAn AISquare sign-in token to use instead of the stored session.
AISQUARE_ROLEThe role of a Claude Code session started by hand; launching with it opts the repo in to the board.
AISQUARE_TEAM=0Master off switch: hooks and board commands do nothing.
AISQUARE_TEAM_HUBPoint sessions from several repos at one shared board.
AISQUARE_TEAM_DELTA=0Mute the per-prompt teammate updates for one session.
AISQUARE_TEAM_LEASE_MINTask-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_BINThe executable every role launches when neither a flag nor AISQUARE_BIN_<ROLE> names one, over a binding.
AISQUARE_HARNESS_PROBE=0Never probe model availability.
AISQUARE_SERVE_CLIENT, AISQUARE_SERVE_ROLEName an MCP client and its role on the board. See Remote agents.
AISQUARE_REMOTE_PORT, AISQUARE_REMOTE_AUTO_OFF, AISQUARE_REMOTE_NGROK_URLDefaults for rlx remote serve.
AISQUARE_NO_TELEMETRY=1, DO_NOT_TRACK=1Force usage sharing off, and skip the question. Any CI run does the same.
AISQUARE_PASTE_LOGRecord 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 logs

The 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.

HookWhat it does
SessionStartHands the session its orientation: your context, and on a team its role and board briefing.
UserPromptSubmitRecords the prompt in a project you added, delivers what teammates did since the last prompt, and heartbeats.
StopMarks the session waiting, renews its task leases, records the turn's tokens, and notes a /model or /effort you picked.
NotificationFlags NEEDS YOU when Claude Code needs a human (a permission prompt, a question).
SessionEndReleases claims and marks the session gone.
StopFailureOn 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 script

doctor 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

SymptomCause and fix
rlx prints usage instead of openingIt 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_unavailabletmux 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 stateHooks 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?" questionNo 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 ⏳ limitedIts 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 capfleet.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 expectA 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 ✗ lostThe 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_addedThe folder is not a project. Add it with rlx project onboard <path>.
A session shows (stale) on the boardIt 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 quietYou 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 reviewA 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 pageIts usage could not be read. Hover it for the cause and the fix, or run rlx accounts usage.

On this page