feat(agent): support custom executable locations for external agents

[ryan-wong-coder]

Background

Flowix currently relies on PATH and a hard-coded list of common installation locations to discover external CLI agents. This is fragile for GUI-launched desktop applications, version managers, portable installations, application-bundled CLIs, and custom installation directories. Adding more hard-coded paths solves individual cases but does not provide a complete user-facing solution.

Proposal

Add a consistent custom-location setting for every third-party/external Agent runtime, including Codex, Claude Code, Hermes, Gemini CLI, OpenClaw, and future external CLI agents. The built-in Flowix Agent does not need this option.

For each external Agent in Preferences:

• Add a Use custom location checkbox.
• When checked, reveal a path field and Choose… button.
• Let the user select either the Agent executable itself or its containing folder, depending on the platform/API constraints. Flowix should resolve the expected executable name inside a selected folder (codex, claude, hermes, gemini, etc.; Windows variants such as .exe and .cmd should be supported).
• Display the resolved executable path and current validation status.
• Provide Change, Clear, and Test actions.
• Show a useful error when the path is missing, is not a file, is not executable, or cannot run its version/probe command.

Resolution priority

When starting or checking an external Agent, resolve its binary in this order:

1. User-selected custom location.
2. Existing explicit environment-variable override, if supported.
3. Current process PATH.
4. Known platform-specific fallback locations.
5. Unavailable state with an actionable setup message.

If a configured custom path becomes invalid, Flowix should show that configuration error rather than silently running a different binary. The user can clear the custom setting to return to automatic detection.

Persistence and platform behavior

• Store custom paths in Flowix user configuration per Agent type.
• Keep the setting synchronized across Flowix windows through the existing configuration event mechanism.
• Use the native Tauri file/folder dialog.
• Preserve macOS security-scoped access/bookmarks where required.
• Normalize Windows paths and support executable wrappers such as .cmd.
• Do not store this preference only in shell environment variables; it must work when Flowix is launched from Finder, Dock, Start Menu, or Explorer.

UI behavior

The Agent runtime status view and / menu should use the same resolved runtime state. Preferences should expose the exact reason an Agent is unavailable instead of requiring users to infer it from an empty / menu.

Suggested states:

• Available — custom location
• Available — automatically detected
• Invalid custom location
• Not detected

Acceptance criteria

• Every selectable external Agent has a Use custom location option.
• Enabling it reveals a native path chooser.
• The chosen location persists across application restarts.
• Runtime detection, status UI, and Agent execution all use the same resolved path.
• A valid custom location makes the Agent available in the / menu.
• An invalid custom location produces an actionable error and does not silently fall back.
• Clearing the setting restores automatic detection.
• macOS, Windows, and Linux path behavior is covered by tests.
• Existing users retain the current automatic detection behavior by default.

Related

Related to #3, which covers one missing automatic fallback path for the Codex binary bundled with ChatGPT.app. This Issue proposes the general configuration mechanism so similar installation layouts do not require one-off code changes.