Cyrene-Agent: a Windows Live2D companion whose agent loop is the real product
An open-source desktop AI agent built around Cyrene’s persona and powered by the self-developed Cyrene_Harness framework. It combines immersive character chat with practical Agent capabilities for daily tasks, coding assistance, learning, and tools like music and weather.
At a glance
- What is it?
- Cyrene-Agent pairs a Honkai: Star Rail character persona with a self-built agent runtime called CyreneHarness. The persona is the packaging; the harness is the part worth reading.
- Who is it for?
- Adopt Cyrene-Agent if you are on Windows 10 or 11, you want a desktop agent with a persistent character layer, and you are willing to read src/main/orchestrator/harness/cyrene-harness.ts before trusting it with file writes.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 5 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 10, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem is not chat, it is tool calls that survive a crash
Most desktop character apps stop at conversation. Cyrene-Agent is aimed at people who want the companion layer and the work layer in one window. The README splits this into four modes: Chat for character conversation, Work for general tasks with web search, file handling, document generation and life services, Code for LSP queries (definitions, references, hover, symbols, diagnostics) plus restricted read, write and edit command execution, and Learn for working against an Obsidian vault. The audience is Windows users who already run an LLM key and want a persistent desktop presence rather than a browser tab. The stated target is Windows 10 or 11 64-bit, and the README notes that Feishu, WeChat iLink, nut-js keyboard and mouse automation and the native screenshot helper all depend on Windows. That is not a soft preference. It is the shape of the project.
CyreneHarness: a while loop with an accounting ledger
The engine lives at src/main/orchestrator/harness/cyrene-harness.ts and the README describes it as the core agent loop that strings model decisions, tool execution, side-effect accounting and state recovery into one interruptible, resumable, replayable cycle. The mechanism is a continuous while loop over function calling. Each round calls the LLM, dispatches on the returned toolCalls, and when no toolCalls come back the model has ended the turn. One rule is stated bluntly: the assistant message must be pushed into messages unconditionally every round, or the next round cannot see its own previous reply and the loop breaks immediately.
Two design choices carry most of the weight. The first is the four-state outcome. Tool results are classified as success, failure, unknown or not_executed. When a result is unknown and the side effect is non_idempotent, the effect is recorded in state.uncertainEffects and halted is set to true, which pauses further calls of the same kind for the rest of the round. The stated purpose is to prevent automatic replay of a dangerous side effect. The second is the Ask mutual-exclusion path: ask_user and confirm_uncertain_effect are user-wait tools that must own the round, so every other tool in that round is written back with a not_executed protocol result and the progress buffer is discarded. Parallel scheduling is conservative by default, serial unless a tool explicitly declares itself a concurrency-safe pure read, capped at four, and results are always committed in the model's original tool-call order. On halt, error or cancel, already-executed results are not thrown away; the failing slot is closed with a synthetic failure result so the transcript stays well-formed.
Termination, timeouts and the two clocks
The harness has four terminal states. Success means terminated is false and terminateReason is undefined, reached when the model stops calling tools. Cancelled means terminated is true with reason cancelled, triggered by an AbortSignal, and in that case finalAnswer is empty and no final_answer event is emitted. Error means the LLM threw or a checkpoint failed. Timeout means config.totalTimeoutMs was exceeded.
The two-clock design is the detail that separates this from a naive wrapper. Execution time and user-wait time are counted separately, so while ask_user is waiting on a human, the execution clock is paused and the user can think for as long as they like without consuming the task timeout budget. Around that, nearly every await is wrapped in raceWithSignal, and an aborted signal returns cancelled() rather than a partial answer. Each round persists messages, state and rounds through onCheckpoint, which is what makes cross-process crash recovery possible. Context handling is also explicit: a mid-loop compaction step checks the token budget at the start of each round, reuses the LLM to summarize history when over threshold while keeping todos and settled results, and if the checkpoint after compaction fails the harness fuses immediately instead of issuing another model request. Tool output is truncated in two tiers, with large output stored on disk as a ToolOutputRef and only a preview kept in the model message; the model reads the full content back on demand through a built-in read_tool_result. When a response hits the model's length limit (finishReason = length), the README says a notice is appended to the reply rather than truncating silently.
Getting it running on Windows
The prerequisites are Node.js 24 LTS, npm 10 or higher (npm 11 recommended), Rust stable and Visual Studio 2022 Build Tools with Desktop development with C++, MSVC v143 and the Windows 10 or 11 SDK selected. After installing Rust, the README suggests confirming the MSVC toolchain with rustup default stable-x86_64-pc-windows-msvc. If you install the packaged release instead of building, Rust and the build tools are not needed.
From source, the sequence is git clone https://github.com/Playa-0v0/Cyrene-Agent.git, cd Cyrene-Agent, then npm ci (npm install also works). The native screenshot helper is not committed as an .exe, so a first clone requires npm run build:screenshot-helper before npm run build and npm start. Development mode is npm run dev after the screenshot helper build, and any change to the Rust helper code requires rerunning npm run build:screenshot-helper. A distributable Windows build is npm run package:win:dir, which the README says builds both the Electron app and the Rust helper. Windows users can instead double-click setup.bat at the repository root to install, build and link, then start.bat to launch.
The CLI entry is separate. npm run build:cli followed by npm link gives you a cyrene command available anywhere: cyrene for the welcome banner on first run and a short status afterward, cyrene hello to see the full banner again, cyrene about, cyrene version, cyrene --help and cyrene run. First-run state is recorded in ~/.cyrene/state.json. The README is explicit that npm run build already includes npm run build:cli, but npm link must still be run separately, and that cyrene run is currently development mode requiring package.json in the current directory, with a cyrene desktop entry promised for 1.x. API keys are configured after launch by clicking the system tray icon and opening settings: pick an LLM vendor preset and fill in API Key, Base URL and model name. TTS is optional and lists Mossland, MiniMax, MiMo, GPT-SoVITS or a custom cloud voice.
Memory, embeddings and the DMAE version gap
Memory is layered L0, L1 and L2, combined with what the README calls a self-built memory avatar plus Worldbook, to accumulate long-term interaction. The README also describes an entry lifecycle managed by a DMAE algorithm, and here the documentation is candid in a way that deserves attention: it states that DMAE v4.0 has not implemented the latest v5.1. That is a version gap in the project's own description, and it means anyone reading the feature list should treat the memory lifecycle as under active revision rather than settled.
BGE-M3 is recommended but optional. Without it, the README says basic chat still works and the embedding-dependent features (sticker semantic matching, scene tone enhancement, Worldbook semantic retrieval and RAG) either turn off or degrade automatically. The model is distributed through the project's Releases page rather than pulled by a package manager, which is worth knowing before you script an install. Music is a second optional component: NeteaseOpenapiProvider pulls search results, recommendations, playlists and favorites through the NetEase Cloud Music OpenAPI and needs credentials configured in settings, while MpvController spawns the mpv binary bundled at resources/bin/mpv/mpv.exe and talks to it over a named pipe on Windows or a Unix socket, sending JSON IPC commands. The README notes this does not require the NetEase desktop client or the orpheus:// protocol registration. If mpv is missing, the music tool returns client_unavailable and the UI shows a notice without affecting anything else.
Where the design constrains you
The Windows dependency is the first hard boundary. Every platform integration named in the README (Feishu, WeChat iLink, nut-js automation, the native screenshot helper) is Windows-bound, and the advertised precondition is Windows 10 or 11 64-bit. There is no Linux or macOS path described.
The second constraint is the provider surface. The README says the project offers tiered Structured Output and Function Calling compatibility schemes for different vendors, and that the harness degrades to non-streaming only when there is zero increment and the provider explicitly does not support stream plus tools, never replaying a half-finished stream. That is a sensible policy, but it also means the quality of your experience tracks how well your chosen provider implements tool calling. A provider that returns malformed toolCalls or no toolCalls at all will look like a model that has decided to end the turn. The harness cannot distinguish those cases for you.
The third is the trust boundary itself. Code mode binds a trusted code directory and offers LSP queries plus restricted read, write and edit command execution, with the README stating that safety is enforced by the Harness permission approval (Permission Policy) and Execution Policy. The uncertainEffects mechanism stops automatic replay of non-idempotent side effects, which is a real safeguard, but it is a safeguard against replay, not against a first mistaken write. If you point Code mode at a directory you care about, the policy layer is the only thing standing between the model and that directory. That is a normal arrangement for an agent, and it is worth being deliberate about.
Finally, the CLI is not yet a headless agent entry. The README calls cyrene run a development-mode command that needs package.json in the current directory, and defers cyrene desktop to 1.x. There is no described way to drive the harness from a script or a CI job.
Alternatives and where the approach actually differs
If you want a desktop assistant without the character layer, the obvious comparison class is a general-purpose desktop agent that exposes a tool loop and a permission prompt. The difference here is not the tool list, which is ordinary (web search, file handling, document generation, life services, music, MCP extensions). The difference is the accounting model. CyreneHarness treats a tool result as one of four states rather than a pass or fail, and it treats an unknown result with a non-idempotent side effect as a reason to halt rather than retry. Most agent loops retry on error and move on. This one records the uncertainty and stops the class of call.
Against a chat-only companion app, the difference runs the other way. Cyrene-Agent is not a chat wrapper with a Live2D skin; Work, Code and Learn all run on the harness, and the README says the harness is what schedules tool chaining for those modes. If you only want character conversation, you are paying for a runtime you will not exercise. If you want tool-calling with an audit trail of what might have happened, the four-state outcome and the checkpoint-per-round design are the features to compare against whatever you are using now. And if you want a single-user local assistant with no vendor account, note that Cyrene still requires an LLM API key, Base URL and model name before it will chat.
Licence, maintenance and what to check before committing
The project is MIT licensed, which permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive licence and it does not impose copyleft obligations on your own code. It also means the maintainers offer no warranty, and nothing in the licence obliges them to fix anything. This is not legal advice; read the LICENSE file in the repository for the actual terms.
On maintenance, the release history supplied shows v1.1.9 on 2026-08-28, v1.2.1 on 2026-09-06 and v1.2.2 on 2026-09-08, with the last push to master on 2026-09-10. Three releases in roughly two weeks is a fast cadence, and the README's own note that DMAE v4.0 has not implemented v5.1 suggests parts of the system are still moving. Fast cadence cuts both ways: fixes arrive quickly, and configuration or internal APIs can shift between minor versions. The npm SDK and development guide for the plugin system are the surface most exposed to that.
The upgrade cost is uneven. If you install packaged releases, upgrades are a download. If you build from source, you carry Node 24, npm 10+, Rust stable and Visual Studio 2022 Build Tools, and you rerun npm run build:screenshot-helper whenever the Rust helper changes. The plugin system, the MCP extension path and any local patches you make to the harness are the things to re-check on each version bump, because those are the parts that touch the loop's internals rather than its configuration.
Editorial conclusion
Adopt Cyrene-Agent if you are on Windows 10 or 11, you want a desktop agent with a persistent character layer, and you are willing to read src/main/orchestrator/harness/cyrene-harness.ts before trusting it with file writes. Do not adopt it if you need Linux or macOS, or if you want a headless agent you can drive from CI, because the README describes a Windows-first desktop application and the packaged releases are the intended path for anyone who does not want a Rust toolchain. Verify three things first: that your model provider supports function calling and the Structured Output tier the harness expects, that your BGE-M3 install is in place if you want Worldbook semantic retrieval and RAG, and that you are comfortable with the permission approval and execution policy gates being the only barrier between the model and your code directories.
Community notes