The All-in-One Manager for Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw & Hermes Agent
Warning
FyAgent 0.3.0 is defined as a stable, public, intentionally unsigned
release. Windows executables and MSI packages have Authenticode status
NotSigned, and the macOS app is not Developer ID signed or notarized. Read
the v0.3.0 Release Notes and verify the
release evidence before installing. Publication remains gated on the formal
workflow; this notice does not claim that the Release already exists.
Modern AI-powered coding relies on tools like Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, and Hermes — but each has its own configuration format. Switching API providers means manually editing JSON, TOML, or .env files, and there is no unified way to manage MCP and Skills across multiple tools.
FyAgent gives you a single desktop app to manage all supported AI tools. Instead of editing config files by hand, you get a visual interface to import providers with one click, switch between them instantly, with 50+ built-in provider presets, unified MCP and Skills management, and system tray quick switching — all backed by a reliable SQLite database with atomic writes that protect your configs from corruption.
- One App, Eight Tools — Manage Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, and Hermes from a single interface
- No More Manual Editing — 50+ provider presets including AWS Bedrock, NVIDIA NIM, and community relays; just pick and switch
- Unified MCP & Skills Management — One panel to manage MCP servers and Skills across Claude, Codex, Gemini, Grok Build, OpenCode, and Hermes with bidirectional sync
- System Tray Quick Switch — Switch providers instantly from the tray menu, no need to open the full app
- Cloud Sync — Sync provider data across devices via Dropbox, OneDrive, iCloud, or WebDAV servers
- Cross-Platform — Native desktop app for Windows, macOS, and Linux, built with Tauri 2
- Built-in Utilities — Includes utilities for first-launch login confirmation, environment diagnostics, plugin extension sync, and more
| Main Interface | Add Provider |
|---|---|
 |
 |
Full Changelog | v0.3.0 Release Notes
- 8 supported tools, 50+ presets — Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, Hermes; copy your key and import with one click
- Universal providers — One config syncs to Claude Code, Codex, and Gemini CLI
- One-click switching, system tray quick access, drag-and-drop sorting, import/export
- Local proxy with hot-switching — Format conversion, auto-failover, circuit breaker, provider health monitoring, and request rectifier
- App-level takeover — Independently proxy Claude, Codex, Gemini, or Grok Build, down to individual providers
- Unified MCP panel — Manage MCP servers across Claude, Codex, Gemini, Grok Build, OpenCode, and Hermes with bidirectional sync and Deep Link import
- Prompts — Markdown editor with cross-app sync (CLAUDE.md / AGENTS.md / GEMINI.md) and backfill protection
- Skills — One-click install from GitHub repos or ZIP files, custom repository management, with symlink and file copy support
- Usage dashboard — Track spending, requests, and tokens with trend charts, detailed request logs, and custom per-model pricing
- Browse, search, and restore conversation history across supported session sources
- Workspace editor (OpenClaw) — Edit agent files (AGENTS.md, SOUL.md, etc.) with Markdown preview
- Cloud sync — Custom config directory (Dropbox, OneDrive, iCloud, NAS) and WebDAV server sync
- Deep Link (
fyagent://) — Import providers, MCP servers, prompts, and skills via URL - Dark / Light / System theme, auto-launch, manual release downloads (no in-app auto-update), atomic writes, auto-backups, i18n (zh/zh-TW/en/ja)
Which AI tools does FyAgent support?
FyAgent supports eight tools: Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, and Hermes. Each tool has dedicated provider presets and configuration management.
Do I need to restart the terminal after switching providers?
For most tools, yes — restart your terminal or the CLI tool for changes to take effect. The exception is Claude Code, which currently supports hot-switching of provider data without a restart.
My plugin configuration disappeared after switching providers — what happened?
FyAgent provides a "Shared Config Snippet" feature to pass common data (beyond API keys and endpoints) between providers. Go to "Edit Provider" → "Shared Config Panel" → click "Extract from Current Provider" to save all common data. When creating a new provider, check "Write Shared Config" (enabled by default) to include plugin data in the new provider. All your configuration items are preserved in the default provider imported when you first launched the app.
macOS installation
FyAgent 0.3.0 is intentionally unsigned and not notarized, so macOS may block the first launch. After attempting to open FyAgent once, use Apple's supported System Settings → Privacy & Security → Open Anyway flow and confirm the prompt. Verify the exact Release Notes and evidence first; do not disable Gatekeeper or remove quarantine metadata.
Why can't I delete the currently active provider?
FyAgent follows a "minimal intrusion" design principle — even if you uninstall the app, your CLI tools will continue to work normally. The system always keeps one active configuration, because deleting all configurations would make the corresponding CLI tool unusable. If you rarely use a specific CLI tool, you can hide it in Settings. To switch back to official login, see the next question.
How do I switch back to official login?
Add an official provider from the preset list. After switching to it, run the Log out / Log in flow, and then you can freely switch between the official provider and third-party providers. Codex supports switching between different official providers, making it easy to switch between multiple Plus or Team accounts.
Where is my data stored?
- Database:
~/.fyagent/fyagent.db(SQLite — providers, MCP, prompts, skills) - Local settings:
~/.fyagent/settings.json(device-level UI preferences) - Backups:
~/.fyagent/backups/(auto-rotated, keeps 10 most recent) - Skills:
~/.fyagent/skills/(symlinked to corresponding apps by default) - Skill Backups:
~/.fyagent/skill-backups/(created automatically before uninstall, keeps 20 most recent)
Linux (Wayland + NVIDIA): clicks don't register and the window black-screens on resize
The AppImage forces GDK_BACKEND=x11 (XWayland) to avoid a historical native-Wayland crash. On newer Wayland + NVIDIA setups this can leave the web content area unclickable (the title-bar buttons still work) and black-screen on resize. Launch with the opt-in escape hatch to switch back to native Wayland:
FYAGENT_GDK_BACKEND=wayland ./FyAgent-*.AppImageIf you launch from a desktop icon, add it to the .desktop Exec= line (e.g. env FYAGENT_GDK_BACKEND=wayland /path/to/AppImage) or set it in your session environment. The variable is generic: on tiling Wayland compositors (sway/Hyprland) where clicks don't register, try FYAGENT_GDK_BACKEND=x11 instead. Leaving it unset keeps the default behavior.
For detailed guides on every feature, check out the User Manual — covering provider management, MCP/Prompts/Skills, proxy & failover, and more.
- Add Provider: Click "Add Provider" → Choose a preset or create custom configuration
- Switch Provider:
- Main UI: Select provider → Click "Enable"
- System Tray: Click provider name directly (instant effect)
- Takes Effect: Restart your terminal or the corresponding CLI tool to apply changes (Claude Code does not require a restart)
- Back to Official: Add an "Official Login" preset, restart the CLI tool, then follow its login/OAuth flow
- MCP: Click the "MCP" button → Add servers via templates or custom config → Toggle per-app sync
- Prompts: Click "Prompts" → Create presets with Markdown editor → Activate to sync to live files
- Skills: Click "Skills" → Browse GitHub repos → One-click install to supported apps
- Sessions: Click "Sessions" → Browse, search, and restore conversation history across supported session sources
Note: On first launch, you can manually import existing CLI tool configs as the default provider.
- Windows: Windows 10 and above
- macOS: macOS 12 (Monterey) and above
- Linux: Ubuntu 22.04+ / Debian 11+ / Fedora 34+ and other mainstream distributions
Download FyAgent-0.3.0-Windows.msi on x64 or
FyAgent-0.3.0-Windows-arm64.msi on ARM64 from the
Releases page. FyAgent no
longer publishes a Windows Portable ZIP because the supported Windows
application uses the protected per-machine MSI path.
Unsigned build: The v0.3.0 executable and MSI intentionally report Authenticode
NotSigned, so Windows SmartScreen may warn. Confirm the asset name and the published manifest/attestation evidence before continuing; do not disable SmartScreen or weaken an organization-managed security policy.
Download FyAgent-0.3.0-macOS.dmg (recommended) or
FyAgent-0.3.0-macOS.zip from the
Releases page.
Unsigned build: v0.3.0 is intentionally not Developer ID signed or notarized. After attempting to open the app once, use System Settings → Privacy & Security → Open Anyway and confirm the prompt. Verify the Release evidence first; do not disable Gatekeeper or strip quarantine metadata.
Download the matching native Linux build from the Releases page:
- x64:
FyAgent-0.3.0-Linux-x86_64.AppImage,FyAgent-0.3.0-Linux-x86_64.deb, orFyAgent-0.3.0-Linux-x86_64.rpm - ARM64:
FyAgent-0.3.0-Linux-arm64.AppImage,FyAgent-0.3.0-Linux-arm64.deb, orFyAgent-0.3.0-Linux-arm64.rpm
Flatpak: Not included in official releases. You can build it yourself from the
.deb— seeflatpak/README.mdfor instructions.
Exact v0.3.0 attachment contract
The formal Release is allowed exactly ten installers: the two macOS files, two
Windows MSI files, and six Linux files named above. It also carries exactly
three evidence attachments — download-manifest.json (including each
installer's SHA-256), build-metadata.json, and
artifact-attestation.sigstore.json — for 13 attachments total. The
workflow rejects missing, duplicate, renamed, or extra files. Treat these as
the publication contract until a completed formal run and independent
post-publication verification are recorded.
Architecture Overview
┌─────────────────────────────────────────────────────────────┐
│ Frontend (React + TS) │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ Components │ │ Hooks │ │ TanStack Query │ │
│ │ (UI) │──│ (Bus. Logic) │──│ (Cache/Sync) │ │
│ └─────────────┘ └──────────────┘ └──────────────────┘ │
└────────────────────────┬────────────────────────────────────┘
│ Tauri IPC
┌────────────────────────▼────────────────────────────────────┐
│ Backend (Tauri + Rust) │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ Commands │ │ Services │ │ Models/Config │ │
│ │ (API Layer) │──│ (Bus. Layer) │──│ (Data) │ │
│ └─────────────┘ └──────────────┘ └──────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Core Design Patterns
- SSOT (Single Source of Truth): All data stored in
~/.fyagent/fyagent.db(SQLite) - Dual-layer Storage: SQLite for syncable data, JSON for device-level settings
- Dual-way Sync: Write to live files on switch, backfill from live when editing active provider
- Atomic Writes: Temp file + rename pattern prevents config corruption
- Concurrency Safe: Mutex-protected database connection avoids race conditions
- Layered Architecture: Clear separation (Commands → Services → DAO → Database)
Key Components
- ProviderService: Provider CRUD, switching, backfill, sorting
- McpService: MCP server management, import/export, live file sync
- ProxyService: Local proxy mode with hot-switching and format conversion
- SessionManager: Conversation history browsing across supported session sources
- ConfigService: Config import/export, backup rotation
- SpeedtestService: API endpoint latency measurement
Development Guide
- mise 2026.8.0 or newer, installed globally
- Tauri 2.0 system prerequisites
The repository pins Node.js 24.19.0 in .node-version, pnpm 10.12.3 in
package.json, Rust 1.97.1 in rust-toolchain.toml, and Python 3.14.7 in
.python-version. mise.toml owns the task API and the uv selector;
mise.lock, uv.lock, and the uv-managed .venv lock the approved Python
environment. The Tauri CLI is installed with the project dependencies.
After reviewing the repository config, initialize the development environment:
mise trust
mise run bootstrap
mise run system:check
mise run devmise trust is an explicit developer security decision and no project task
runs it automatically. bootstrap does not install privileged system packages,
change Git remotes, refresh locks, or publish. WSL must not resolve managed
tools from /mnt/<drive> or Windows shims. See the generated
canonical task catalog for the full
API.
Local development and packaging support only the current host operating system. The standard commands do not accept another OS or architecture target:
mise run dev
mise run buildFyAgent installers are built only by GitHub Actions on native Windows x64 and ARM64, Linux x64 and ARM64, and macOS runners. The macOS job produces the Universal build. Local Linux/WSL-to-Windows or macOS packaging is not a supported release path.
# Install locked dependencies and verify the environment
mise run bootstrap
# Dev mode (hot reload)
mise run dev
# Type check
mise run typecheck
# Format code
mise run format
# Check code format
mise run format:check
# Run frontend unit tests
mise run test:unit
# Run tests in watch mode (recommended for development)
mise run test:unit:watch
# Build application
mise run build
# Build debug version
mise run build:debug# Format Rust code
mise run rust:fmt
# Run clippy checks
mise run rust:clippy
# Run backend tests
mise run rust:test
# Run specific tests
mise run rust:test test_name
# Run the complete current-host gate before a pull request
mise run checkFrontend Testing:
- Uses vitest as test framework
- Uses MSW (Mock Service Worker) to mock Tauri API calls
- Uses @testing-library/react for component testing
Running Tests:
# Run all tests
mise run test:unit
# Watch mode (auto re-run)
mise run test:unit:watch
# Complete frontend gate
mise run check:frontendFrontend: React 18 · TypeScript · Vite · TailwindCSS 3.4 · TanStack Query v5 · react-i18next · react-hook-form · zod · shadcn/ui · @dnd-kit
Backend: Tauri 2.8 · Rust · serde · tokio · thiserror · tauri-plugin-process/dialog/store/log
Testing: vitest · MSW · @testing-library/react
Project Structure
├── src/ # Frontend (React + TypeScript)
│ ├── components/
│ │ ├── providers/ # Provider management
│ │ ├── mcp/ # MCP panel
│ │ ├── prompts/ # Prompts management
│ │ ├── skills/ # Skills management
│ │ ├── sessions/ # Session Manager
│ │ ├── proxy/ # Proxy mode panel
│ │ ├── openclaw/ # OpenClaw config panels
│ │ ├── settings/ # Settings (Terminal/Backup/About)
│ │ ├── deeplink/ # Deep Link import
│ │ ├── env/ # Environment variable management
│ │ ├── universal/ # Cross-app configuration
│ │ ├── usage/ # Usage statistics
│ │ └── ui/ # shadcn/ui component library
│ ├── hooks/ # Custom hooks (business logic)
│ ├── lib/
│ │ ├── api/ # Tauri API wrapper (type-safe)
│ │ └── query/ # TanStack Query config
│ ├── locales/ # Translations (zh/zh-TW/en/ja)
│ ├── config/ # Presets (providers/mcp)
│ └── types/ # TypeScript definitions
├── src-tauri/ # Backend (Rust)
│ └── src/
│ ├── commands/ # Tauri command layer (by domain)
│ ├── services/ # Business logic layer
│ ├── database/ # SQLite DAO layer
│ ├── proxy/ # Proxy module
│ ├── session_manager/ # Session management
│ ├── deeplink/ # Deep Link handling
│ └── mcp/ # MCP sync module
├── tests/ # Frontend tests
└── assets/ # Screenshots
Issues and suggestions are welcome!
Before submitting PRs, please ensure:
- Run the complete current-host gate:
mise run check - Use focused tasks from the canonical task catalog while developing
For new features, please open an issue for discussion before submitting a PR. PRs for features that are not a good fit for the project may be closed.
FyAgent is source-available software, not open source as defined by the Open Source Initiative. FyAgent-owned components and modifications are licensed under the PolyForm Noncommercial License 1.0.0. Commercial use requires separate written authorization. CC Switch-derived portions remain under the MIT License. See LICENSE, LICENSING.md, and THIRD_PARTY_NOTICES.md.