🔍 Click to Zoom

✨ Executive Overview (v1.1.18)

Neo-Secretary: Your Ambient Living-Space Companion

"Delegate autonomous AI coding to your PC, spend weekends with your family in the living room." Turn your spare smartphone into an ambient living-space companion for 1-tap remote approval across Claude Code, Cline, Cursor, and Antigravity.

💡 Note on Infographics & Mascot Characters

The banner above reflects an early visual prototype. In the current release (v1.1.18), Neo-Secretary features the official built-in skins "Hisho" and "Kyle", while "Shiitake-kun (🍄)" serves as the project mascot and brand icon. Furthermore, it has evolved into an ambient living-space companion designed for your living room sofa and kitchen rather than keeping you chained to a computer desk. (A refreshed visual photoshoot will be released in sprint ID 85).

🔥 6 Core Highlights of Neo-Secretary

🤖 1. One-Tap Remote Approval (FastMCP & Transparent Hooks): Review and approve AI coding commands from your couch or kitchen. PC actions automatically dismiss pending cards.

📱 2. Upcycle Spare Smartphones into an Ambient Companion: Place your unused phone in the living room. A living pixel mascot breathes and monitors autonomous builds.

🚀 3. Zero App Installs Required (Pure PWA): Instant zero-config connection via QR code on mobile Safari/Chrome. 0fps adaptive sleep preserves battery life.

📅 4. Integrated Tasks & Read-Only iCal Sync: Daily timeline scheduler, Quick-Add natural language tasks, habit trackers, and proactive calendar reminders.

🔒 5. Local-Only Boundary Defense (Air-Gapped Privacy): Per-device 256-bit cryptographic tokens, fail-closed isolation, and constant-time token verification.

💬 6. Bundled Offline Local AI (LFM2.5): Runs entirely offline on local CPU with zero cloud API keys needed. Ask your pet anything right from the chat bubble!

🎯 Real-World Scenarios

A Day in the Life with Neo-Secretary

How developers and power users eliminate downtime while delegating heavy tasks to autonomous AI agents.

⚡ Killer Use Case: Autonomous Development

1. Step Away During Heavy AI Coding Runs

Delegating large-scale refactoring, test suites, or package updates to Claude Code, Cline, Cursor, or Codex.

1️⃣ Prompt your agent on PC: "Refactor this module and generate comprehensive unit tests." Then step away from your desk.

2️⃣ Relax or do household chores: Make a fresh espresso, read a book on the couch, or attend to personal tasks without staring at the terminal.

3️⃣ Instant alert on mobile phone: When the agent hits a command permission checkpoint (`git push` or `npm test`), your phone vibrates with an amber/red banner!

4️⃣ One-tap remote decision: Inspect the proposed bash command and tap [✅ Approve] with one hand. No need to run back to your PC.

5️⃣ Victory celebration: Once all tasks and tests pass green, your mobile pet erupts into confetti and celebratory bounce animations! 🎉

🌅 Morning Routine

2. Proactive Briefing & Timeboxing

Start your workday with automated schedule synchronization and timeline organization.

1️⃣ Unified Daily Agenda: Today's calendar events and prioritized tasks are automatically chronological in your digital notebook.

2️⃣ 15-Minute Pre-Meeting Alerts: "Boss, your Sync Meeting starts in 15 minutes!" The desktop companion gently chimes.

3️⃣ Natural Language Quick Add: Type Submit budget report tomorrow at 5pm #finance !high to schedule deadlines instantly.

🍅 Focus & Wellness

3. Pomodoro Focus & Ergonomic Care

Prevent developer burnout while maintaining peak flow state.

1️⃣ 25m Focus + 5m Rest: Starting the timer switches your pet into high-focus posture. Rest periods trigger gentle tea suggestions 🍵.

2️⃣ Ergonomic Check-ins: After 45+ minutes of continuous typing, your companion reminds you to look at distant objects and hydrate.

🔒 Air-Gapped Privacy

4. Confidential Enterprise Work

Process proprietary code, meeting notes, and private ideas with zero cloud leakage.

1️⃣ 1-Click Model Download: Grab the ultra-lightweight LFM2.5 model (approx. 230MB) directly from settings.

2️⃣ 100% Local Inference: Even with network adapters disabled, conversational task brainstorming runs entirely on your local CPU.

Cheatsheet ①

Initial Setup & Quickstart Guide

From binary extraction to offline local LLM in under 60 seconds

Extract & Launch
(Zero Installation)

📦

Download NeoHisho.zip from GitHub Releases. Unzip and run NeoHisho.exe.

10-Sec Launch

1-Click Local AI
(LFM2.5 · 230MB)

🧠

Fetch ultra-lightweight LFM2.5 model in Settings. Operates air-gapped without API keys.

Zero API Keys

Interactive Tour
(Guided Onboarding)

💬

Your pet walks you through menus, mobile pairing, and digital notebook features.

Guided Tour

Wire AI Agents
(FastMCP Bridge)

🔌

Deterministic absolute-path wiring for Claude Code, Cline, Cursor, and Antigravity.

Ready in 30s

📘 Cheatsheet ①

Initial Setup & Quickstart Guide

From downloading the binary to 1-click offline local LLM setup in under 2 minutes.

Extract Release ZIP and Launch

Download NeoHisho.zip from GitHub Releases, extract to any folder, and double-click NeoHisho.exe (or start.bat if running from source). The companion appears at the bottom-right of your screen.

Enable Local LLM (Zero API Keys Needed)

Right-click the pet ➔ "⚙️ Settings" ➔ "🧠 AI Model" tab. Click "⚡ Download Ultra-Light Model (350M / 230MB)". In ~60 seconds, your air-gapped local AI assistant is fully operational.

Take the 3-Step Interactive Onboarding Tour

On first launch, your pet guides you through right-click menus, mobile pairing, and conversational tasks. You can re-trigger this tour anytime from Settings.

📘 Neo-Secretary Cheatsheet ① [Initial Setup & Environment]

Last Updated: 2026-09-13

Fast-track guide to downloading, starting, and configuring Neo-Secretary.

🚀 1. Installation Steps

Extract the Distribution Archive: Unzip NeoHisho.zip to your preferred workspace directory.
Run the Executable: Double-click NeoHisho.exe. Your retro pixel pet will appear on your desktop.

🔒 2. Zero-Config Air-Gapped Privacy Mode (Recommended)

To use the app without cloud API keys and ensure complete data privacy:

Right-click the pet ➔ select "⚙️ Settings".
Under the "🧠 AI Model" tab, find the "Embedded Local LLM" card.
Click "⚡ Download Ultra-Lightweight Model (350M / 230MB)".
The model downloads in ~1 minute and configures DEFAULT_LLM_PROVIDER=local_gguf automatically.

⚙️ 3. Settings Window Structure

Tab	Primary Function	Use Case
🧠 AI Model	Toggle between Local GGUF, Google Gemini, Anthropic Claude, and OpenCode	Offline inference or high-speed cloud reasoning
🤖 External AI / MCP	Register to Claude Code, Cline, Cursor, Codex, and manage MCP tools	Remote one-tap command approvals
📅 External Integrations	Google Calendar read-only iCal sync, Tailscale VPN hostname	Schedule timeline & remote mobile access
📖 Guide & Diagnostics	Self-diagnostics, interactive tour replay, shortcut cheatsheet	Troubleshooting and feature reference

Cheatsheet ②

Mobile Pairing & Encrypted Mesh Guide

QR pairing, full-screen PWA, and living-space Tailscale mesh connectivity

Display QR Code
(Single Right-Click)

🖥️

Right-click your companion ➔ "📱 Mobile Desk Pet" to generate a secure pairing QR code.

1-Click QR

Scan with Camera
(Pure Web PWA)

📱

Scan with default phone camera. Opens instantly in browser with zero app store downloads.

No App Store

Add to Home Screen
(Full-Screen Mascot)

📲

Tap "Add to Home Screen". Hides browser chrome and launches as a retro desktop pet.

Full-Screen PWA

Living-Space Mesh
(Tailscale Security)

🛋️ ☕

Run autonomous AI on PC while relaxing in the living room. Encrypted mesh spans your entire home.

Living-Space Ambient

📱 Cheatsheet ②

Mobile Desk Pet PWA & Tailscale Encrypted Mesh Guide

Turn your unused smartphone into an ambient living-space companion. Works seamlessly on local Wi-Fi or across your home via encrypted Tailscale mesh.

📲

Local Wi-Fi Pairing (Default)

1. Connect PC and phone to the same Wi-Fi.
2. Right-click pet ➔ 📱 Mobile Connect.
3. Scan the QR code with phone camera.
4. Tap "Add to Home Screen" for full-screen PWA mode.

🌐

Remote Connectivity via Tailscale

1. Install Tailscale on PC & smartphone.
2. On PC, run tailscale serve 8765.
3. In Neo-Secretary Settings, enter your Tailscale machine name.
4. Scan the dedicated Tailscale QR code.
Note: 8765 is the default port. If you changed it via NEO_HISHO_PORT, substitute that value.

📱 Neo-Secretary Cheatsheet ② [Mobile Pairing & Zero-Trust PWA]

Last Updated: 2026-09-13

🛡️ Zero-Trust Security Guarantees

Cryptographic Bearer Token: Each mobile pairing receives an ephemeral 256-bit token. DB stores only salted SHA-256 hashes.
Fail-Closed Pairing Window: Tokens are generated only while the QR dialog is actively open on the desktop. Outside the window, connection requests are rejected with 401 Unauthorized.
Anti-Self-Approval Isolation: Command approval requests originating from the same IP as the requester are blocked, preventing malicious LAN self-escalation.

💡 PWA Full-Screen Tip

On iOS Safari, tap Share ➔ Add to Home Screen. On Android Chrome, tap Menu ➔ Install App. This enables wake-lock keep-alive, vibration haptics, and clean full-screen display without browser address bars.

Cheatsheet ③

Digital Notebook & Google Calendar Sync

Proactive briefings, natural language tasks, habit tracking, and Pomodoro

iCal Secure Sync
(Zero Credentials)

📅

Paste your secret Google Calendar iCal URL. Fetches events read-only without storing OAuth tokens.

Read-Only Safety

Natural Language
(Quick Task Add)

📝

Type "Submit report tomorrow 18:00 #finance !high" to parse dates, tags, and priorities instantly.

Smart Parser

Habit Tracker
(Streak Heatmap)

🌱

Track hydration, reading, and fitness routines. Your companion cheers for your streak milestones.

Visual Heatmap

Pomodoro Focus
(Burnout Shield)

🍅 🍵

25m work + 5m rest cycles. Pet adopts focus pose during work and suggests tea on breaks.

Flow State

📅 Cheatsheet ③

Digital Notebook, Tasks & Google Calendar Sync

Timeline schedule management, quick natural-language task creation, and habit tracking.

📝

Natural Language Quick-Add

Type Tomorrow 2pm Client review #work !high in the chat bubble to create prioritized tasks with automated date parsing.

🔗

Google Calendar iCal Sync

Paste your secret iCal URL in Settings. Fetches events in read-only mode with zero OAuth configuration or credential leaks.

🍅

Pomodoro & Habit Heatmap

Track daily micro-habits and focus sessions. Visual heatmap displays streaks and completion velocity.

📅 Neo-Secretary Cheatsheet ③ [Notebook, Tasks & Habits]

Last Updated: 2026-09-13

⚡ Quick Natural Language Syntax

Input Phrase	Parsed Due Date	Priority / Tag
`Submit report tomorrow 18:00 !3 #finance`	Tomorrow 18:00	Priority 3 (High), #finance
`Gym workout next monday morning #habit`	Next Monday 09:00	Normal, #habit
`Quick meeting in 30 minutes !urgent`	+30 mins from now	Urgent (Top)

Cheatsheet ④ · Core Feature

AI Agent Remote Approval & 2-Layer Integration

Claude Code, Cline, Cursor, Antigravity, and cancel_pending synchronization

30-Second Setup
(Absolute Paths)

⚡

Deterministic absolute-path configuration for Claude Code, Cline, and Cursor (fixes Windows #54786).

Deterministic Paths

Transparent Hooks
(Auto Intercept)

🛡️

OpenCode & shell hooks intercept command execution. Pushes alerts with Jev safety audit scores.

Layer 1 Hooks

PC Auto-Dismissal
(cancel_pending)

✨ 📲

When approved on PC, mobile pending cards dismiss immediately! Zero lingering notification clutter.

Ambient UX

1-Tap & Earbuds
(No-Look Decisions)

🎧 👆

Approve via single mobile tap or Bluetooth earphone play/pause media button with coffee in hand.

Save Life Time

🤖 Cheatsheet ④ [Core Hero Feature]

Autonomous AI Coding Remote Approval & 2-Layer Integration

Bridge Claude Code, Cline, Cursor, and Codex with your mobile phone. Features a 3-Tier Policy Engine, cancel_pending auto-dismissal, and SQLite Audit Logging.

🛡️ 3-Tier Smart Approval Policy Engine

🟢 Auto-Allow (Zero Friction): Safe read-only commands (`git status`, `git diff`, `pytest`, `cargo check`) are auto-approved in 0 milliseconds. Keeps your agent sprinting at full speed without bothering you.

🟡 Prompt (Standard Confirmation): Non-destructive file edits, `git commit`, and standard package installations push a polite mobile alert banner with haptic vibration.

🔴 Strict (High-Risk Warning): Destructive operations (`rm -rf`, `git reset --hard`, `push --force`) trigger an urgent crimson pulsing banner and confirmation sheet on mobile.

📝 Persistent Audit Trail: Every request, timestamp, client IP, and decision is written to the SQLite `approval_audit_logs` table with tamper-resistant record tracking for compliance.

🔌

Claude Code & Cline Deterministic MCP

• Claude Code: Register via terminal using absolute paths (bypasses Windows cwd bug):

claude mcp add hisho-bridge -- "C:/path/to/venv/Scripts/python.exe" "C:/path/to/hisho-kun/hisho_mcp_server.py"

• Cline: Add the identical absolute paths into cline_mcp_settings.json.

⚙️

Antigravity 1-Click Auto Registration

Open Neo-Secretary Settings ➔ "External AI / MCP" tab. Click "🚀 Auto-Register to Antigravity" to inject MCP configurations automatically!

🤖 Neo-Secretary Cheatsheet ④ [Agent Approval Platform & MCP Bridge]

Last Updated: 2026-09-13

⚡ MCP Tools Specification (`neo_hisho_bridge`)

MCP Tool Name	Arguments	Description
`ask_human_approval`	`command`, `summary`, `agent_name`	Forwards a bash command or action for user remote authorization.
`notify_task_completed`	`title`, `message`, `agent_name`	Triggers celebratory confetti and joyful bounce animations on mobile.
`notify_user_input_needed`	`question`, `choices`, `agent_name`	Requests textual clarification or multi-choice input on mobile.
`remember_boss_insight`	`category`, `insight`	Persists architectural lessons and user preferences into long-term DB memory.

Cheatsheet ⑤

Local Offline LLMs & Character Skins

Air-gapped LFM2.5 model and official built-in skins

Ultra-Light Model
(350M · 230MB)

💻

1-click download of Liquid AI LFM2.5 in Settings. High-speed local CPU inference.

Zero GPU Needed

100% Air-Gapped
(Zero Leakage)

🔒

Zero telemetry, zero cloud data transfer. Process sensitive code and ideas in privacy.

Air-Gapped Safety

Hisho & Kyle
(Official Skins)

👔 🐚

Switch between Hisho (Assistant) and Kyle (Shell Spirit) with a single click in Settings.

2 Built-in Skins

🧠 Cheatsheet ⑤

Local Offline LLMs & Character Skins

Liquid AI LFM2.5 lightweight models, retro 16-bit sound effects, and official pixel mascot skins.

📴

Liquid AI LFM2.5 (350M)

Only ~230MB disk footprint. High-efficiency inference runs seamlessly even on lightweight laptop CPUs with zero GPU requirements.

🎭

Character Mascot Skins

Switch between Hisho (Professional Assistant) and Kyle (Nostalgic Shell Spirit) with a single click in Settings.

🔊

Retro Chimes & Audio

8-bit retro sound effects and text-to-speech briefing. Alerts you when critical milestones or approvals are needed.

🧠 Neo-Secretary Cheatsheet ⑤ [Local LLM & Built-in Skins]

Last Updated: 2026-10-04 (v1.1.18)

🎭 Built-in Mascot Skins & Roadmap

Neo-Secretary currently ships with 2 official built-in skins available via the Settings menu:

Hisho: Professional 16-bit pixel secretary assistant.
Kyle: Nostalgic retro shell spirit assistant.

Note: Dynamic folder-based custom character mods are planned for Phase I in the project roadmap.

❓ Frequently Asked Questions

Troubleshooting & FAQ

Quick solutions for common connection and configuration questions.

Q1: The QR code won't open on my phone browser.

A: Ensure both your PC and phone are connected to the exact same Wi-Fi router. If Windows Defender Firewall shows a popup, click "Allow access for Private Networks". You can also test binding port 8765 via Tailscale VPN.

Q2: Can I use this with Claude Code without running a server manually?

A: Yes! NeoHisho.exe launches the sync server and internal MCP server automatically in the background. Adding the MCP server entry into Claude Code takes just one command.

Q3: How does Anti-Self-Approval prevent security exploits?

A: If an agent running on 127.0.0.1 requests approval, Neo-Secretary refuses to accept approval decisions from 127.0.0.1. Approvals must originate from a verified mobile client with a cryptographically signed Bearer token.

Q4: What happens if I lose my internet connection?

A: Neo-Secretary operates entirely on your local area network (LAN). All features—including MCP command approvals, offline GGUF chat, tasks, and habit tracking—function 100% reliably without an external internet connection.