Fello is a desktop AI collaboration client built on the Agent Client Protocol (ACP). It brings local and cloud AI agents into your development workflow — all inside a native desktop app.
Fello 是一款通过 ACP（Agent Client Protocol） 协议实现的桌面 AI 协作客户端，将本地与云端 AI Agent 无缝融入你的日常开发工作流。
Talk to your codebase. Let AI handle the heavy lifting.
与你的代码对话，让 AI 处理繁重工作。
-
🧠 Multiple Agent Support — Run local Stdio agents (via ACP, like
kiro-cli acp) or connect to any OpenAI-compatible API. Switch freely between them per session. -
🧠 多种 Agent 支持 — 运行本地 Stdio Agent（通过 ACP 协议，如
kiro-cli acp），或连接任意 OpenAI 兼容 API，会话间自由切换。 -
🔧 MCP Server Integration — Dynamically attach Model Context Protocol servers (Stdio or HTTP) to supercharge your agent with extra tools.
-
🔧 MCP 服务器集成 — 动态配置 MCP 服务器（Stdio 或 HTTP），为 Agent 扩展更多能力。
-
📁 File Workspace + Terminal — Browse, edit, preview files and run terminals side by side with your AI chat. All in one panel, all synced.
-
📁 文件工作区 + 终端 — 在 AI 对话旁浏览、编辑、预览文件，同时运行终端。一体面板，实时联动。
-
🌐 WebUI Remote Access — Access your Fello from a browser on the same network. Full functionality, zero compromise.
-
🌐 WebUI 远程访问 — 在同网络的浏览器中远程使用 Fello 的全部功能，毫无妥协。
-
💬 WeChat iLink — Connect Fello to WeChat. Receive messages, reply, and stay in the loop — right from your desktop.
-
💬 微信 iLink — 将 Fello 接入微信，在桌面端收发消息，时刻在线。
-
🎨 Beautiful & Modern UI — Dark/light themes, responsive layout, tabbed panels, and smooth streaming chat.
-
🎨 美观现代的界面 — 深色/浅色主题、响应式布局、标签面板、流畅的流式对话。
-
🛡️ Permission Control — Granular tool permission with "Always Allow" memory. Stay in control, avoid repetitive approvals.
-
🛡️ 权限控制 — 细粒度的工具权限管理，支持"始终允许"记忆，掌控一切，免去重复确认。
| Feature | Description |
|---|---|
| Local Agents | Stdio agents via ACP protocol for private, offline-capable workflows |
| API Agents | Connect to OpenAI-compatible APIs (streaming text, reasoning, file content) |
| MCP Servers | Dynamic tool integration via Model Context Protocol |
| File Tree | Browse, create, rename, delete, drag-drop files — with preview for images, markdown, code, PDF, DOCX, XLSX |
| Terminal | Full xterm.js terminal with node-pty, multi-tab support, auto-persisted logs |
| Diff View | Side-by-side file diffing (Git-style) for code reviews |
| WebUI | Browser access over local network via WebSocket |
| WeChat iLink | Mobile ↔ Desktop messaging bridge |
| Skills | Browse & install from skills.sh marketplace |
| Chat Timeline | Jump between messages with timeline dots |
| Auto Titles | Sessions auto-name themselves from your first message |
| Multi-language | English & Chinese (more locales extensible via i18next) |
| Token Stats | Real-time input/output/thinking token counters |
# Install dependencies
# 安装依赖
npm install
# Launch in development mode
# 启动开发模式
npm run dev
# Build for production
# 构建生产版本
npm run build
# Package for your platform
# 打包为桌面应用
npm run pack:mac # macOS
npm run pack:win # Windows
npm run pack:linux # Linux
# Package as npm package (headless server)
# 打包为 npm 包（无头服务器）
npm run pack:npm # → npm-package/Download the latest release → Releases
Run Fello as a pure Node.js server — no Electron, no display required. Perfect for Linux servers or CI environments.
# Via npx (no install needed)
npx @zythum02/fello-server --port 9090 --token mysecret
# Or install globally
npm install -g @zythum02/fello-server
fello-server -p 9090 -t mysecret
# Package locally
npm run pack:npm
cd npm-package
npm publish --access publicThe server serves the same WEBUI frontend over HTTP/WebSocket, with full session/agent/file/terminal support.
When accessing the WEBUI in a browser:
- Visit the provided URL with
?token=xxx(e.g.http://192.168.1.100:9090/?token=abc123) - The server validates the token and sets a session cookie (
fello_token) - Subsequent requests (JS, CSS, WebSocket, project files) authenticate via cookie
- Page requests (
/) always require?token=in the URL — cookie alone is not accepted for initial page loads - The cookie is a session cookie (no
Max-Age), cleared when the browser closes
This means each browser session needs the token URL once; refreshing the page works as long as the browser is open.
navigator.clipboard requires a secure context (HTTPS). When accessing WEBUI over plain HTTP, the app automatically falls back to document.execCommand("copy") for copy operations. Paste requires navigator.clipboard.readText() which has no HTTP fallback — the paste button is hidden when the API is unavailable.
- Desktop Shell: Electron
- Renderer: React + Vite + Tailwind CSS
- AI Protocol: ACP (Agent Client Protocol) SDK + AI SDK
- State Management: Zustand
- i18n: i18next + react-i18next
- Terminal: xterm.js + node-pty
- Build: electron-vite + electron-builder
npm run dev starts:
- Vite dev server on
http://localhost:6234with HMR enabled - Electron loads the renderer from the Vite dev server
- React components update instantly without full page reload
Main/preload changes typically require restarting the dev process.
├── src/
│ ├── shared/ # Typed IPC contracts & shared types
│ ├── agents/ # Agent session logic (ACP + MCP tools, permissions, system prompts)
│ ├── backend/ # IPC handlers, FS, Terminal, WebUI, Skills
│ │ ├── agents/ # Agent process spawners (stdio, API)
│ │ └── ilink/ # WeChat iLink integration
│ ├── electron/ # Electron main process
│ └── mainview/ # React app (components, routing, store, i18n, styles)
├── docs/ # Architecture, guides, conventions
├── tools/ # Build scripts
└── icons/ # App icons
| What | Where to Edit |
|---|---|
| React components | src/mainview/ |
| Routing | src/mainview/router.tsx |
| i18n translations | src/mainview/locales/*.json |
| Window / lifecycle | src/electron/main.ts |
| Backend logic | src/backend/backend.ts + src/backend/agent/agent-bridge.ts |
| IPC bridge | src/scripts/electron-preload/preload.ts, src/mainview/backend.ts |
| IPC types | src/shared/schema.ts |
| Agent implementations | src/agents/ + src/backend/agents/ |
| Build config | electron.vite.config.ts |
npm run dev # Development with HMR
npm run build # Production build
npm run preview # Preview built app
npm run lint # Lint with oxlint
npm run typecheck # TypeScript checking
npm run format # Format with oxfmt
# Package
npm run pack:npm # Build npm package → npm-package/
npm run pack:mac # macOS .dmg
npm run pack:win # Windows .exe
npm run pack:linux # Linux .AppImage- Overview
- Tech Stack
- Architecture
- Project Structure
- Coding Conventions
- Custom Events
- IPC Protocol
- Built-in ACP Tools
- Storage & Data
Built with ❤️ by Zythum · GPL-3.0-or-later