HanaAgent: a desktop AI agent that ships its own sandbox, memory and personality files

The gap HanaAgent targets is the one between CLI agents and office work

The README states the project's motivation directly: the author wanted to close the distance between most people and AI agents, and to stop strong agent capability from living only inside a terminal. The stated audience is not developers. It is anyone sitting at a computer doing work, with the author noting their own day job is clerical and that many tool and workflow decisions target everyday office scenarios.

That framing explains several product decisions that would look odd in a coding agent. There is a graphical interface throughout. The setup wizard asks for a name and a language before it asks for anything technical. Agents get a desktop metaphor (the README calls it a desk) where files can be dropped and notes written, and the agent reads those notes on its own initiative. There is a full-screen media viewer with wheel zoom and keyboard shortcuts for `+`, `-` and `0`.

If you already use Claude Code, Codex or Manus, the README says you will find something familiar and something new. The familiar part is the tool set: file read and write, one-shot commands and persistent terminal sessions, web browsing, search through a browser backend or API, screenshots including segmented long screenshots, and code execution. The unfamiliar part is that these tools are wrapped in a desktop application with per-agent identity rather than a shell session.

Memory, personality and the desk are all folder-scoped

The README describes a memory system that combines mainstream approaches with its own additions, and then says plainly that it still needs optimization. That is an unusual admission in a project README and worth taking at face value: recent events are remembered firmly, older material is where the caveat applies.

Personality is not a prompt preset. It is a template plus a custom personality file, and each agent has its own way of speaking and its own behavior logic. The README states that separation between agents is done well and that backup is convenient because an agent is a folder. A later feature, character cards, packages an agent as a local-first zip that carries personality, avatar, optional memory and skills according to a whitelist.

The desk is the asynchronous collaboration surface. Each agent has one, files can be placed there, and notes written there are read and acted on by the agent. The README mentions drag and drop, file preview, and a file tree change listener on the workbench. Scheduled tasks and a heartbeat mechanism sit on top: the agent sets Cron jobs and periodically inspects desk files for changes. The automation executor separates when something triggers from what it does, so complex work runs in the background through the agent while lightweight reminders can go straight to a notification.

Multi-agent support follows from the folder model. Multiple agents each hold independent memory, personality and scheduled tasks. They can collaborate through channel group chats or delegate tasks to one another.

The architecture is six layers with a separate server process

The repository layout in the README lists `core/` for engine orchestration and managers including PluginManager, `lib/` for memory, tools, sandbox and Bridge adapters, `server/` for a Hono HTTP and WebSocket service, `hub/` for the scheduler, channel routing and event bus, `desktop/` for the Electron app and React frontend, `shared/` for cross-layer utilities such as the config schema and model references, plus `plugins/`, `skills2set/`, `scripts/` and `tests/`.

The engine layer coordinates several managers (Agent, Session, Model, Preferences, Skill, Channel, BridgeSession, Plugin) behind a single facade. The Hub runs background work independently of the current chat session: heartbeat inspection, automation and scheduled tasks, channel routing, inter-agent communication and DM routing. That separation matters because it means an agent can act while no window is open on that conversation.

The server is a standalone Node.js process, spawned by Electron or started on its own, bundled with Vite and dependency-traced by @vercel/nft. It talks to the Electron renderer over WebSocket. User data lives under a directory chosen by `HANA_HOME`, defaulting to `~/.hanako` in production and `~/.hanako-dev` in development. The Pi SDK runtime that Hana manages sits at `${HANA_HOME}/runtime/pi-sdk/`, and the README notes Hana does not depend on Pi's global agent directory or `PI_CODING_AGENT_DIR`. Leftover `fd` and `rg` binaries from older versions at `${HANA_HOME}/.pi/agent/bin/` are copied to the new directory on first use of the corresponding search tool, with the old files left in place.

Files a user can see inside a session are registered through a `SessionFile` sidecar, so the desktop app, Bridge adapters, the mobile PWA and other remote frontends consume one file identity and adapt to their own capabilities.

Sandbox levels, PathGuard and what each platform actually isolates

The sandbox is the part of the design most worth reading closely, because the README is explicit about where the platforms differ. There are two layers: an application-level PathGuard with four access levels, and an operating-system sandbox using macOS Seatbelt, Linux Bubblewrap or a Windows restricted token.

The default posture described is read-only access to ordinary system files, with writes and deletes confined to the working directory and controlled data directories. You change the level in Settings, under the security page.

Then the caveat. The README states the Windows command sandbox is currently a write-isolation model: reads happen according to the current user's permissions, and network access runs under the current user's network permissions as well. On macOS and Linux, network isolation is whatever the platform sandbox provides. So the guarantee is not uniform across operating systems, and on Windows the read and network sides are effectively as permissive as your normal user account. If your threat model includes an agent reading files it should not, Windows is the weak platform in this set.

External network access is configurable through a system proxy, a manual proxy or a direct connection. On the Bridge side, the README states Hana does not open a public tunnel automatically; a public entry point has to be supplied explicitly by the user.

Plugins have two permission tiers and the split is load-bearing

The plugin architecture is convention-first. Plugins are installed by drag and drop from the community, and a plugin can contribute tools, skills, commands, agent templates, HTTP routes, a Pi SDK extension, an LLM provider, pages, a sidebar widget, a config schema and background tasks.

Routes reach core services directly through a `PluginContext` injection, and plugins can talk to the agent over a Session Bus to fetch history and manage sessions. Plugin cards appear in the unified message block and in history replay.

Permissions come in two levels, restricted and full-access. The README is specific about what the second level gates: `extensions/`, routes, providers, pages and lifecycle capabilities only take effect in full-access plugins. That is a meaningful boundary rather than a label. A restricted plugin can still contribute tools and skills, but it cannot register an HTTP route or an LLM provider. If you are evaluating a third-party plugin, the tier it declares determines how much of your process it can reach.

Skills are a separate axis. The README says the built-in system is compatible with a large community skill ecosystem, and that agents can install community skills from GitHub before doing work, or write and learn new skills themselves. By default there is a strict skill review, and the README notes you can turn it off yourself if skills fail to install. Turning off a review gate to make an install succeed is the kind of trade-off worth making deliberately rather than reflexively.

Getting it running: installers, the wizard and the three model slots

Installation is by release artifact rather than package manager. macOS gets a `.dmg` for Apple Silicon and Intel, and the README states the app is signed with an Apple Developer ID and notarized, so it should open directly. Windows gets an `.exe` installer, and the README warns the installer is not code signed, so SmartScreen may block the first run; the documented workaround is More info then Run anyway. Linux gets `.AppImage` or `.deb`. The platform table marks Windows as Beta, with macOS and Linux as supported and the mobile PWA as v0.

The first-run wizard covers language, your name, and connecting a model provider with an API key and base URL. It then asks you to pick three models: a conversation model for the main dialogue, a small tool model for lightweight tasks, and a large tool model for memory compilation and deep analysis. A fourth slot, the vision model, is chosen separately in settings so a text model can handle image attachments through what the README calls a Vision Bridge. Supported access types include OpenAI-compatible, Anthropic-style, OAuth providers and local Ollama models. OpenAI OAuth login is available; the README states Anthropic OAuth is deliberately not offered because of account-ban risk.

For development the README gives the commands directly: `npm install`, then `npm start` for Electron with a renderer build, `npm run start:vite` for Vite HMR (the renderer dev server must already be running), `npm run server` to start only the server, `npm run cli` for the server-first CLI, `npm test` for Vitest and `npm run typecheck`. The CLI is notable because it connects to the same HanaAgent Server, letting you check status, list sessions and continue a conversation from a terminal.

Bridge adapters, the mobile PWA and the public URL you must supply yourself

One agent can be reachable from Telegram, Feishu, QQ and WeChat bots at the same time, with remote control of the computer from any of those platforms. Bridge messages carry platform context, and notifications can be sent back out to whichever external platform is current.

Media delivery is where the design gets concrete. Staged local files are uploaded directly by each platform adapter where possible: Telegram, Feishu and WeChat use their own upload endpoints, and QQ uses the official bot chunked upload endpoint followed by a rich media message with `msg_type: 7`. The config keys `preferences.bridge.mediaPublicBaseUrl` and `HANA_BRIDGE_PUBLIC_BASE_URL` exist only for platforms that still need a public URL or for remote fallback. That URL acts as the origin for the temporary file route `/api/bridge/media/:token`, and the file itself is protected by a short-lived token, a download count limit and a local path whitelist.

The mobile side is a PWA hosted by the server at `/mobile/`. A phone logs in with a device access key or a local account and can view sessions, continue chatting and manage workbench files. A second desktop can also connect to an existing server through a LAN URL plus access key and consume the same sessions and resources. This is the part of the project that is least like a personal desktop tool and most like a small self-hosted service, and it is the reason the server is a separate process rather than something embedded in the renderer.

Where HanaAgent is the wrong tool, and what it is not competing with

The README's own admissions are the best starting point. Memory is described as strong for recent events and still in need of optimization. Windows is Beta, and the Windows sandbox is write-isolation only, with reads and network following the user's normal permissions. The Windows installer is unsigned. The repository and release URLs still point at the old `openhanako` name during a migration, so links and any tooling keyed to the current name will need attention.

The structural limitation is different. HanaAgent is an Electron application with a graphical setup wizard, a desk, a media viewer and a PWA. If your workflow is a shell script that pipes a repository into an agent and captures stdout, this is the wrong shape. The server-first CLI exists and connects to the same server, but the documented commands are for status, listing sessions and continuing a conversation, not for scripting arbitrary agent runs. A terminal coding agent such as Claude Code or Codex, both named in the README as points of comparison, keeps the agent inside your existing shell, your existing diff tooling and your existing CI. HanaAgent instead asks you to adopt a desktop app and a data directory at `~/.hanako`, and it manages its own Pi SDK runtime under `${HANA_HOME}/runtime/pi-sdk/` rather than using Pi's global agent directory.

The honest comparison is not which is more capable at editing files. Both read, write, run commands and search. The difference is where identity and state live. A CLI agent typically carries configuration in project or home dotfiles and treats each invocation as roughly stateless. HanaAgent makes the agent itself a folder with memory, personality, a desk and a schedule, and lets several such folders exist side by side and message each other through channels. If you want one agent you invoke and forget, the folder model is overhead. If you want several persistent assistants with distinct behavior, the folder model is the feature.

Licence, upgrade surface and what to check before committing

The project is Apache-2.0, which permits commercial use, modification and redistribution provided you keep the licence and notices and state significant changes. It also includes an express patent grant. This is a description of the licence text, not legal advice; if you plan to redistribute a modified build or bundle it into a product, have counsel read the NOTICE and attribution requirements rather than relying on this paragraph.

The upgrade surface is larger than a single binary. Releases arrive frequently, with v0.450.0 and v0.449.0 both dated within a day of each other and a parallel `train-beta-32` tag alongside them, so pinning to a specific tag matters more than following the latest. The technology stack is Electron 42, React 19, Zustand 5, Vite 7, Hono and better-sqlite3 in WAL mode, which means a Node ABI change can force a native rebuild of better-sqlite3. The Pi SDK runtime is managed inside `${HANA_HOME}/runtime/pi-sdk/`, so that path is part of your upgrade and backup story. If you rely on plugins, check their declared permission tier after each upgrade, because a plugin that needs a route or provider must be full-access to function. If you rely on Bridge media, the `preferences.bridge.mediaPublicBaseUrl` setting and the `/api/bridge/media/:token` route are the parts most likely to need re-verification when adapters change.

Editorial conclusion

Adopt HanaAgent if you want a packaged desktop agent where each agent is a folder holding its own memory and personality, and you accept the Windows sandbox being a write-isolation model rather than full network isolation. Do not adopt it if you need a headless, scriptable agent or if you cannot tolerate a project whose README states its memory system still needs optimization. Verify three things first: whether your provider supports the OpenAI-compatible or Anthropic-style endpoints the setup wizard asks for, whether your target OS sandbox backend (Seatbelt, Bubblewrap or the restricted token) covers the operations you intend to permit, and whether the plugin you want is restricted or full-access, since routes, providers and pages only load for full-access plugins.

Official sources

1. Issues
2. License: Apache-2.0
3. liliMozi/openhanako on GitHub
4. README
5. Releases