Rexa Docs
Esc

    Reference

    Troubleshooting

    Fixes for problems you may meet installing Rexa, running agents and using its tools.

    Install and update

    rexa: command not found

    Open a new terminal; the installer added ~/.local/bin to PATH in your shell’s startup file. If ~/.local/bin/rexa is a file you put there, Rexa leaves it alone: remove it and relaunch Rexa to recreate the link.

    The installer stops at a Command Line Tools prompt

    The installer needs /usr/bin/python3, and Rexa needs git. Both come with the Command Line Tools:

    Terminal
    xcode-select --install

    Then rerun the installer.

    The update badge disappears

    The download failed. Rexa checks again within 4 hours, or update now with rexa update.

    Projects or layout reset after an update

    A saved-state migration failed and Rexa restored the previous state file. Check, then retry:

    Terminal
    rexa update migrate --check
rexa update migrate --force

    Agents

    An agent shows no card or status

    Agents report through hooks Rexa installs. Check and repair them:

    Terminal
    rexa claude setup --check
rexa claude setup

    Replace claude with your agent. Then:

    • Codex runs new hooks only after you trust them in its startup review.
    • The agent must start in a Rexa terminal. Agents started elsewhere show only in session history.

    Cursor Agent stays on Working while it waits

    Cursor Agent sends no hook for approval prompts. Check its terminal.

    A card is stuck

    Right-click the card → Remove Card, or rexa sessions remove <id>. The agent process keeps running.

    Terminal

    Terminals keep running after I quit

    They run in a background process so they reattach on the next launch. List or stop them:

    Terminal
    rexa pty ls
rexa pty kill <id>
rexa pty stop

    Running shells ended after an update

    An update that changes the terminal protocol ends running shells once. The release notes say when.

    Option-arrow keys do not move by word

    The terminal sends ESC [1;3D and ESC [1;3C, which default zsh and bash configs do not bind. Add to ~/.zshrc:

    ~/.zshrc
    bindkey '^[[1;3D' backward-word
bindkey '^[[1;3C' forward-word

    Esc does not close the floating terminal

    Esc goes to the program in the terminal. Use ⌘ J.

    Language servers

    No diagnostics or go-to-definition

    • The server is off. Turn it on in Settings → Language servers.
    • The status item is yellow: the server is not installed. Install it on your PATH, then run rexa: restart language servers.
    • Your PATH is set only for interactive shells in your startup files. Move the export outside that guard.
    • .nvmrc holds an alias such as lts/iron. Write a version number such as 20.

    The first TypeScript start downloads the server, so it takes longer.

    Settings and keymap

    My settings stopped applying

    settings.json and keymap.json must be plain JSON. A comment or trailing comma makes Rexa ignore the whole file. Remove it and save.

    A shifted-symbol shortcut never fires

    Write the shifted symbol: cmd-~, not cmd-shift-`; cmd-{, not cmd-shift-[.

    GitHub and GitLab

    The Forge panel shows a setup card

    Install and sign in to the CLI it names:

    Terminal
    brew install gh
gh auth login

    Push or pull fails without asking for a password

    Rexa never prompts for credentials. Sign in with gh or glab, or set up a git credential helper or SSH key.

    Browser

    rexa web eval is refused

    eval is off by default. Quit Rexa and start it with REXA_WEB_ALLOW_EVAL=1 set.

    Chrome import asks for confirmation in the terminal and needs an interactive shell. Run it yourself.

    Still stuck

    Collect logs as described in Data and logs and report the problem on GitHub or Discord.