Cyrene-Agent: a Windows Live2D desktop companion that also runs an agent loop

What Cyrene-Agent actually is, and who it is for

The README opens with a single sentence that defines the scope: Cyrene-Agent is a Windows Live2D AI desktop companion whose core character is Cyrene from Honkai: Star Rail. Everything else in the repository is arranged around that. The desktop pet layer renders expressions, motions, mood, speech bubbles and stickers; underneath it sits an Electron and TypeScript application that talks to an LLM and can call tools.

The intended user is someone who wants both halves at once. A pure character-chat front end would not need CyreneHarness, the permission policy or the LSP integration. A pure coding agent would not need Live2D, TTS, ASR or the proactive-chat scheduler. Cyrene-Agent bundles them, and the README lists four conversation modes that map to four kinds of user: Chat for roleplay and conversation, Work for general tasks with search, file handling and document generation, Code for repository work with semantic LSP queries and restricted read/write/execute commands, and Learn for studying against an Obsidian vault.

That combination is the project's identity and also its cost. A user who only wants the Code mode is paying for a Live2D renderer and a voice stack. The README does not describe a way to install the harness without the desktop shell, so the modes are not separable in practice. If you are evaluating this for a team, the honest framing is that the agent loop is the serious engineering and the companion layer is the product decision wrapped around it.

Inside CyreneHarness: the while loop, the four outcomes and the halt rule

The README points at src/main/orchestrator/harness/cyrene-harness.ts and describes CyreneHarness as the core agent loop that strings model decisions, tool execution, side-effect bookkeeping and state recovery into one interruptible, resumable, replayable cycle. Work, Code and Learn all run on it.

The mechanism is a continuous while loop plus Function Calling. Each round calls the LLM; if the response carries toolCalls, they are dispatched; if it does not, the model has ended the turn. One rule is stated as non-negotiable: the assistant message returned each round must be pushed into messages unconditionally, because otherwise the next round cannot see what the model just said and the loop collapses immediately. That is a small sentence with large consequences for anyone modifying the loop.

The more interesting design is the four-state tool outcome. Results are classified as success, failure, unknown or not_executed. When a result is unknown and its sideEffect 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. This is a deliberate trade: the agent stops and hands control back rather than guessing whether an action landed. If your workload involves non-idempotent operations, you get safety at the cost of an interrupted turn that something downstream has to resolve.

Scheduling is conservative by default. Tools run serially unless a tool explicitly declares itself concurrency-safe and pure, with a default parallel cap of 4, and results are always committed in the model's original tool-call order. There is a separate Ask path: ask_user and confirm_uncertain_effect are user-wait tools that must own the round, and every other tool in that round is written back with a not_executed protocol result while discardProgressBuffer() throws away progress text. Timeouts use two clocks, so execution time and user waiting time are measured separately and a slow human does not consume the task timeout budget. Each round checkpoints messages, state and rounds through onCheckpoint, which is what makes crash recovery possible.

Termination has four states: success (terminated false), cancelled (terminated true, terminateReason cancelled, finalAnswer empty, no final_answer event), error (LLM throw or checkpoint failure) and timeout (past config.totalTimeoutMs). Context handling adds mid-loop compaction driven by a token budget, two-level truncation where large tool output is stored on disk as ToolOutputRef and the model keeps only a preview, and a read_tool_result built-in to pull the full content back on demand.

Installing Cyrene-Agent from source on Windows

The README is explicit that the prerequisites are Windows 10 or 11 64-bit, Node.js 24 LTS, npm 10 or newer (npm 11 recommended), Rust stable and Visual Studio 2022 Build Tools with the Desktop development with C++ workload, MSVC v143 and the Windows 10/11 SDK. If you install a packaged build from Releases, the README says you do not need Rust or the Build Tools.

Clone the repository and install dependencies with the locked versions:

git clone https://github.com/Playa-0v0/Cyrene-Agent.git
cd Cyrene-Agent
npm ci

The README notes that the first install downloads Electron, Pixi.js and Live2D dependencies, so the time depends on your network. After Rust is installed, it suggests confirming the MSVC toolchain:

rustup default stable-x86_64-pc-windows-msvc

The native screenshot helper is not committed as an .exe, so a fresh clone must build it once before anything else:

npm run build:screenshot-helper
npm run build
npm start

There is also a CLI entry point. Build it and link it, then the cyrene command works from any directory:

npm run build:cli
npm link
cyrene hello
cyrene version

The first bare cyrene run prints a welcome banner and records state in ~/.cyrene/state.json; later runs print only Cyrene Agent <version> and Ready. The README warns that cyrene run is currently development mode and needs a package.json in the current directory, and that a cyrene desktop entry for packaged installs is planned for 1.x. Windows users can alternatively double-click setup.bat for install, build and npm link, then start.bat to launch.

One configuration step remains before the agent is useful. Click the system tray icon, open settings, and in model settings pick an LLM vendor preset and fill in API Key, Base URL and model name. The README calls this necessary for both chatting and running the agent. The optional BGE-M3 embedding model, downloadable from Releases, adds sticker semantic matching, tone enhancement, Worldbook retrieval and RAG; without it those features switch off or degrade automatically, and basic chat is unaffected.

Where Cyrene-Agent breaks down or is the wrong tool

Platform lock-in is the first constraint. The README states that Feishu, WeChat iLink, nut-js keyboard and mouse automation, and the native screenshot feature depend on the Windows environment. The prerequisites list Windows only. There is no macOS or Linux path described, and the Rust screenshot helper is built with the MSVC toolchain. If your team develops on macOS, you are not the target.

The second constraint is the dependency chain on the build machine. Node 24 LTS, Rust stable and Visual Studio 2022 Build Tools are a real setup cost, and the README adds that modifying the Rust screenshot helper code requires re-running npm run build:screenshot-helper. Anyone who expects a single npm install to be enough will be surprised.

The third is memory behavior. The README describes the memory engine as L0/L1/L2 layered, combined with memory avatars, Worldbook and long-term accumulation, and it states plainly that the DMAE algorithm is v4.0 and does not implement the latest v5.1. That is an admission that the shipped memory logic lags the intended design. If your use case depends on precise long-term recall, treat the memory layer as versioned and moving.

Finally, the harness itself has failure modes worth naming. The unknown plus non_idempotent rule halts the round; a workflow that expects the agent to push through a flaky external call will instead stop and wait for resolution. Mid-loop compaction reuses the LLM to summarize history, and the README says a checkpoint failure right after compaction trips a circuit breaker and stops further model requests. Those are safety choices, and they are also places where a run can end earlier than a user expects. If you need a headless agent running unattended on a server, this is the wrong tool: the app is a desktop Electron shell, and the modes are not exposed as a standalone service.

How Cyrene-Agent differs from generic desktop agent shells

The obvious alternative is a general-purpose desktop agent shell that attaches to a chat model and exposes tools, with the character layer left to a separate app. The difference is not the feature list; it is where the identity lives. In a generic shell, the persona is a system prompt you edit, and memory is usually a single conversation store. In Cyrene-Agent, the persona is a product surface: Live2D expressions, motions, mood state, stickers, TTS and ASR, proactive chat triggered by time and user preference, and delivery across desktop, Feishu, WeChat iLink and QQ through NapCat or OneBot 11.

That pushes complexity into places a generic shell does not have. Memory is split into L0/L1/L2 rather than one store, so retrieval has layers to choose from. The Code mode binds a trusted directory and offers LSP semantic queries (definition, references, hover, symbols, diagnostics) with restricted read/write/execute, gated by a permission policy and an execution policy in the harness. A generic shell typically hands the model a shell and trusts the prompt. Cyrene-Agent instead routes side effects through the four-state outcome ledger and the halt rule described above.

The cost of that approach is coupling. Because the harness is described as the base for Work, Code and Learn, and because the desktop shell is the delivery vehicle, you cannot easily take the loop and leave the companion. The README also notes that different model vendors get tiered Structured Output and Function Calling compatibility handling, which implies per-vendor behavior differences inside the loop rather than one uniform path. If you want a minimal, portable loop, this is more machinery than you asked for.

Licence, maintenance and what an upgrade costs you

The repository is MIT licensed, which is permissive and places few obligations on how you use or redistribute the code. That is the whole of what the README supports; questions about bundled assets, the Live2D character or the mpv binary are not addressed there, and no separate asset licence is stated, so treat those as unresolved until you check the repository files yourself.

On maintenance, the last push was on 2026-09-10, and the repository is not archived. Recent releases are v1.2.2 on 2026-09-08, v1.2.1 on 2026-09-06 and v1.1.9 on 2026-08-28. The release cadence in that window is fast, and the README itself flags that the DMAE memory algorithm is at v4.0 while v5.1 is not implemented, and that the packaged cyrene desktop entry is planned for 1.x. Both are signals that interfaces are still moving.

That matters for upgrade cost. The harness persists messages, state and rounds through onCheckpoint, and the README describes a cacheEpoch that advances across compaction and recovery, plus vendor cache hints injected at the request layer. If you run long-lived sessions, an upgrade that changes checkpoint shape or cache epoch semantics can invalidate saved state. The README does not document a migration path for checkpoints, and it does not document rollback. Before upgrading in place, back up the state directory you configured and read the release notes for the specific version, because the README does not promise compatibility across the 1.x line.

Editorial conclusion

Adopt Cyrene-Agent if you want a Windows desktop companion whose agent loop is documented in the source, and you accept Node 24, Rust stable and Visual Studio 2022 Build Tools on the build machine. Do not adopt it if you need macOS or Linux, or if you want a headless agent that runs on a server: the README states the Feishu, WeChat iLink, nut-js and native screenshot paths depend on Windows. Before committing, read src/main/orchestrator/harness/cyrene-harness.ts and confirm that the uncertainEffects halt path matches your tolerance for a paused turn, because that is the design decision the rest of the app inherits.

Frequently asked questions

Official sources

1. License: MIT
2. Playa-0v0/Cyrene-Agent on GitHub
3. Project website
4. README
5. Releases