> ## Documentation Index
> Fetch the complete documentation index at: https://rakumux.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fixes for common problems.

> **Option/Alt+↑/↓ do nothing**
>
> Your terminal isn't sending Option/Alt with the arrow keys. iTerm2, Ghostty, kitty, WezTerm and
> Alacritty do. In macOS Terminal.app, turn on **Use Option as Meta key** in the profile's
> Keyboard settings. `↑`/`↓` and `j`/`k` always work.

> **Folder or branch marks show as boxes**
>
> Your terminal can't show the icon set. Pick another in **Settings → Icons**: Plain works in any
> font, Emoji needs a colour emoji font, and Nerd Font needs a Nerd Font set in your terminal.

> **The footer says the server is unavailable**
>
> Run `rakumux daemon status`. If the server isn't running, `rakumux daemon start` starts it (any
> `rakumux` command does too). If it runs but misbehaves, read `rakumux daemon logs`, then restart
> it in place with `rakumux daemon restart`: sessions keep running.

> **Rakumux says the server is missing features**
>
> An older server is still running after an update. Accept the offer to restart it, or run
> `rakumux daemon restart`. When the server supports restarting in place, sessions keep running;
> otherwise Rakumux asks before stopping it.

> **The update says the install isn't writable**
>
> Automatic updates need write access to the install directory. Re-run the installer with the same
> `PREFIX`, or install user-locally with `PREFIX="$HOME/.local"`. Source builds update with
> `./build.sh`, then `R`.

> **An agent's status looks wrong**
>
> Without hooks, Rakumux reads the agent's screen, which can lag behind. Install the
> [activity hooks](https://rakumux.com/docs/agents/activity-hooks.md) for exact phases. For Codex, make sure you trusted the
> hooks in `/hooks`.

> **Sessions don't get AI titles**
>
> Check that you're signed in (`a`, or `rakumux account status`) and that **Settings →
> Available on sign-in → AI session titles** is on (or the same switch at
> [rakumux.com/features](https://rakumux.com/features)). A session gets its first title once
> its agent has written 5 messages or finished; press `s` for one sooner. A session you renamed
> keeps your name. Titles need a Claude Code, Codex or OpenCode session and a server that reads
> agents' conversations: after an update, accept Rakumux's offer to restart the server in place
> (`S`), which keeps sessions running. For two OpenCode sessions in one folder, install the
> OpenCode plugin. Accounts are by invitation for now.

> **The sign-in code expired**
>
> Codes are short-lived. Press `a` again (or run `rakumux account login`) for a new one, and
> approve it in the browser.

> **rakumux: command not found, or a binary not found**
>
> Make sure `$PREFIX/bin` (by default `/usr/local/bin`) is on your `PATH`, or reinstall. In a source
> checkout, run `./build.sh`, which builds every binary.

> **Keys arrive in pieces on a phone or over SSH**
>
> Over SSH, Rakumux waits a little longer for the rest of an escape sequence (an arrow key, Home,
> End, PgUp, PgDn, F1 to F4 or a focus report), so a lone `Esc` can take a moment. That's expected.

## Logs

| Log | Where |
| - | - |
| The server | `rakumux daemon logs`, or `~/.rakumux/logs/ptyd.log` |
| A background HTTP API | `~/.rakumux/logs/api.log` (`RAKUMUX_API_LOG=debug` for every request) |
| Keys the UI read | `~/.rakumux/logs/tui-input.log`, written on quit and on `kill -USR1 <pid>`, or live with `rakumux --debug` |

## Start fresh, or test safely

Run a separate Rakumux, with its own server and sessions, by pointing `RAKUMUX_HOME` at another
directory:

```bash theme={null}
RAKUMUX_HOME=$(mktemp -d) rakumux
```

To report a bug, open an issue on [GitHub](https://github.com/humanunsupervised/rakumux/issues).
For a security problem, follow the
[security policy](https://github.com/humanunsupervised/rakumux/blob/main/SECURITY.md) instead.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.