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

```bash [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:

```bash [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:

```bash [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:

```bash [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`:

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

### Esc does not close the floating terminal

<Kbd>Esc</Kbd> goes to the program in the terminal. Use <Kbd>⌘</Kbd> <Kbd>J</Kbd>.

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

```bash [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.

### Cookie import from Chrome fails in an agent

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](/docs/reference/data-and-logs#report-a-bug) and report the problem on [GitHub](https://github.com/deltaqdev/rexa-releases/issues) or [Discord](https://discord.gg/hMWEAr38Md).