Troubleshooting
Common issues and solutions for AgentsInFlow.
CLI Detection Issues
If AgentsInFlow cannot find an engine CLI, it shows a guided setup prompt with an install action.
CLI not found after install
Make sure the CLI is in your system PATH. Open a new terminal and run which claude (or which codex) to verify. Restart AgentsInFlow after installing.
Wrong version detected
If you have multiple versions installed, check which one is first in your PATH. Use npm list -g to see installed global packages.
Remote Access Issues
Saved port or token does not work immediately
Remote Access settings apply after restart. Use Save and Restart in the settings dialog, then open the new tokenized URL again.
Remote URL returns 404 or is not reachable
Check whether Remote Access is disabled. If it is disabled, the tokenized browser UI is not served after restart. For a one-off web-only launch, start the packaged app with --remote.
Fixed port still will not bind
Another process may already be using that port. Choose a different fixed port or leave it blank so AgentsInFlow selects a free port automatically on startup.
Tunnel works but LAN devices cannot connect
Make sure you are using your Mac's LAN IP instead of 127.0.0.1, and keep the same port and token path from the app's URL preview.
The URL works locally but not from another device
The app port may still be blocked by the macOS firewall or your network firewall. Remote Access enables the listener and the tokenized URL, but the network path still needs to allow inbound traffic before another device can connect.
Worktree Errors
Branch already checked out
Git does not allow the same branch in multiple worktrees. Choose a different target branch name or remove the existing worktree first.
Stale worktree references
If a worktree was deleted manually, run git worktree prune in your project directory to clean up stale references.
Lock file conflicts
If git reports a locked worktree, check for running processes that may be using it. You can unlock with git worktree unlock <path>.
Log Locations
App logs can help diagnose issues. Find them at these locations:
| macOS | ~/Library/Logs/AgentsInFlow/ |
| Windows | %APPDATA%\AgentsInFlow\logs\ |
Execution Recovery
If the app closes while executions are running, they are automatically marked as "paused" and saved. On next launch, paused executions appear in the Running Tasks panel. Click an execution to resume where you left off.
- Paused executions retain their terminal output and state
- Resume sends a continuation prompt to the CLI
- If resume fails, you can start a new execution from the same ticket
Common Errors
"Project directory not found"
The folder linked to the project was moved or deleted. Update the project path in project settings, or create a new project pointing to the correct folder.
"Authentication expired"
Re-run the login command for your engine CLI (for example, claude login). Credentials are stored by the CLI, not by AgentsInFlow.
"Execution failed to start"
Check that the engine CLI is installed and authenticated. Review the app logs for the specific error. Common causes include missing CLI binary, expired auth tokens, or branch creation failures.