# Reference (/docs/rlx/reference)

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 [#commands]

The package is `aisquare-cli`, and the command is `rlx`. Bare `rlx` at a
terminal opens the [fleet UI](/docs/rlx/fleet-ui).

### Set up and keep healthy [#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](#doctor).                                                       |
| `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](/docs/rlx/install#update).                                                                    |
| `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](#configuration).                                                                               |

### Memory and code [#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](/docs/rlx/memory).

### Projects and the fleet [#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](/docs/rlx/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](/docs/rlx/fleet),
[Accounts and usage](/docs/rlx/accounts),
[Personas](/docs/rlx/personas),
[See where your usage goes](/docs/rlx/usage-and-stats) and
[Your fleet on your phone](/docs/rlx/remote).

### The board [#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](/docs/rlx/board),
[Tasks and the work cycle](/docs/rlx/tasks) and
[Remote agents](/docs/rlx/remote-agents).

### AISquare platform [#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 [#parked]

| Command          | State                                                                                                            |
| ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| `explainability` | **Parked.** Session tracing; out of `doctor` and every screen. See [Tracing (parked)](/docs/rlx/explainability). |

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]

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 [#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.)

```sh
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>&#x60;, 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](/docs/rlx/remote-control).                                                                                              |
| `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](/docs/rlx/usage-and-stats).                                                                                                                          |
| `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](/docs/rlx/fleet). `rlx team bind` pins a
role's binary, environment, arguments and account; see
[Launching sessions](/docs/rlx/launching-sessions).

## Environment variables [#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](/docs/rlx/launching-sessions#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](/docs/rlx/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](/docs/rlx/explainability) commands.

## The `~/.aisquare` directory [#the-aisquare-directory]

Everything rlx keeps is in one place, in your home directory:

```text
~/.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](/docs/rlx/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 [#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 [#doctor]

```sh
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&#x60; the same report is **⚙ Settings ▸ Doctor**, where a known fix is one
click. Tracing has its own doctor, `aisquare explainability doctor`; see
[Tracing (parked)](/docs/rlx/explainability).

## Troubleshooting [#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](/docs/rlx/install#install-by-hand-with-uv)); 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](/docs/rlx/add-accounts).                                                                                                                        |
| 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](/docs/rlx/launching-sessions#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`.                                                                                                                                                                                                              |

<Cards>
  <Card title="Install" href="/docs/rlx/install" description="Install, update and uninstall." />

  <Card title="Tour of rlx" href="/docs/rlx/fleet-ui" description="The sidebar, agent panes, Settings and the keys you will use every day." />
</Cards>
