Introduction to Jarvis Desktop Glas

Relevant source files

The following files were used as context for generating this wiki page:

• instructions/CONTEXT.md
• instructions/design-backend-prompt.txt
• instructions/AGENTS.md
• instructions/DESIGN.md
• backend/src/handler.ts
• src/index.html
• SOUL.md
• CONTRIBUTING.md

Jarvis Desktop Glas is a modern, native "Control-Room" desktop application designed as a highly personalized AI assistant framework. Built with a futuristic Sci-Fi and Cyberpunk minimalism aesthetic, it functions as a personal operating system interface that integrates voice interaction, long-term memory, system automation, and multi-agent collaboration. The project utilizes a glassmorphism design language, combining high-tech HUD elements with a central interactive 3D orb.

The system is architected as a local-first application, ensuring privacy by keeping personal device state, local activity, and memory within the user's environment. It bridges local HTTP/IPC streams with AI models (such as xAI Grok and Ollama) to execute tasks ranging from browser automation to complex file management.

Sources: instructions/CONTEXT.md:3-8, instructions/design-backend-prompt.txt:8-12, instructions/design-frontend-prompt.txt:4-9

System Architecture

The project follows a modular, three-tier architecture that separates machine control, user experience, and intelligence processing.

Core Components

Component	Responsibility	Technical Stack
Electron Shell	Process lifecycle, native filesystem access, IPC bridge, and window management.	Electron, TypeScript
Renderer	Presentation layer, React components, 3D Orb (Three.js), and Web Audio API.	React, Three.js, Vanilla CSS3
Backend Service	Agent workflows, RAG (Retrieval-Augmented Generation), Model orchestration, and SSE event streaming.	Bun, TypeScript
Shared Package	Canonical design tokens, runtime-validated API types, and shared contracts.	@jarvis/shared

Sources: instructions/CONTEXT.md:11-14, instructions/design-backend-prompt.txt:10-15, instructions/AGENTS.md:14-19

The Orb Identity System

The central "Orb" serves as a composite semantic system indicator, providing visual feedback on the assistant's internal state. It is not merely decorative; its behavior is driven by a strictly typed state contract.

Orb States and Visual Mappings

The orb transitions through various states based on subsystem feedback:

State	Semantic Meaning	Visual Representation
idle	Core initialized, no active work.	Muted cyan, slow orbit.
ready	Local service is healthy.	Luminous cyan/blue, steady pulse.
listening	Voice intake is active.	Green/cyan receptive pulse.
thinking	Model inference/processing is active.	Violet/blue faster orbit.
responding	Response output/playback is active.	Bright cyan/green expansion.
error	Runtime fault requires attention.	Red high-contrast warning.
disconnected	Local service unreachable.	Dim desaturated core.

Sources: instructions/design-backend-prompt.txt:53-65, src/index.html:437-448

Intelligence & Memory Core

Jarvis operates on a "Soul" prompt and a "LifeOS" context, allowing it to act as a discrete butler rather than a generic chatbot.

SOUL.md and Identity

The assistant's personality is defined in SOUL.md. Key principles include:

• Tone: Analytical, discrete, and execution-focused.
• Address: Refers to the user as "Master".
• Rule: "Maximum Intelligence. Minimum Interruption." Jarvis plans and executes multi-step tasks silently unless explicit human-in-the-loop approval is required.

Sources: SOUL.md:1-25, backend/src/handler.ts:33-51

LifeOS and Persistent Memory

LifeOS represents the user's persistent "TELOS" (Mission, Values, Current State). These files are stored locally in the user's Documents folder to survive reinstalls. The system uses these to disambiguate user preferences without repeated prompting.

Automation & Action Engine

Jarvis features a Multi-Agent architecture where different "Sub-Agents" (Planner, Researcher, Coder, Reviewer) collaborate on complex goals.

Action Approval Lifecycle

To ensure security, sensitive actions follow a strict lifecycle requiring human-in-the-loop (HITL) approval:

1. Proposed: The agent identifies an intent (e.g., system.shutdown, scratchpad.write).
2. Review: The intent is sent to the renderer via a JarvisActionIntent event.
3. Decision: The user approves or rejects the action via the HUD.
4. Execution: If approved, the action moves to executing and then completed or failed.

Sources: instructions/design-backend-prompt.txt:47-51, backend/src/agent-orchestrator.ts:24-125, backend/src/handler.ts:168-308

Technical Implementation Details

Security Principles

1. Local Loopback Only: The backend service binds strictly to 127.0.0.1.
2. Origin Allowlisting: Rejects requests from non-allowlisted browser origins.
3. Renderer Isolation: The Electron renderer is sandboxed with context isolation and a restrictive Content Security Policy (CSP).
4. Pairing Seam: Sensitive routes require a 6-digit OTP pairing code for authentication.

Sources: instructions/design-backend-prompt.txt:69-79, backend/src/handler.ts:340-350, src/index.html:7-9

Development and Build Commands

The project uses Bun as the primary runtime and bundler.

# Install dependencies
bun install

# Start the Electron app (includes build)
bun run start

# Build production bundles
bun run build

# Create Windows Installer
bun run dist:win

Sources: instructions/CONTEXT.md:32-38, package.json:11-18, CONTRIBUTING.md:12-25

Conclusion

Jarvis Desktop Glas is an evolving AI assistant framework that prioritizes local control, futuristic design, and intelligent automation. By combining native Electron power with flexible AI backend adapters, it provides a foundation for users to build their own personalized AI "Control Room."

Sources: instructions/design-backend-prompt.txt:140-145, SOUL.md:370-375