openhanako

Purpose

HanaAgent (repository name openhanako) is a personal AI assistant positioned as a "private AI assistant with memory and a soul." The project's original intent is to bridge the gap between ordinary users and AI Agents, so that powerful Agent capabilities are no longer limited to the command line and not only aimed at coders, but designed for everyone sitting in front of a computer working.

Main Capabilities

• Memory: It combines mainstream memory solutions and, with its own initiative, built a memory system. Recent events are remembered very firmly, but it genuinely still needs optimization.
• Personality: It is not a cookie-cutter "AI assistant." Through personality templates and custom personality files, it shapes a unique character. Each Agent has its own way of speaking and behavioral logic, and separation between Agents is done very well. Backup is convenient; an Agent is just a folder.
• Tools: Read and write files, execute one-off commands or persistent terminal sessions, browse web pages, search the internet through a browser backend or API, take screenshots, take segmented long screenshots, preview media, and inspect web pages. Its capabilities cover the vast majority of everyday office scenarios. It can also connect to the same HanaAgent Server through a server-first CLI to check status, list sessions, and continue conversations in the terminal.
• SKILLS support: It has built-in compatibility with the SKILLS community ecosystem and has made proactive optimizations: sometimes before doing work, the Agent will install community skills from GitHub, and the Agent can also write and learn new skills itself. By default, there is fairly strict review of SKILLS; if you find that SKILLS cannot be installed, you can turn it off yourself.
• Character cards and skill packs: Agents can be imported/exported as local-first character card zips, carrying personality, avatar, optional memory, and Skills according to a whitelist. Skill Bundle is an independent skill package infrastructure that can be grouped, dragged, enabled as a group on the skill management page, and separately exported as a zip for easy migration and sharing.
• Multiple Agents: Create multiple Agents, each with independent memory, personality, and scheduled tasks. Agents can collaborate through channel group chats and can also delegate tasks to each other.
• Desk: Each Agent has its own desk, where files can be placed and notes can be written (similar to sticky notes, which the Agent will proactively read and execute). It supports drag-and-drop operations, file previews, and workbench file tree change monitoring, serving as a bridge between the user and the Agent.asynchronous collaboration space.
• Full-screen media viewer: Any image, SVG, or video in a chat or on the desktop opens into a full-screen preview with a dark overlay: scroll-wheel zoom, drag to pan, + / − / 0 keyboard shortcuts, and left/right arrows to switch between adjacent media in the same conversation or the same directory.
• Session management: The sidebar supports searching chat history, prioritizing title matches and continuing to search the body text when necessary; old sessions can be archived and then restored from the settings entry point or permanently deleted. Selected text in the chat body enters a quote card in the input box, preserving the original context for follow-up questions.
• Scheduled tasks and heartbeat: The Agent can set scheduled tasks (Cron) and also periodically inspects file changes on the desktop. The current automation executor has already separated "when to trigger" from "what to do": complex tasks are still executed by the Agent in the background, lightweight reminders can directly send notifications, and plugin actions can also be invoked on a schedule.
• Security sandbox: Two-layer isolation: application-layer PathGuard four-level access control + operating-system-level sandbox (macOS Seatbelt / Linux Bubblewrap / Windows restricted token). The Agent's permissions are under the user's control. Normally it can have read-only access to ordinary system files, while writes and deletions are restricted to the working directory and controlled data directories. The Windows command sandbox is currently a write-isolation model: reads occur naturally according to the current user's permissions, and the network also runs according to the current user's network permissions; network isolation on macOS / Linux is still determined by the corresponding platform's sandbox capabilities. To adjust permissions, you can change the sandbox level on the Settings → Security page; for external networks, you can also configure a system proxy, a manual proxy, or a direct connection.
• Plugin system: A convention-first extensible plugin architecture. Drag and drop to install community plugins; plugins can contribute tools, skills, commands, Agent templates, HTTP routes, Pi SDK extensions, LLM Providers, pages, sidebar Widgets, configuration schemas, and background tasks. Routes can directly access core services (injected via PluginContext), converse with the Agent through the Session Bus, retrieve history, and manage sessions; plugin cards enter the unified message blocks and history replay. A two-level permission model (restricted / full-access) ensures security, extensions/, routes, providers, pages, and lifecycleCapabilities only take effect in the full-access plugin.
• Multi-platform access: The same Agent can simultaneously connect to Telegram, Feishu, QQ, and WeChat bots. You can talk to it on any platform and operate your computer remotely; Bridge messages carry platform context, and notifications can also be sent back to the current external platform.
• Mobile and LAN frontends: HanaAgent Server can host the /mobile/ PWA. A phone can log in via a device access key or local account to view sessions, continue chatting, and manage workspace files. Another desktop can also connect to an existing HanaAgent Server via a LAN URL + access key and continue consuming the same set of sessions and resources.
• Internationalization: The interface supports 5 languages: Chinese, English, Japanese, Korean, and Traditional Chinese.

Installation and Usage

• macOS (Apple Silicon / Intel): Download the latest .dmg from Releases. The app has been signed and notarized with an Apple Developer ID, so macOS should be able to open it directly.
• Windows: Download the latest .exe installer from Releases. The installer has not yet been code-signed. On first run, Windows Defender SmartScreen may block it. Click More info → Run anyway. This is normal for an unsigned version.
• Linux: Download the latest .AppImage or .deb from Releases.
• First launch: The onboarding wizard will guide you through configuration: choose a language, enter your name, connect a model provider (API key + base URL), and choose three models: chat model (main conversation), small tool model (lightweight tasks), and large tool model (memory compilation and deep analysis). The settings page also allows separately selecting a vision model, so that a text model can handle image attachments through Vision Bridge. HanaAgent supports multiple types of access, including OpenAI-compatible, Anthropic-style, OAuth Provider, and local Ollama models. OpenAI OAuth login has also currently been added; given the risk of account bans with Anthropic, it is not provided for now.

Architecture Overview

The engine layer coordinates multiple Managers (Agent, Session, Model, Preferences, Skill, Channel, BridgeSession, Plugin, etc.), exposed through a unified facade. The Hub is responsible for background tasks (heartbeat checks, automation/scheduled tasks, channel routing, inter-Agent communication, DM routing), running independently of the current chat session.

User-visible files within a Session are uniformly registered through the SessionFile sidecar. The desktop, Bridge, Mobile PWA, and other remote frontends consume the same file identity according to their respective capabilities. Each Bridge adapter explicitly declares its own media types, delivery methods, and size limits; for plugin file contribution rules, see PLUGINS.md .

Locally staged files are preferentially uploaded directly by each platform adapter: Telegram / Feishu / WeChat use their respective upload interfaces, and QQ uses the official Bot chunked upload interface, then sends a msg_type: 7 rich media message. preferences.bridge.mediaPublicBaseUrl / HANA_BRIDGE_PUBLIC_BASE_URL are only used for platforms that still require a public URL or for remote fallback; this URL serves as the origin for the temporary file route /api/bridge/media/:token. The file itself is still protected by a short-term token, download count, and local path whitelist. Hana will not automatically open a public tunnel; the public entry point must be explicitly provided by the user.

The Server runs as an independent Node.js process (spawned by Electron or started independently), bundled through Vite, with dependencies traced by @vercel/nft. It communicates with the Electron renderer process through WebSocket. The user data directory is determined by HANA_HOME (production default ~/.hanako , development default ~/.hanako-dev ). Hana-managed Pi SDK runtime resources are located at ${HANA_HOME}/runtime/pi-sdk/ ; Hana does not depend on Pi's global agent directory or PI_CODING_AGENT_DIR . Legacy versions left in ${The fd / rg in HANA_HOME}/.pi/agent/bin/ will only be copied to the new directory the first time the corresponding search tool is used; old files will be kept as-is.

Applicable Scenarios and Limitations

It is suitable for scenarios such as daily office work, personal computer assistants, multi-Agent collaboration, remote conversations, and mobile use. In terms of limitations: the memory system currently needs optimization; the Windows command sandbox is currently a write-isolation model, reads occur naturally according to the current user's permissions, and the network runs according to the current user's network permissions; the Windows installer has not yet undergone code signing; Anthropic's OAuth login is temporarily unavailable due to account ban risk; Hana will not automatically open a public network tunnel, and the public network entry point must be explicitly provided by the user.

Other Information

• License: Apache License 2.0
• Repository and Release: The repository and release addresses still retain the old openhanako URL during the current migration stage; the subsequent repository rename will be carried out separately.
• Issue Rules: Issues only describe problems or requirements and do not accept code implementations (fix suggestions, patches, diffs, implementation plans, or examples); non-compliant ones will be closed directly. For bugs, please have the Agent reproduce and investigate in the environment, and submit an acceptable problem report according to the Bug Report template: list the actual problem that occurred, the reproduction steps, and the acceptance method, without writing how to fix it. For feature suggestions, first chat with the Agent, then submit a Spec according to the Feature Request template: what you want, why you need it, and what counts as complete, without writing the implementation.
• Acknowledgments: The progressive disclosure structure of the beautify plugin HTML aesthetic specification of tw93/kami, namely the "router + on-demand retrieval of sibling sections," was inspired by it.