undefined

```powershell

undefined

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

---

// 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"
}

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

~/.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
└── skills/             # Agent-local installed skills

undefined

---

// Via the Skills UI in the app, or programmatically:
const { skillManager } = engine;

await skillManager.installFromGitHub({
  repo: 'some-user/hanako-skill-weather',
  agentId: 'agent-abc123',
  safetyReview: true   // strict review enabled by default
});

---
name: web-scraper
version: 1.0.0
description: Scrape structured data from web pages
tools:
  - browser
  - javascript
permissions:
  - network
---

undefined

// skills/my-skill/index.js
export default {
  name: 'my-skill',
  version: '1.0.0',
  description: 'Does something useful',

  // Tools this skill adds to the agent
  tools: [
    {
      name: 'fetch_weather',
      description: 'Fetch current weather for a city',
      parameters: {
        type: 'object',
        properties: {
          city: { type: 'string', description: 'City name' }
        },
        required: ['city']
      },
      async execute({ city }) {
        const res = await fetch(
          `https://wttr.in/${encodeURIComponent(city)}?format=j1`
        );
        const data = await res.json();
        return {
          temp_c: data.current_condition[0].temp_C,
          description: data.current_condition[0].weatherDesc[0].value
        };
      }
    }
  ]
};

// Accessing memory programmatically (core/lib/memory)
import { MemoryManager } from './lib/memory/index.js';

const memory = new MemoryManager({ agentId: 'agent-abc123' });

// Store a memory event
await memory.store({
  type: 'conversation',
  content: 'User prefers dark mode and terse responses',
  importance: 0.8   // 0.0–1.0; higher = decays slower
});

// Retrieve relevant memories
const relevant = await memory.query({
  query: 'user preferences',
  limit: 10,
  minRelevance: 0.5
});

// Trigger manual compilation (normally runs automatically)
await memory.compile();

// File operations
{ tool: 'read_file',   args: { path: '/Users/me/notes.txt' } }
{ tool: 'write_file',  args: { path: '/Users/me/out.txt', content: '...' } }

// Terminal
{ tool: 'run_command', args: { command: 'ls -la', cwd: '/Users/me' } }

// Browser & web
{ tool: 'browse',      args: { url: 'https://example.com' } }
{ tool: 'web_search',  args: { query: 'OpenHanako latest release' } }

// Screen
{ tool: 'screenshot',  args: {} }

// Canvas
{ tool: 'draw',        args: { instructions: '...' } }

// Code execution
{ tool: 'execute_js',  args: { code: 'return 2 + 2' } }

Tier 0 — Denied:     System paths (/System, /usr, registry hives)
Tier 1 — Read-only:  Home directory files outside agent desk
Tier 2 — Read-write: Agent desk folder only
Tier 3 — Full:       Explicitly granted paths (user confirms)

// core/AgentManager usage example
import { createEngine } from './core/engine.js';

const engine = await createEngine();

// Create a second agent
const researchAgent = await engine.agentManager.create({
  name: 'Researcher',
  personalityTemplate: 'researcher.md',
  models: {
    chat: 'deepseek-chat',
    utility: 'gpt-4o-mini',
    utilityLarge: 'gpt-4o'
  }
});

// Delegate a task from one agent to another via channel
await engine.hub.channelRouter.delegate({
  fromAgent: 'agent-abc123',
  toAgent: researchAgent.id,
  task: 'Find the top 5 papers on mixture-of-experts published in 2025',
  returnTo: 'agent-abc123'   // result routed back automatically
});

// hub/scheduler usage
import { Scheduler } from './hub/scheduler.js';

const scheduler = new Scheduler({ agentId: 'agent-abc123' });

// Run a task every day at 9am
scheduler.cron('daily-briefing', '0 9 * * *', async () => {
  await agent.run('Summarize my desk notes from yesterday and post to #briefing channel');
});

// Heartbeat — check desk for new files every 5 minutes
scheduler.heartbeat('desk-watch', 300_000, async () => {
  const changed = await agent.desk.checkChanges();
  if (changed.length > 0) {
    await agent.run(`New files on desk: ${changed.join(', ')} — summarize and notify me`);
  }
});

scheduler.start();

// lib/bridge configuration
const bridgeConfig = {
  telegram: {
    enabled: true,
    token: process.env.TELEGRAM_BOT_TOKEN,
    allowedUsers: [process.env.TELEGRAM_ALLOWED_USER_ID]
  },
  feishu: {
    enabled: true,
    appId: process.env.FEISHU_APP_ID,
    appSecret: process.env.FEISHU_APP_SECRET
  },
  qq: {
    enabled: false
  }
};

await engine.agentManager.setBridges('agent-abc123', bridgeConfig);

// WebSocket — real-time chat stream
const ws = new WebSocket('ws://localhost:PORT/ws/agent-abc123');

ws.send(JSON.stringify({
  type: 'chat',
  content: 'Summarize my project folder'
}));

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  // msg.type: 'chunk' | 'tool_call' | 'tool_result' | 'done'
  console.log(msg);
};

// HTTP — one-shot task
const res = await fetch('http://localhost:PORT/api/agent/agent-abc123/run', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ task: 'List all .md files on my desk' })
});
const result = await res.json();

undefined

```javascript
// tests/memory.test.js example pattern
import { describe, it, expect, beforeEach } from 'vitest';
import { MemoryManager } from '../lib/memory/index.js';

describe('MemoryManager', () => {
  let memory;

  beforeEach(async () => {
    memory = new MemoryManager({ agentId: 'test-agent', inMemory: true });
    await memory.init();
  });

  it('stores and retrieves a memory', async () => {
    await memory.store({ type: 'fact', content: 'User likes dark mode', importance: 0.9 });
    const results = await memory.query({ query: 'dark mode', limit: 5 });
    expect(results[0].content).toContain('dark mode');
  });
});

undefined

undefined

// Force a manual compile
await engine.agentManager.getAgent('agent-abc123').memory.compile({ force: true });

// Temporarily disable safety review for trusted local skills only
await skillManager.installLocal({
  path: './my-skill',
  agentId: 'agent-abc123',
  safetyReview: false   // ⚠️ only for local dev, never for untrusted sources
});