# Pinvou Agent **An open-source desktop AI agent workspace for work, design, and coding.** [English](README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) [![CI](https://github.com/Pinvou/pinvou-agent/actions/workflows/pr-check.yml/badge.svg)](https://github.com/Pinvou/pinvou-agent/actions/workflows/pr-check.yml) [![License: MIT](https://img.shields.io/github/license/Pinvou/pinvou-agent)](LICENSE) [![Version](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FPinvou%2Fpinvou-agent%2Fmain%2Fpinvou3-app%2Fpackage.json&query=%24.version&label=version&color=blue)](pinvou3-app/package.json) [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)](#-quick-start) [![GitHub Stars](https://img.shields.io/github/stars/Pinvou/pinvou-agent?style=flat)](https://github.com/Pinvou/pinvou-agent/stargazers) [Download Preview](https://github.com/Pinvou/pinvou-agent/releases) · [Website](https://pinvou.com/) · [QQ Group](#-community--security) · [Issues](https://github.com/Pinvou/pinvou-agent/issues) · [Discussions](https://github.com/Pinvou/pinvou-agent/discussions) · [Security](SECURITY.md)

▶ Watch the 90-second feature demo (Chinese)

Pinvou Agent is more than a chat window. It brings everyday work, visual design, and software development into one desktop workspace — designed for tasks that should end with **a result**, not just another chat response. Use tools, work with files, and build personal knowledge; bring a dedicated coding agent into a real project over ACP; or turn a prompt into a visual artifact you can continue editing. Use a local model for a fully private loop, connect any OpenAI-compatible endpoint, and extend the agent with MCP servers, CLI connectors, Skills, and workflows. ## 🧭 One workspace, three ways to work ### 💼 Work: give the agent a real task Combine attachments, personal knowledge, specialist personas, Skills, MCP tools, and workflows to research, analyze, write, and deliver reusable files — not just another block of chat text. ### 🎨 Design: from a prompt to an editable visual Create posters and data visualizations in natural language. Open the result in design mode, select elements directly, and adjust copy, fonts, colors, dimensions, and layout — or keep describing changes and let the agent iterate on the current design. ### 💻 Code: bring a coding agent into a real project Use **Codex, Claude Code, or Kimi** through [ACP](docs/multi-agent-acp.md) in the same desktop workspace. The coding agent can read and edit a real project or an isolated temporary workspace, run commands, and surface plans, tool steps, permission requests, and file changes. Sessions stay bound to their workspace and can be continued after restarting the app. ## ✨ Features ### 🎯 From conversation to deliverables - **Multi-session workspace** with title search — messages, tool calls, and artifacts persist with each session - **Attachments** for PDF, Office documents, images, and text — drag, drop, or paste them in - **Artifact panel** automatically collects every file the agent creates or edits; preview, locate, and open them in one place - **Editable Markdown artifacts** — edit directly, or select a passage and ask the agent to revise it - **Plan / YOLO modes** — review the plan first for complex work, or execute directly when the task is clear - **Auxiliary chat** — ask side questions while a task runs, in a per-task side session whose only tool is a server-enforced read-only view of that task's own history (ADR-0024), isolated from the task's execution context ### 🧠 Knowledge and memory - **Local knowledge base** with file management, full-text and vector retrieval; attach multiple collections to one chat, enable or disable each independently, and retain collection and file provenance in answers - **Memory center** captures long-term preferences and context, with explicit candidate review and confirmation - **Persona card pool** — create, save, and apply specialist roles for different domains - **Skills, Commands, and workflows** turn proven methods into stable, reusable capabilities ### 🔌 Real tools and connectors - **Unified tool store** for local MCP servers, remote MCP servers, CLI tools, and API connectors - **OAuth / SSO authorization** where supported — no manual key pasting - Ready-made connectors for **Feishu (Lark), DingTalk, WeCom, Tencent Meeting, Tencent ima, Obsidian**, enterprise knowledge bases, and legal / enterprise data services - **Remote control** — scan a QR code from your phone to view and steer the running workspace ### 🖥️ Built for daily operation - **Global bring-to-front shortcut** (off by default, `Ctrl/Cmd+Alt+P`) — enable it in Settings → General to summon the window with a key while it runs in the background - **Local voice input** with on-demand speech model downloads - **Centralized monitoring** of GPU, memory, disk, model service, and context usage - **Updates via GitHub Releases** — in-app update checks are not enabled yet - Sessions, settings, knowledge, and runtime extensions all live under `~/.pinvou3/` > [!NOTE] > Whether data leaves your machine depends on the model and tools you enable. A local model with local tools stays fully local. Cloud models, remote MCP servers, and third-party connectors send the relevant requests to their respective services. ## 📸 Screenshots


Design mode for posters and data visualizations	Code mode with Codex, Claude Code, and Kimi

Extend the agent with tools and connectors	Preview and deliver generated artifacts

## 🤖 Model Access Pinvou Agent works with **local vLLM** and any **OpenAI-compatible API**. Save multiple model configurations in the app, give cloud configurations optional display aliases, and switch between them per session without changing the model identifier sent to the provider. Built-in templates cover local vLLM, DeepSeek, Kimi, Qwen, Doubao, MiniMax, Zhipu (GLM), MiMo, OpenAI, Anthropic, Gemini, and xAI — or fill in any custom compatible endpoint. Local vLLM example: ```bash export DEEPSEEK_BASE_URL="http://127.0.0.1:8000/v1" export DEEPSEEK_API_KEY="local-no-auth" export DEEPSEEK_MODEL="your-model-name" ``` Endpoints, model names, and API keys can also be managed directly in the application settings. For a non-loopback plain HTTP endpoint in a trusted development network, explicitly set `DEEPSEEK_ALLOW_INSECURE_HTTP=1`. ## 🚀 Quick Start ### Prerequisites - Git with submodule support - Node.js and npm - A current Rust toolchain - The [Tauri 2 system dependencies](https://v2.tauri.app/start/prerequisites/) for your platform - An accessible OpenAI-compatible model endpoint The source tree supports **Linux, Windows, and macOS**. Linux release packages target Ubuntu 22.04 or newer (glibc 2.35+) on x86_64 and arm64, and LoongArch64 (new-world; UOS V25 or deepin 23 or newer, glibc 2.38+); the deb also requires WebKitGTK 2.40+ (any 22.04 system with the standard updates pocket applied satisfies this). Old-world LoongArch systems (UOS V20 Loongson Edition, Loongnix 20, and the Kylin V10 era) are not supported — they offer no webkit2gtk-4.1/libsoup3, which the Tauri 2 runtime requires, and their rustc toolchains top out at 1.58. macOS release packages are universal (Apple Silicon and Intel) builds for macOS 11 or later. Speech-recognition engines can be packaged per build configuration; file parsing (PDF / Office / OCR / archives) relies on optional external tools installable via your platform's package manager (see `pinvou3-app/INSTALL.md`). ### Run from source ```bash git clone --recursive https://github.com/Pinvou/pinvou-agent.git cd pinvou-agent/pinvou3-app npm ci cd .. ./pinvou3-app/run-dev.sh ``` If you cloned without submodules: ```bash git submodule update --init --recursive ``` ## 🏗️ Architecture [![Tauri](https://img.shields.io/badge/Tauri-2.0-24C8D8?logo=tauri&logoColor=white)](https://v2.tauri.app/) [![React](https://img.shields.io/badge/React-19-61DAFB?logo=react&logoColor=white)](https://react.dev/) [![Vite](https://img.shields.io/badge/Vite-8-646CFF?logo=vite&logoColor=white)](https://vite.dev/) [![Rust](https://img.shields.io/badge/Rust-stable-DEA584?logo=rust&logoColor=white)](https://www.rust-lang.org/) ```text React + Vite UI ↕ Tauri commands / events pinvou3-app (desktop orchestration) ↕ EngineHandle / AgentHarness CodeWhale (agent engine submodule) ├─ OpenAI-compatible model services ├─ MCP servers and CLI connectors └─ Skills, Commands, Hooks, and Compaction ``` [CodeWhale](https://github.com/Pinvou/CodeWhale) provides the agent engine: model calls, streaming, tool execution, sessions, MCP, Skills, hooks, and compaction. `pinvou3-app/` owns the desktop UI, runtime configuration, orchestration, and operating-system integration — it never re-implements engine capabilities. | Extension goal | Where it belongs | |---|---| | Add a domain agent or tool bundle | A `SKILL.md` package | | Connect an external API | An independent MCP server or connector | | Guide model behavior | Bundle instructions (`instructions.md`) | | Change desktop UI or system integration | `pinvou3-app/` | | Fix a reusable engine issue | The CodeWhale fork, following the [fork policy](docs/fork-policy.md) | ## 📁 Repository Layout ```text pinvou3-app/ Tauri 2 + React/Vite desktop application CodeWhale/ Agent engine submodule pinvou-knowledge/ Reusable knowledge core and self-contained server remote-control-relay/ Optional self-hosted relay for QR-code remote control pinvou3-app/resources/mcp-servers/ Independent local MCP servers scripts/ Tests, guards, build, and release helpers docs/ Architecture and maintenance documentation ``` ## 🧪 Development Checks Run these commands from the repository root: ```bash (cd pinvou3-app && npm run lint:ui) (cd pinvou3-app && npm run build:ui) (cd pinvou3-app && npm test) (cd pinvou3-app/src-tauri && cargo test --lib -- --test-threads=1) ./scripts/fork-guard.sh --fast ``` ## 🤝 Contributing Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow and CI gates, and [docs/fork-policy.md](docs/fork-policy.md) with the [current fork modification inventory](docs/fork-modifications.md) for CodeWhale maintenance rules. By participating, you agree to our [Code of Conduct](CODE_OF_CONDUCT.md). ## 💬 Community & Security - 🐧 **QQ user group (Chinese): 1108909346** — scan the QR code below or search for the group number in QQ - 🐛 [GitHub Issues](https://github.com/Pinvou/pinvou-agent/issues) — reproducible bugs and focused feature requests - 💡 [GitHub Discussions](https://github.com/Pinvou/pinvou-agent/discussions) — questions and ideas (community support is best-effort, see [SUPPORT.md](SUPPORT.md)) - 🔒 **Do not report security vulnerabilities in public issues** — use the private channel in [SECURITY.md](SECURITY.md) or email `security@pinvou.com`

QR code for the Pinvou Agent official QQ user group, group number 1108909346

Licensing, third-party attribution, SBOM, brand-use boundaries, and the extension marketplace overview are documented in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md), [docs/sbom.md](docs/sbom.md), [TRADEMARKS.md](TRADEMARKS.md), and [docs/工具市场.md](docs/工具市场.md). ## 🔗 Friendly Links - [LINUX DO](https://linux.do/) ## ⭐ Star History

Star History Chart

---

Pinvou Agent is under active development — the `main` branch and the latest release notes are the source of truth for current behavior. **[MIT License](LICENSE)** · Made with ❤️ by the Pinvou team and contributors