Troubleshooting

Fixes for common Open Free Max issues — CLI not found, unsigned-build warnings, agents that don't start, bulk runs 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.

”Unidentified developer” / SmartScreen warning

Builds aren’t code-signed/notarized yet. On Windows click More info → Run anyway. On macOS, move the app to Applications, then run xattr -cr "/Applications/Open Free Max IDE.app" and open it via System Settings → Privacy & Security → Open Anyway. On Apple Silicon, if it’s reported as damaged, re-sign it ad-hoc with sudo codesign --force --deep --sign - "/Applications/Open Free Max IDE.app". Full steps in Install.

A bulk agent “does nothing”

Open the Workers drill-down. If a unit is quarantined, the captured last screen shows the cause. Common ones:

The agent finished without writing the {output} — tell it the exact path and to write it last.
A first-time permission/trust prompt is waiting — set an appropriate autonomy level or use remember for the whole campaign.

Everything is parked, nothing runs

That’s usually a token-limit window — expected in bulk on a subscription. Plan auto-resumes when the quota reopens (the card shows the resume time). Lower the pool if you want to spread usage and hit the cap less often.

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.