Openhanako Personal Ai Agent

# OpenHanako Personal AI Agent

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

OpenHanako is a desktop AI agent platform built on Electron that gives each agent persistent memory, a distinct personality, and the ability to autonomously operate your computer — read/write files, run terminal commands, browse the web, execute JavaScript, and manage schedules. Multiple agents can collaborate via channel group chats or task delegation.

---

## Installation

### Download & Run

```bash
# macOS Apple Silicon — download from releases page
# https://github.com/liliMozi/openhanako/releases
# Mount the .dmg and drag to Applications

# First launch — bypass Gatekeeper (one-time):
# Right-click app → Open → Open
```

```powershell
# Windows — run the .exe installer from releases
# SmartScreen warning: click "More info" → "Run anyway"
```

### Build from Source

```bash
git clone https://github.com/liliMozi/openhanako.git
cd openhanako
npm install

# Development mode
npm run dev

# Build for production
npm run build

# Run tests
npm test
```

---

## First-Run Onboarding

On first launch, the wizard asks for:

1. **Language** — UI language preference
2. **Your name** — used by agents when addressing you
3. **Model provider** — any OpenAI-compatible endpoint
4. **Three models:**
   - `chat model` — main conversation (e.g. `gpt-4o`, `deepseek-chat`)
   - `utility model` — lightweight tasks, summarization (e.g. `gpt-4o-mini`)
   - `utility large model` — memory compilation, deep analysis (e.g. `gpt-4o`)

### Provider Configuration Examples

```json
// OpenAI
{
  "baseURL": "https://api.openai.com/v1",
  "apiKey": "process.env.OPENAI_API_KEY"
}

// DeepSeek
{
  "baseURL": "https://api.deepseek.com/v1",
  "apiKey": "process.env.DEEPSEEK_API_KEY"
}

// Local Ollama
{
  "baseURL": "http://localhost:11434/v1",
  "apiKey": "ollama"
}

// Qwen (Alibaba Cloud)
{
  "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
  "apiKey": "process.env.DASHSCOPE_API_KEY"
}
```

---

## Project Architecture

```
openhanako/
├── core/           # Engine orchestration + Managers (Agent, Session, Model, Preferences, Skill)
├── lib/            # Core libraries
│   ├── memory/     # Custom memory system (recency decay)
│   ├── tools/      # Built-in tools (files, terminal, browser, screenshot, canvas)
│   ├── sandbox/    # PathGuard + OS-level isolation (Seatbelt/Bubblewrap)
│   └── bridge/     # Multi-platform adapters (Telegram, Feishu, QQ)
├── server/         # Fastify 5 HTTP + WebSocket server
├── hub/            # Scheduler, ChannelRouter, EventBus
├── desktop/        # Electron 38 main process + React 19 frontend
├── tests/          # Vitest test suite
└── skills2set/     # Built-in skill definitions
```

### Key Managers (via unified engine facade)

| Manager | Responsibility |
|---------|---------------|
| `AgentManager` | Create, load, delete agents |
| `SessionManager` | Conversation sessions per agent |
| `ModelManager` | Route requests to configured providers |
| `PreferencesManager` | User/global settings |
| `SkillManager` | Install, enable, disable, sandbox skills |

---

## Agent Configuration

Each agent is a self-contained folder you can back up:

```
~/.openhanako/agents/<agent-id>/
├── personality.md      # Personality template (free-form prose or structured)
├── memory/
│   ├── working.db      # Recent events (SQLite WAL)
│   └── compiled.md     # Long-term compiled memory
├── desk/               # Agent's file workspace
│   └── notes/          # Jian notes
└