# HanaAgent: A Memory-Bearing Desktop AI Agent You Run Yourself

> HanaAgent is an Electron desktop agent with persistent memory, editable personalities, and OS-level sandboxing, shipped as signed installers rather than a terminal tool. It is approachable, but the memory system is self-described as unfinished and the plugin surface assumes you will read the docs.

**liliMozi/openhanako** — A personal AI agent with memory, personality, and autonomy.

- Repository: https://github.com/liliMozi/openhanako
- Stars: 6,666 · Forks: 576
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/lilimozi-openhanako

## The gap HanaAgent is trying to close

Most agent tooling assumes you live in a terminal. Claude Code and Codex are CLI-first; Manus is hosted. HanaAgent takes the opposite position. The README states the author's intent directly: to bridge the distance between ordinary computer users and agent capabilities, so that agent power is not confined to the command line. The target reader is someone who works at a desk, not necessarily a programmer. The README says the author's own day job is clerical work, and that a large share of the tooling and workflow decisions were made for everyday office scenarios.

That framing explains several choices that would look odd in a developer tool. There is a full graphical interface. There are personality templates and per-agent personality files. There is a concept called a desk, where each agent keeps files and can leave notes that the agent reads on its own. Agents can be reached over Telegram, Feishu, QQ and WeChat bots. The unit of configuration is a folder, and the README notes that agent separation is clean and backup is convenient because an agent is just a folder.

The trade-off is real. A GUI-first agent is harder to put in CI, harder to script, and harder to run on a headless box. HanaAgent does ship a server-first CLI, but the README presents it as a way to check status, list sessions and continue a conversation, not as the primary interface.

## How the engine, hub and server split the work

The repository layout in the README is the clearest description of the architecture. There is a core engine layer that orchestrates multiple managers (Agent, Session, Model, Preferences, Skill, Channel, BridgeSession, Plugin) behind a single facade. A separate hub handles background work: heartbeat inspection, scheduled and automated tasks, channel routing, inter-agent communication and DM routing. The hub runs independently of whatever chat session is open, which is what allows an agent to act while you are not looking at it.

Above that sits a Hono HTTP and WebSocket server. The README is explicit that this runs as a separate Node.js process, spawned by Electron or started on its own, bundled with Vite and with dependencies traced by @vercel/nft. The Electron renderer talks to it over WebSocket. That split is why the mobile PWA and a second desktop machine can attach to the same server over a LAN URL plus an access key and consume the same sessions and files.

User data lives under a directory chosen by the HANA_HOME environment variable. The README gives the production default as ~/.hanako and the development default as ~/.hanako-dev. Runtime resources for the Pi SDK live under ${HANA_HOME}/runtime/pi-sdk/. The README also notes that HanaAgent does not depend on Pi's global agent directory or on PI_CODING_AGENT_DIR, which matters if you already have Pi installed for something else and do not want the two to interfere.

## Installing HanaAgent from Releases and finishing the wizard

HanaAgent is distributed as prebuilt installers, not as an npm global. The README points to the GitHub Releases page for every platform. On macOS you download the latest .dmg; the README states the app is signed with an Apple Developer ID and notarized, so it should open directly. On Linux you take the latest .AppImage or .deb. On Windows you take the latest .exe, and the README warns that the installer is not code signed, so SmartScreen may block the first run and you click through More info then Run anyway. Windows is listed as Beta in the platform table.

The first launch runs a setup wizard. According to the README it asks for your language, your name, a model provider (API key plus base URL), and then three model roles: a conversation model for the main chat, a small tool model for lightweight tasks, and a large tool model used for memory compilation and deeper analysis. A separate vision model can be selected in Settings so that a text model handles image attachments through what the README calls a Vision Bridge. Supported access styles include OpenAI-compatible, Anthropic-style, OAuth providers, and local models through Ollama. The README also mentions OpenAI OAuth login has been added, and says Anthropic OAuth is deliberately not offered because of account-ban risk.

If you build from source instead, the README gives these commands. Note the engines field in package.json, which requires Node 24.12.0 or newer and below 25.

```bash
npm install
npm start
npm run server
npm run cli
npm test
npm run typecheck
```

Running npm start builds the preload, renderer, splash and theme bundles and then launches Electron; npm run server starts only the Hono server process, and npm run cli opens the server-first CLI. npm test runs the Vitest suite and npm run typecheck runs tsc across the main, node and test configurations.

## Sandboxing, file access and the Windows caveat

This is the part worth reading closely before you hand an agent your machine. The README describes two layers of isolation. At the application layer, a component called PathGuard enforces four levels of access control. At the operating system layer, HanaAgent uses Seatbelt on macOS, Bubblewrap on Linux, and a restricted token on Windows. In normal operation the agent can read ordinary system files but writes and deletes are confined to the working directory and a controlled data directory. The sandbox level is adjustable in Settings under a security page.

The Windows model is weaker and the README says so plainly. Windows command sandboxing is a write-isolation model: reads happen according to the current user's permissions, and network access runs under the current user's network permissions. On macOS and Linux, network isolation is left to the platform sandbox's own capability. If you are on Windows and expecting the same containment you would get from Seatbelt, that expectation is not supported by the documentation.

External network access is configurable through a system proxy, a manual proxy, or a direct connection. There is one point in the README that deserves emphasis: HanaAgent does not automatically open a public tunnel. The public entry point must be supplied explicitly by the user. The bridge media base URL, set through preferences.bridge.mediaPublicBaseUrl or the HANA_BRIDGE_PUBLIC_BASE_URL environment variable, is only used for platforms that still need a public URL or as a remote fallback, and it acts as the origin for a temporary file route at /api/bridge/media/:token. That route is protected by a short-lived token, a download count limit, and a local path allowlist. The design is conservative, but it means remote media delivery is your responsibility to configure.

## Memory, personality and skills: what is actually shipped

Memory is the headline feature and also the softest one. The README says the memory system combines mainstream approaches with some original ideas, and that recent events are remembered very firmly. It then adds, in the same sentence, that the system genuinely still needs optimization. That is an unusually candid line for a project README, and it should shape your expectations. If your use case depends on precise recall of things said months ago, this is the area to test yourself before committing.

Personality is more concrete. Agents are shaped by personality templates and custom personality files, and the README claims strong separation between agents with convenient backup because an agent is a folder. Role cards and skill bundles extend this: an agent can be exported as a local-first role card zip that carries personality, avatar, optionally memory, and skills, filtered by an allowlist. Skill Bundle is separate infrastructure for grouping skills on a management page, reordering them by drag, enabling them as a group, and exporting them individually as zips.

Skills themselves come with a caveat. HanaAgent is compatible with the wider SKILLS community ecosystem, and the README says an agent may install community skills from GitHub before starting work, or write and learn new skills itself. By default there is a strict skill review step. The README notes that if a skill fails to install you can turn that review off yourself. Turning off a safety check to make an install succeed is a decision, not a fix, and the README does not describe what the review actually inspects.

## Multi-agent, bridges and the plugin permission model

You can create several agents, each with its own memory, personality and scheduled tasks. They coordinate through channel group chats and can delegate tasks to one another. Each agent also has a desk, a space where files can be placed and notes written, with drag and drop, file preview, and a watcher that detects changes in the workbench file tree. That watcher is what feeds the heartbeat inspection the hub runs.

Scheduled tasks use Cron, and the README describes a deliberate separation between when something triggers and what it does. Complex tasks still run in the background through the agent, lightweight reminders can be sent as notifications directly, and plugin actions can be invoked on a schedule. That split is a sensible design: not every timer needs a full model round trip.

The plugin system is where the complexity concentrates. Plugins are installed by drag and drop and can contribute tools, skills, commands, agent templates, HTTP routes, Pi SDK extensions, LLM providers, pages, sidebar widgets, configuration schemas and background tasks. Routes can reach core services directly through an injected PluginContext, and can talk to agents over a Session Bus to fetch history or manage sessions. Plugin cards appear in the message stream and in history replay. There are two permission tiers, restricted and full-access, and the README states that extensions/, routes, providers, pages and lifecycle capabilities only take effect in full-access plugins. A plugin that needs a route is a full-access plugin, and that is a meaningful amount of trust to place in a zip you dragged in.

## Where HanaAgent is the wrong choice

If you need an agent embedded in a build pipeline, HanaAgent is the wrong shape. The primary interface is an Electron app, the server is a separate Node process that the app spawns, and the README's CLI is scoped to status, session listing and continuing a conversation. There is a bin entry named hana pointing at cli/entry.ts, but the README does not present it as a general automation surface.

If you are on Windows and need signed software, the README says the installer is not code signed and Windows is Beta. If you need network isolation on Windows, the README describes a write-isolation model only, with reads and network governed by your existing user permissions.

If you want a hosted agent with no local footprint, this is the opposite: it runs on your machine, keeps data under HANA_HOME, and asks you to supply your own model provider credentials. And if you are looking for a finished memory system, the README's own wording says the memory work is ongoing. The honest comparison here is with a CLI coding agent such as Claude Code or Codex. Those give you a terminal-native workflow, composable shell integration and no GUI to maintain. HanaAgent gives you a graphical interface, per-agent personality and memory folders, a desk for asynchronous collaboration, and chat bridges to Telegram, Feishu, QQ and WeChat. The difference is not quality, it is where the agent lives and who is expected to operate it.

## Licence, maintenance and the cost of upgrading

HanaAgent is licensed under Apache-2.0, which permits commercial use, modification and redistribution provided you keep the licence and notices intact and state significant changes. Apache-2.0 also includes an express patent grant, which matters if you plan to build on the plugin surface. This is a general description of the licence text, not legal advice; read LICENSE in the repository if the distinction matters to your organisation.

The repository is not archived, and the last push was on 2026-08-27. Releases are frequent and version numbers move quickly: v0.450.0 on 2026-08-22, the same day as a train-beta-32 tag, and v0.449.0 the day before. That cadence is a maintenance cost as much as a signal. A project that ships point releases this often will change behaviour between them, and the README already notes that repository and release URLs still point at the old openhanako name during a migration, with a rename to be performed separately. If you pin a version, expect to re-read the release notes before moving.

There is a second upgrade cost specific to this project: user data lives under HANA_HOME, and the README documents a migration detail for legacy runtime files. Older versions left fd and rg binaries in ${HANA_HOME}/.pi/agent/bin/, and the README says those are copied to the new runtime directory only on first use of the corresponding search tool, with the old files left in place untouched. That is a tidy migration, but it also means stale binaries can sit in your data directory indefinitely unless you remove them.

## Conclusion

Adopt HanaAgent if you want a GUI-first personal agent with per-agent memory and personality folders, and you are willing to accept that the memory system is described in the README as still needing optimization. Skip it if you need a headless, scriptable agent on a server, or if you require a code-signed Windows installer today. Verify three things first: that your Node version satisfies the engines field if you build from source, that your model provider speaks one of the supported API styles, and that the sandbox level shown in Settings matches what you expect before you let an agent write files.

## FAQ

### Can HanaAgent give me an example of an autonomous agent?

The README describes agents that set Cron scheduled tasks, periodically inspect files on their desk for changes, install community skills from GitHub before starting work, and write and learn new skills themselves. The hub runs these background tasks independently of the open chat session.

### What is an AI autonomous agent in the context of HanaAgent?

In this project it is an agent with its own memory, personality and scheduled tasks that can act without a prompt, including delegating work to other agents through channel group chats. The separation between trigger and action means lightweight reminders can be sent as notifications while complex tasks run through the agent in the background.

### How do I install HanaAgent on macOS, Windows or Linux?

Download the installer for your platform from the GitHub Releases page: a .dmg for macOS, an .exe for Windows, or an .AppImage or .deb for Linux. The macOS build is signed and notarized, while the README notes the Windows installer is not code signed, so SmartScreen may require you to click through More info and Run anyway.

### Which model providers does HanaAgent support?

The setup wizard asks for an API key and base URL, and the README lists OpenAI-compatible, Anthropic-style, OAuth provider and Ollama local model access. It also notes OpenAI OAuth login is available, while Anthropic OAuth is deliberately not offered because of account-ban risk.

### Where does HanaAgent store my data?

The README states the user data directory is determined by the HANA_HOME environment variable, defaulting to ~/.hanako in production and ~/.hanako-dev in development. Pi SDK runtime resources live under ${HANA_HOME}/runtime/pi-sdk/.

## Sources

- [Issues](https://github.com/liliMozi/openhanako/issues)
- [License: Apache-2.0](https://github.com/liliMozi/openhanako/blob/main/LICENSE)
- [liliMozi/openhanako on GitHub](https://github.com/liliMozi/openhanako)
- [README](https://github.com/liliMozi/openhanako/blob/main/README.md)
- [Releases](https://github.com/liliMozi/openhanako/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/lilimozi-openhanako