Pinvou Agent

English | 简体中文

An open-source desktop AI agent that can use tools, work with files, build knowledge, and deliver real artifacts.

Website · CodeWhale engine · Security · MIT License

Pinvou Agent brings models, tools, personal knowledge, specialist personas, and reusable workflows into one desktop workspace. It is designed for work that should end with a result—not just another chat response.

Use a local model for a private loop, connect any OpenAI-compatible endpoint, or extend the agent through MCP servers, CLI connectors, Skills, and workflows.

What you can do

• Turn conversations into deliverables — create and edit Markdown, documents, spreadsheets, code, and other files, then preview every generated artifact in one place.
• Work with your own context — import PDF, Office, image, and text attachments; search local knowledge; and manage long-term memory explicitly.
• Let the agent use tools — connect MCP servers, local CLI tools, and external APIs from a unified tool store.
• Reuse reliable methods — package domain behavior as Skills, Commands, specialist personas, or multi-step workflows.
• Choose how the agent acts — use Plan mode for review-first work or YOLO mode for direct execution.
• Run locally or in the cloud — use local vLLM or any compatible model provider without locking the application to one vendor.

A workspace built for outcomes

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

Core capabilities

[!NOTE]
Whether data leaves your machine depends on the model and tools you enable. A local model with local tools can stay local. Cloud models, remote MCP servers, and third-party connectors send the relevant requests to their respective services.

Quick start

Prerequisites

• Git with submodule support
• Node.js and npm
• A current Rust toolchain
• The Tauri 2 system dependencies for your platform
• An accessible OpenAI-compatible model endpoint

The source tree supports Linux, Windows, and macOS. The initial macOS target is Apple Silicon on macOS 14 or later.

Run from source

git clone --recursive https://github.com/Pinvou/pinvou-agent.git
cd pinvou-agent/pinvou3-app
npm ci
npm run dev

If you cloned without submodules:

git submodule update --init --recursive

Connect a local model

Pinvou Agent supports local vLLM and custom OpenAI-compatible APIs. You can manage endpoints, models, and API keys from the application settings.

export DEEPSEEK_BASE_URL="http://127.0.0.1:8000/v1"
export DEEPSEEK_API_KEY="local-no-auth"
export DEEPSEEK_MODEL="your-model-name"

For a non-loopback plain HTTP endpoint in a trusted development network, explicitly set DEEPSEEK_ALLOW_INSECURE_HTTP=1.

Architecture

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 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.

Repository layout

pinvou3-app/          Tauri 2 + React/Vite desktop application
CodeWhale/            Agent engine submodule
pinvou3-app/resources/mcp-servers/
                      Independent local MCP servers
workflows/            Reusable workflows
scripts/              Tests, guards, build, and release helpers
docs/                 Architecture and maintenance documentation

Development checks

Run these commands from the repository root:

(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

See CONTRIBUTING.md for the current contribution workflow and docs/fork-policy.md for CodeWhale maintenance rules.

Community and security

Pinvou Agent is licensed under the MIT License. Please use GitHub Issues for reproducible bugs and feature requests.

Do not report security vulnerabilities in public issues. Follow SECURITY.md or email [email protected].

Pinvou Agent is under active development. The main branch and the latest release notes are the source of truth for current behavior.