MakoCode — Mako Edition Agent

一个自带完整 Galgame 界面的桌面 AI Agent
以《千恋＊万花》常陆茉子为主题形象，封装 Claude Code CLI 为沉浸式视觉小说体验

✨ 功能 • 🚀 快速开始 • 📦 安装 • 🔧 技术栈 • 📄 协议

---

✨ Features

🎮 Galgame Immersive Interface

• Character Sprite System: Dual characters — Mako Tsuge + Yoshino Asamake, over 110 PNG expression sprites
• Dynamic Position State Machine: Speaker centers & enlarges, listener shifts side & shrinks, 0.7s smooth transition
• Scene Backgrounds: 6 Japanese-style scenes (Japanese Room / Bathhouse / Dining Hall / Dojo / Inn / Shrine), 1.5s fade-in/out
• BGM System: 30+ original soundtracks from Senren＊Banka, auto-switching by scene
• Sakura Particles: 35 petals falling eternally, random size/speed/rotation
• Thinking Speech Bubble: Mako's signature playful popups while the AI is thinking
• Typewriter Effect: Character-by-character display + Markdown rendering + KaTeX formula support

🗣️ Voice System

• 30 pre-generated greeting voices (GPT-SoVITS TTS)
• 7 thinking voices ("Hmm.../Meow.../Ah..." etc.)
• Voice cache management (FIFO, 200MB cap)
• Independent volume control

🔀 Multi-LLM Backend

One-click switching across 9 AI providers:

Provider	Preset ID
🚀 DeepSeek	deepseek
🏛️ Anthropic	anthropic
🔀 OpenRouter	openrouter
⚡ SiliconFlow	siliconflow
☁️ Alibaba DashScope	dashscope
🌋 Volcano Engine	volcano
💼 Tencent Hunyuan	tencent
🌙 Kimi	moonshot
🔵 Baidu Qianfan	qianfan

🧙 First-Setup Wizard

• Auto-detects Node.js / Git / Claude Code installation status
• One-click silent background installation (bundled Node.js + Git installers)
• API configuration + connection test
• Vendor preset modal for one-click filling

✏️ Character Customization

• Built-in Markdown personality editor (main profile + world view dual tabs)
• Modify character personality, speech style, and world setting
• Takes effect on new sessions

📂 Beginner Friendly

• Settings panel — one-click open Skills / plugin folders
• File upload (images/documents/code, 50MB limit)
• 33 quick commands (triggered by typing /)
• Auto-expanding input box (multi-line support)
• Save system (auto + manual + multi-slot)

🔄 Auto-Update

• In-app update check + background download
• NSIS silent installation — no manual reinstall needed

---

🚀 Quick Start

Method 1: Download Installer (Recommended)

Download the latest MakoCode Setup x.x.x.exe from Releases and double-click to install.

安装器会引导你完成：

1. Auto-detection and installation of Node.js / Git / Claude Code
2. API configuration (bring your own DeepSeek or other LLM API Key)
3. Connection test → enter Mako's world

Method 2: Run from Source

# 1. 克隆仓库
git clone https://github.com/liebaojun/makocode.git
cd makocode

# 2. 安装依赖
npm install

# 3. 配置 API Key
cp mako-settings.example.json mako-settings.json
# 编辑 mako-settings.json，填入你的 API Key

# 4. 启动
npm start

Prerequisites: Node.js ≥ 18, Git, Claude Code CLI (npm install -g @anthropic-ai/claude-code)

---

📦 Installation

Build Installer

npm run build        # 完整 NSIS 安装器 → dist/
npm run build:dir    # 仅解压版（调试用）

Installer Contents

Component	Size	Description
MakoCode source + assets	~400MB	Sprites/BGM/Voice/UI
Node.js installer	~32MB	Auto-installed
Git installer	~63MB	Auto-installed
Claude Code CLI	Online download	npm global install

---

🔧 Tech Stack

Layer	Technology
Desktop Framework	Electron 31+
Frontend	Vanilla HTML + CSS + JavaScript (zero framework)
Backend	Node.js HTTP Server (zero external dependencies)
AI Engine	Claude Code CLI
Build/Distribution	electron-builder + NSIS
Auto-Update	electron-updater (GitHub Releases)
Markdown	marked.js
Formulas	KaTeX
Voice	GPT-SoVITS pre-generated WAV

Project Structure

makocode/
├── electron-main.js      # Electron 主进程
├── server.js             # HTTP 后端（聊天/设置/存档）
├── preload.js            # Electron 桥接
├── galchat.html          # 主界面（对话/角色/BGM/樱花）
├── wizard.html           # 首次配置向导
├── package.json          # 项目 + 构建配置
├── lib/                  # 共享模块 (5 个)
│   ├── constants.js      #   全局常量
│   ├── utils.js          #   工具函数
│   ├── settings.js       #   设置管理
│   ├── installer.js      #   后台安装
│   └── llm-presets.js    #   LLM 供应商预设
├── assets/               # 游戏资源
│   ├── sprites/          #   角色立绘
│   ├── backgrounds/      #   场景背景
│   ├── bgm/              #   背景音乐
│   ├── voice/            #   语音
│   └── images/           #   头像/图标
├── bundled-tools/        # 预装工具 (Node.js MSI + Git EXE)
├── .claude/              # Claude Code 配置 + 茉子专属 skills
└── dist/                 # 构建输出 (不在仓库中)

---

⚠️ Important Notes

Copyright Notice

Character sprites, background music, and background images in this software are from Yuzusoft's Senren＊Banka, copyright © Yuzusoft. These assets are for fan non-commercial use only. They will be removed immediately upon request from the rights holder.

AI-Generated Content

This software uses AI LLMs to generate dialogue. Output may be inaccurate or inappropriate. Use at your own discretion.

API Fees

This software requires you to bring your own LLM API Key (e.g., DeepSeek). API call fees may apply.

---

📄 License

• Code: MIT License © 2026 liebaojun
• Assets: Copyright © Yuzusoft, non-commercial use only

See LICENSE for details.

---

---

MakoCode — Mako-chan Agent

A desktop AI Agent with a full Galgame-style interface
Featuring 常陸茉子 (Hitachi Mako) from *Senren＊Banka* as the character theme,
wrapping Claude Code CLI into an immersive visual novel experience

✨ Features • 🚀 Quick Start • 📦 Installation • 🔧 Tech Stack • 📄 License

---

✨ Features {#features-en}

🎮 Galgame Immersive Interface

• Character Sprite System: Dual characters — Aji-Mako + Asada Yano, 110+ PNG expression sprites
• Dynamic Position State Machine: Speaker centers & enlarges, listener shifts side & shrinks, 0.7s smooth transition
• Scene Backgrounds: 6 Japanese-style scenes (Japanese Room / Bathhouse / Dining Hall / Dojo / Inn / Shrine), 1.5s fade-in/out
• BGM System: 30+ original soundtracks from Senren＊Banka, auto-switching by scene
• Sakura Particles: 35 petals falling eternally, random size/speed/rotation
• Thinking Speech Bubble: Mako-chan's signature playful popup while AI is thinking
• Typewriter Effect: Character-by-character display + Markdown rendering + KaTeX formula support

🗣️ Voice System

• 30 pre-generated greeting voices (GPT-SoVITS TTS)
• 7 thinking voices ("Hmm.../Nya.../Ah..." etc.)
• Voice cache management (FIFO, 200MB cap)
• Independent volume control

🔀 Multi-LLM Backend

One-click switching across 9 AI providers:

Provider	Preset ID
🚀 DeepSeek	deepseek
🏛️ Anthropic	anthropic
🔀 OpenRouter	openrouter
⚡ SiliconFlow	siliconflow
☁️ Alibaba DashScope	dashscope
🌋 Volcano Engine	volcano
💼 Tencent Hunyuan	tencent
🌙 Kimi (Moonshot)	moonshot
🔵 Baidu Qianfan	qianfan

🧙 First-Setup Wizard

• Auto-detects Node.js / Git / Claude Code installation status
• One-click silent background installation (bundled Node.js + Git installers)
• API configuration + connection test
• Vendor preset modal for one-click filling

✏️ Character Customization

• Built-in Markdown personality editor (main profile + world view dual tabs)
• Modify character personality, speech style, and world setting
• Takes effect on new sessions

📂 Beginner Friendly

• Settings panel — one-click open Skills / plugin folders
• File upload (images/documents/code, 50MB limit)
• 33 quick commands (triggered by typing /)
• Auto-expanding input box (multi-line support)
• Save system (auto + manual + multi-slot)

🔄 Auto-Update

• In-app update check + background download
• NSIS silent installation — no manual reinstall needed

---

🚀 Quick Start {#quick-start-en}

Method 1: Download Installer (Recommended)

Download the latest MakoCode Setup x.x.x.exe from Releases and double-click to install.

The installer guides you through:

1. Auto-detection and installation of Node.js / Git / Claude Code
2. API configuration (bring your own DeepSeek or other LLM API Key)
3. Connection test → enter Mako-chan's world

Method 2: Run from Source

# 1. Clone the repository
git clone https://github.com/liebaojun/makocode.git
cd makocode

# 2. Install dependencies
npm install

# 3. Configure API Key
cp mako-settings.example.json mako-settings.json
# Edit mako-settings.json, fill in your API Key

# 4. Launch
npm start

Prerequisites: Node.js ≥ 18, Git, Claude Code CLI (npm install -g @anthropic-ai/claude-code)

---

📦 Installation {#installation-en}

Build Installer

npm run build        # Full NSIS installer → dist/
npm run build:dir    # Extracted version (debugging)

Installer Contents

Component	Size	Description
MakoCode source + assets	~400MB	Sprites/BGM/Voice/UI
Node.js installer	~32MB	Auto-installed
Git installer	~63MB	Auto-installed
Claude Code CLI	Online download	npm global install

---

🔧 Tech Stack {#tech-stack-en}

Layer	Technology
Desktop Framework	Electron 31+
Frontend	Vanilla HTML + CSS + JavaScript (zero framework)
Backend	Node.js HTTP Server (zero external dependencies)
AI Engine	Claude Code CLI
Build/Distribution	electron-builder + NSIS
Auto-Update	electron-updater (GitHub Releases)
Markdown	marked.js
Formulas	KaTeX
Voice	GPT-SoVITS pre-generated WAV

Project Structure

makocode/
├── electron-main.js      # Electron main process
├── server.js             # HTTP backend (chat/settings/save)
├── preload.js            # Electron bridge
├── galchat.html          # Main UI (chat/character/BGM/sakura)
├── wizard.html           # First-setup wizard
├── package.json          # Project + build config
├── lib/                  # Shared modules (5)
│   ├── constants.js      #   Global constants
│   ├── utils.js          #   Utility functions
│   ├── settings.js       #   Settings management
│   ├── installer.js      #   Background installer
│   └── llm-presets.js    #   LLM provider presets
├── assets/               # Game resources
│   ├── sprites/          #   Character sprites
│   ├── backgrounds/      #   Scene backgrounds
│   ├── bgm/              #   Background music
│   ├── voice/            #   Voice files
│   └── images/           #   Avatars/icons
├── bundled-tools/        # Bundled installers (Node.js MSI + Git EXE)
├── .claude/              # Claude Code config + Mako-exclusive skills
└── dist/                 # Build output (not in repo)

---

⚠️ Important Notes

Copyright Notice

Character sprites, background music, and background images in this software are from Yuzusoft's Senren＊Banka, copyright © Yuzusoft. These assets are for fan non-commercial use only. They will be removed immediately upon request from the rights holder.

AI-Generated Content

This software uses AI large language models to generate dialogue. The output may contain inaccurate or inappropriate information. User discretion is advised.

API Fees

This software requires you to bring your own LLM API Key (e.g., DeepSeek). API call fees may apply.

---

📄 License {#license-en}

• Code: MIT License © 2026 liebaojun
• Assets: Copyright © Yuzusoft, non-commercial use only

See LICENSE for details.

---

Made with ❤️ for Mako-chan fans