ZhiYuan Agent

The open-source, local-first desktop AI agent — start free with a built-in model, run GGUF models locally, and assign tasks from WeChat, Feishu or DingTalk.

⬇️ Download · Quick start · Build from source · 中文

Why ZhiYuan

• 🆓 Free to start — built-in ZhiYuan free model, no third-party API key needed (network required; limits shown in app). Bring your own provider anytime.
• 💻 Runs local models — browse a model marketplace, pick a GGUF model & quantization, tune context / GPU / threads, powered by llama.cpp runtime.
• 🛠️ Actually does the work — reads & writes files, runs commands, operates a browser; creates PPT, Word, PDF, Excel outputs.
• 💬 Lives in your chat apps — WeChat, WeCom, DingTalk, Feishu/Lark, QQ, email.
• 🧩 Extensible — Experts, Skills and MCP; scheduled recurring tasks.
• 🔒 Local first — sessions, config and task metadata stored locally; approval modes for tool execution.

Get started

1. Download the installer from the official website or GitHub Releases. GitHub Releases currently ships a Windows installer; macOS and Linux packages are unconfirmed—check the download page.
2. Open the app and chat with the built-in free model — no API key required.
3. Pick a project folder, describe your task, then follow progress and approve actions as it works.

Developers: git clone https://github.com/rongxinzy/RongxinAI.git ZhiYuanAgent && cd ZhiYuanAgent && bun install && bun run electron:dev (Node 24.x, Bun 1.4.0). See Developer quick start for prerequisites and more commands.

The free model requires a network connection; availability and usage limits are shown in the app. You can also run from source on other platforms.

Use local models

Open the local inference workspace, browse the model marketplace, and choose a GGUF model and quantization suited to your hardware. Install the model and start its service. Adjust context length, GPU allocation, threads, and other options, then use a running local model for agent tasks.

Local models reduce reliance on cloud inference. Web search, model downloads, remote MCP services, and messaging channels still require their respective network services.

Data and permissions

Sessions, configuration, and task metadata are stored locally. The desktop execution environment accesses local files. When you use a cloud model or remote tool, the content needed for that request is sent to the corresponding service.

Tool execution follows the selected permission mode. Operations requiring approval display a request; automatic authorization allows some operations to run directly. Progress and results remain visible in the workspace.

How it compares

⭐ If ZhiYuan helps you, please star the repo — it helps more people find it and keeps us shipping.

Star History

Choose your workspace appearance

ZhiYuan includes Codex, Daming Fenghua, Changan Fengwu, and Weiyang Jinshi themes. Codex uses neutral surfaces and compact controls. Daming Fenghua combines paper white, cinnabar, and ink. Changan Fengwu adds silk white, peacock green, warm bronze, rounder controls, and a deep green night appearance. Weiyang Jinshi combines lacquer black, stone white, antique gold, and static cloud-scroll corner ornament.

In Settings → Appearance, select a theme preview card and choose light, dark, or system mode. Every card updates with the selected mode. Backgrounds, textures, typography, shapes, controls, and interaction states belong to the complete theme package.

To create a theme, start with the theme authoring guide and design specification. Packages supply presentation data; shared components retain interaction and state ownership.

Developer quick start

Install Git, Node.js 24.x, and Bun 1.4.0, as pinned in package.json. Native dependencies may require Python and a C/C++ toolchain when prebuilt binaries are unavailable. See the contributing guide for Windows build requirements.

git clone https://github.com/rongxinzy/RongxinAI.git ZhiYuanAgent
cd ZhiYuanAgent
bun install
bun run electron:dev

The development command prepares the channel and memory runtimes, then starts Vite and Electron. Initial runtime preparation requires network access. To use local inference, download the inference runtime for your host separately:

bun run llamacpp:runtime:download

Useful commands

Release packaging uses bun run dist:mac, bun run dist:win, or bun run dist:linux. These also involve platform runtimes, resources, and signing configuration; see CONTRIBUTING.md and package.json.

Project map

The stack includes Electron, React, TypeScript, Vite, Tailwind CSS, Redux Toolkit, and SQLite. Refer to package.json and bun.lock for dependency versions.

The renderer owns the UI, preload provides the communication boundary, and the main process owns sessions, execution, data, and service lifecycles. Task messages, tool status, and approval requests stream back to the UI. Dedicated services manage local inference, skills, MCP, and messaging channels.

Browser preview mode

Preview the renderer in a plain browser without Electron:

bun run web:preview

This starts a Vite dev server on port 5176 with a typed mock of the Electron preload API. bun run web:preview:check starts that server, walks the main screens in light and dark (sessions, a streamed reply, every settings panel, skills, MCP, automation, local inference, IM, and dialogs), fails on any console error, and writes screenshots to .github/pr-assets/browser-preview/. The mock covers the full preload contract: unimplemented calls return a typed default and warn once.

The mock is only active in browser mode (import.meta.env.DEV + no window.electron). Production builds and Electron runs use the real preload bridge.

Contribute

• Report a bug with your system, app version, reproduction steps, and relevant logs.
• Suggest a feature by describing the workflow and expected behavior.
• Contribute code or documentation. Read AGENTS.md first and follow DESIGN.md for UI changes.

Star the repository to follow the project, or share a workflow you have built with ZhiYuan.

Acknowledgments and license

Thanks to AnySearch for supporting the built-in web search capability. Its integration lives in SKILLs/web-search.

ZhiYuan Agent is licensed under the GNU Affero General Public License v3.0.