Yoji: an AI desktop companion that runs shell commands, keeps a hormone engine, and stays local

The gap Yoji is trying to fill: a chat window that can actually touch your disk

Most desktop AI clients are a text box wired to an API. Yoji's README states the opposite intent in its first line: "Yoji 不止是一个聊天机器人。它能操作你的电脑", and the feature list backs that up with file creation and editing, folder search and organisation, Shell command execution, and Python script runs. The audience is therefore narrower than "anyone who wants an AI assistant". It is for people who already keep a local workspace of files and scripts and want an agent that can act on them without a browser tab and without a cloud round trip for every file read.

The second audience is the tinkerer. Yoji ships a workshop page (工坊) where you define sub-agents with a name, a description, a system prompt and a bound set of MCP tools. That is a configuration surface, not a chat trick, and it tells you the project expects users who will spend an evening wiring tools together rather than users who want a finished appliance.

Architecture: Electron shell, LangChain agent core, SQLite memory, MCP for tools

The README's architecture diagram is the clearest statement of how the pieces fit. Electron plus React plus TypeScript plus Vite form the shell. Inside it, LangChain deepagents handles tool calling, sub-agent scheduling and interrupt approval. @langchain/mcp-adapters performs dynamic tool discovery over MCP. better-sqlite3 and sqlite-vec store chat checkpoints and semantic memory. pdf-parse and mammoth extract text from PDF and DOCX. electron-native-speech wraps macOS SFSpeechRecognizer. pixi-live2d-display renders the avatar.

The repository layout matches that split. src/main holds the agent, the IPC handlers and config.ts, which the README says manages env, model, mcp and childrenAgent settings. src/preload is a contextBridge layer, and src/renderer holds the React pages: home, chat, model settings, MCP management, workshop and file management. A separate models/ directory sits at the top level, which is where Live2D assets would live given the pixi-live2d-display dependency.

Memory is described as three layers, and the distinction matters. The user profile lives in AGENTS.md and loads at startup. Conversation snapshots go to SQLite checkpoints through @langchain/langgraph-checkpoint-sqlite. Long-term summaries plus vector retrieval go to sqlite-vec. Only the first layer is a file you can edit by hand; the other two are opaque binary stores, which is a real constraint if you ever want to inspect or migrate what the agent believes about you.

Installing Yoji and getting a first conversation out of it

The README pins the package manager: pnpm 11, installed globally. The quick start is four commands, and the repository's .npmrc is already configured with a domestic mirror for the Electron and model downloads, so a slow first install is expected to be handled for you.

git clone https://github.com/wangxijie001/yoji.git
cd yoji
pnpm install
pnpm dev

pnpm dev runs electron-vite dev, which is the development entry point in package.json. The README does not describe what the first window shows, only that you configure a model afterwards. Distribution builds are separate scripts:

pnpm build:mac
pnpm build:win
pnpm build:linux

Those map to electron-vite build plus electron-builder for each target. Note that the macOS and Windows builds skip the typecheck step that the generic build script runs, since build:mac and build:linux call electron-vite build directly.

Model configuration happens in the UI, not in a file. The README says to open the 模型 page, enter an API key for DeepSeek or Qwen, pick a model, and save. There is no documented environment variable for the key, and config.ts is the only place the README hints that env settings live. If you prefer keys in a file, you are reading source to find out how.

Adding an MCP server is the same shape: open the MCP page, add a name, a URL and a transport (SSE or HTTP), save, and the app tests the connection. The README also claims you can ask the AI in chat to install a tool for you, with an approval prompt before it acts.

The sub-agent system is the most opinionated part, and the README knows it

Yoji's README makes a direct claim about the alternative: official sub-agents are blocking, and the async versions depend on a cloud server, so the project implemented its own local factory and scheduler. The mechanism is a three-queue event loop (task queue, running queue, result queue) with a concurrency cap of five sub-agents and mutual exclusion per agent. Tasks get a UUID thread, a checkpoint that is cleared on completion, and a result row in SQLite that expires after seven days. Configuration and MCP versions are hashed with MD5 so unchanged setups are reused instead of rebuilt.

Two tools expose this to the main agent: task for synchronous calls and push_async_task for fire-and-forget dispatch. Cancellation has both a UI path and an abort_async_task tool. That is a more complete design than most hobby agent projects bother with, and the per-agent mutual exclusion rule suggests the author hit a real reentrancy problem rather than designing defensively from the start.

The cost is conceptual weight. A new user now has to understand synchronous versus asynchronous agents, MCP tool binding per agent, and the fact that changing the workshop, an MCP server or the model triggers an automatic rebuild. The README states that rebuild behaviour plainly, but it does not say how long a rebuild takes or what happens to queued tasks during one.

Where Yoji breaks: macOS-only voice, two model vendors, and an agent with shell access

The clearest limitation is platform. Voice wake uses macOS SFSpeechRecognizer and the README says Windows is not supported, with the renderer hiding the entry point automatically. TTS is also macOS-only. Linux appears in the build scripts and in the feature table's platform claim, but the README does not describe a Linux voice path, so a Linux user is building a chat and file agent without the two features the project markets hardest.

The model layer is narrower than it looks. The configuration instructions name DeepSeek and Qwen only. The architecture diagram lists @langchain/deepseek and @langchain/openai, and package.json carries @langchain/openai, so an OpenAI-compatible endpoint is plausible, but the README never tells you to point Yoji at one. If your organisation requires a self-hosted model, the documentation gives you nothing to follow.

The risk profile deserves stating plainly. Yoji runs Shell commands, edits files and installs MCP servers, gated by an approval prompt the README calls 智能审批. That is a reasonable default, but the README does not describe a command allowlist, a sandbox, a dry-run mode or an audit log of executed commands. The three-layer memory is also not exportable in a readable form except through the .ecompanion export file, which the README says is authenticated but does not describe the format of. For a personal machine that is fine. For a shared or managed machine, it is an argument for waiting.

Alternatives and how the approach differs

The obvious comparison is a general-purpose desktop agent such as Open Interpreter, which also executes code and shell commands locally. The difference is in where the personality and tool layers sit. Open Interpreter is a code-execution loop with a conversation attached; Yoji is a conversation with a persistent emotion state, a Live2D body, a memory profile in AGENTS.md and a tool layer that is MCP-native rather than Python-package-native. If your task is "run this analysis and show me the chart", the interpreter model is a shorter path. If your task is "keep a companion that remembers my preferences and can call the same MCP servers my other tools use", Yoji's shape is the closer fit.

The second comparison is a plain MCP client such as Claude Desktop. Both speak MCP, but a standard client has no sub-agent scheduler and no local file or shell tooling beyond what a server exposes. Yoji bundles those capabilities and adds the async dispatch layer on top. The trade is that you inherit Yoji's model configuration and its Electron runtime instead of a vendor-maintained client.

Maintenance, licence and what upgrading actually costs

The last push to the repository was on 2026-08-12, and the most recent release is v1.6.1 from the same day, described as 状态图可视化. Before that, v1.6.0 (微信连接) landed on 2026-07-22 and v1.5.0 (Live2D 虚拟形象) on 2026-07-18. Three tagged releases in under a month is a fast cadence, which cuts both ways: features arrive quickly, and so does churn in the areas you might have configured.

The rebuild-on-change behaviour described in the README is the concrete upgrade cost. Because the workshop, MCP configuration and model selection each trigger an agent rebuild with an MD5 version hash, a release that changes how config.ts is parsed or how MCP tools are bound can invalidate your setup. The README does not document a migration path or a config schema version. The .ecompanion export is the only stated portability mechanism, and it is described as covering memory, emotion and configuration, which suggests it is the intended answer to upgrade pain, though the README does not say whether exports survive across major versions.

Licensing is straightforward: MIT, stated in the README and in package.json. That permits commercial use and modification with attribution and no warranty. It says nothing about the licences of the bundled models/ assets, the Live2D runtime, or the third-party MCP servers you connect, and those are the places where an MIT label on the wrapper can mislead. Check the individual components before shipping anything built on Yoji.

Editorial conclusion

Adopt Yoji if you want a local-first Electron agent that can touch your filesystem and shell, you accept DeepSeek or Qwen API keys as the model path, and macOS or Windows is your daily driver. Skip it if you need Linux voice input, a cloud-free model runtime, or an audit trail of what the agent did to your disk; the README documents none of those. Before running pnpm dev, read src/main/config.ts and the electron-builder.yml targets so you know which keys and which platform you are actually building for.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. wangxijie001/yoji on GitHub