Troubleshooting

Fixes for common Open Free Max issues — CLI not found, installer checks, agents that don't start, sessions that stall, and what to report after a crash.

Common issues and how to resolve them.

The agent CLI isn’t found

When a CLI is not detected, the agent panel shows a step-by-step installation assistant with copy-ready commands for your OS and target (Windows, macOS, WSL). Use the Re-check button after installing to update the panel state without restarting.

If the assistant shows the CLI as present but the agent still won’t start:

Confirm the CLI runs in a normal terminal (claude --version, etc.).
On macOS, make sure it’s on your login shell’s PATH (homebrew/nvm/~/.claude/local).
For a WSL project, the CLI must be installed in the distro — see Native WSL2.

Windows publisher warning

The Windows MSI is signed by APPS VELOCITY with Azure Artifact Signing. The macOS DMG and application are signed and notarized by Apple. No bypass or xattr command is required. If Windows shows an unexpected warning, confirm that you downloaded the installer from the official download section and that its publisher is APPS VELOCITY. See Install.

An agent “does nothing”

Open the session in Mission Control — the pane shows the agent’s real screen, which is usually enough to see the cause. Common ones:

A first-time permission/trust prompt is waiting — answer it from the queue or set an appropriate autonomy level.
The CLI is idle waiting for input after finishing its task.

Every session says “rate-limited”

That’s a token-limit window — expected on a subscription. The session shows the reset time and picks back up once the quota reopens. Run fewer sessions at once if you want to spread usage and hit the cap less often. See Consumption.

The app crashed — what do I report?

Since 1.1.3, every crash is written to a crash black box: panic.log in the config directory (%APPDATA%\com.openfreemax.ide\ on Windows, ~/Library/Application Support/com.openfreemax.ide/ on macOS). It records the error message and the exact source location — attach the last lines to your bug report.

Lost session / blank tab

OFM rebuilds its session map from the CLI’s on-disk history. If a tab can’t resume, the transcript may have been removed from the CLI’s store (outside OFM). See Sessions & persistence.