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.
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.