Multi-expert AI workspace, powered by Nio & NioDB.

1. Overview

Unlike monolithic chatbots that attempt to answer everything with one generic prompt, NioGuru organizes your AI interactions into purpose-built domain specialists called Gurus. Each Guru has an intentional persona, curated instructions, attached domain documents, and isolated tool/skill bindings.

┌───────────────────────────────────────────────────────────────────┐
│                    NioGuru Web UI (Vue 3 + PWA)                   │
│   Gurus roster · Multi-chat feed · Markdown / KaTeX / Mermaid     │
│   @Mention switching · Timeline branching · Knowledge Vault       │
└──────────────────────────────┬────────────────────────────────────┘
                               │ HTTP / SSE (:3000)
                               ▼
┌───────────────────────────────────────────────────────────────────┐
│                    NioGuru Server (Hono + Node.js)                │
│                                                                   │
│  Streaming SSE · Lease concurrency locks · Turn sanitization      │
│  Conversation branching · Skill bundling · Model catalog relay    │
└───────────────────────┬───────────────────────────┬───────────────┘
                        │                           │
          NioDB Client  ▼              Child Process▼
┌──────────────────────────────────┐ ┌──────────────────────────────┐
│           NioDB Engine           │ │        Nio AI Engine         │
│         Port 7432 (Local)        │ │   nio run --format json      │
│                                  │ │                              │
│  ACID transactions · Leases      │ │  Companion Gateway: NioXS    │
│  Gurus · Conversations · Logs    │ │  Default: nioxs::nio-echo    │
│  Messages · Documents & Memory   │ │  Zero tool leakage filter    │
└──────────────────────────────────┘ └──────────────────────────────┘

2. Quickstart

Zero-Install Run via NPX

Launch NioGuru instantly on any system with Node.js 20+ installed:

npx @nio-labs/nio-guru

NioGuru automatically starts its embedded NioDB database engine, seeds the built-in Gurus, and opens your browser at http://localhost:3000.

From Source (Recommended for Development)

# 1. Clone the repository
git clone https://github.com/nio-labs/nio-guru.git
cd nio-guru

# 2. Install dependencies & build packages
pnpm install
pnpm build

# 3. Start NioGuru (starts NioDB on :7432 and NioGuru on :3000)
pnpm start

Docker / Container Run

docker run -d -p 3000:3000 -v nioguru-data:/home/node/.nioguru ghcr.io/nio-labs/nio-guru:latest

3. Built-in Gurus

NioGuru ships with built-in domain experts designed for specific engineering and creative challenges:

4. Skills System

Skills in NioGuru are packaged capability bundles containing instructions, examples, and tool references. Rather than cramming dozens of tools into the LLM system prompt, NioGuru mounts skills dynamically per turn:

# Install and manage native skills directly via nio CLI
nio skills add wshobson/agents/plugins/ui-design/skills/visual-design-foundations
nio skills list

5. System Architecture

NioGuru combines a reactive Vue 3 client, an ultra-fast Hono backend, and an embedded NioDB storage layer.

Client Layer (apps/web)

• Vue 3 & Pinia: Reactive stores for chat feed, guru state, active model, and attachments.
• Markdown & Math: Rendered with marked, highlight.js, and KaTeX for display and inline equations.
• Diagrams: In-browser mermaid.js with syntax error recovery and SVG export.

Server Layer (apps/server)

• Hono Server: High-throughput HTTP API with Server-Sent Events (SSE) streaming.
• Turn Sanitizer: Real-time streaming token filter that eliminates leaked tool calls from models lacking native function calling.
• Lease Coordinator: ACID concurrency leases that prevent multi-tab race conditions during generation.

6. Native NioDB Storage

NioGuru stores all chats, messages, and knowledge embeddings in local NioDB collections (running on port 7432):

// Collections configured in NioDB:
- nioguru_gurus          // Custom and seeded Guru personas
- nioguru_conversations  // Conversation metadata and preview state
- nioguru_messages       // Message history with role, thoughts, and attachments
- nioguru_documents      // Guru knowledge vault attachments
- nioguru_settings       // Local configuration & UI preferences

NioDB gives NioGuru instant crash resilience, zero data loss, and sub-millisecond query performance without needing external PostgreSQL or cloud databases.

7. Models & NioXS Companion Gateway

NioGuru connects to local and cloud models via the bundled NioXS companion gateway:

• Default Model: nioxs::nio-echo (Free, ultra-fast general answer model).
• Build Model: nioxs::nio-atom (Code generation and implementation tasks).
• Multimodal & Images: kilo::stepfun/step-3.7-flash:free for image understanding and synthesis.
• OpenAI-Compatible: Any provider configured in ~/.config/nio/config.json is automatically detected and available in the top model switcher.

8. Multi-Guru Mentions (@Guru)

Need a security perspective on an architectural design? You don't have to start a separate conversation:

@Security please review the JWT refresh rotation strategy described above for timing attacks.

Typing @ in the composer reveals an autocompleting list of all active Gurus. The mentioned Guru responds directly in the conversation thread while maintaining full conversational context.

9. Conversation Branching & Forking

Explore alternative implementations or creative paths without losing your work. Hover over any assistant or user message and click Fork / Branch:

• Creates a new timeline branched exactly from that turn.
• Preserves the full preceding message history and context.
• Allows experimenting with different prompts, models, or constraints cleanly.

10. Guru Knowledge Base & Documents

Ground your Gurus with proprietary documentation, architectural standards, or reference code:

• Click the Knowledge button in any Guru's header.
• Upload .md, .txt, .pdf, or code snippets.
• The Guru automatically indexes and references uploaded knowledge when answering queries in that workspace.

11. Resilient Mermaid Diagrams

LLMs frequently produce minor Mermaid syntax errors that break standard renderers. NioGuru features an automated diagram self-repair engine:

• Sequence Diagram Notes: Automatically clamps multi-participant notes (Note over A,B,C,D: → Note over A,D:) and folds raw multiline note text using <br/>.
• Flowcharts: Quotes unescaped parentheses and brackets inside node labels.
• Block Terminators: Auto-closes unclosed loop, alt, and rect blocks.
• SVG Preview & Export: Rendered diagrams include an interactive code view toggle and one-click SVG export.

12. Add Guru with AI Draft

Creating a customized specialist takes seconds. In the Add Guru dialog, type any role name (e.g. Quantum Computing Researcher or DevOps SRE) and click Fill with AI:

• Generates a concise tagline and domain-tailored system instructions.
• Matches an appropriate Lucide icon automatically.
• Suggests matching installed skills from your registry.
• Includes animated progress and instant cancellation support.

13. Progressive Web App (PWA)

NioGuru is fully installable as a Progressive Web App on desktop and mobile:

• Desktop: Runs in a borderless, focused window with native app shortcuts.
• Mobile & Tablets: Responsive slide-out sidebar, touch-optimized dialogs, and safe-area notch insets.
• Service Worker: Fast cached asset loading and offline resilience.

14. REST & SSE API

Integrate external tools, automations, or terminal scripts with NioGuru's HTTP endpoints:

# Health check
curl http://localhost:3000/api/health

# List available models
curl http://localhost:3000/api/models

# List Gurus
curl http://localhost:3000/api/gurus

# Stream a conversation turn via Server-Sent Events
curl -N -X POST http://localhost:3000/api/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"conversationId":"my-chat","prompt":"Explain distributed transactions"}'

15. Frequently Asked Questions