User Guide — Gnomad Desktop Assistant

Version: 0.2.0-beta.1

Project site: davidthegnomad.github.io/gnomad-desktop-assistant
Studio: gnomadstudio.org

Introduction

Gnomad is a desktop AI assistant that lives in your menu bar (macOS) or system tray (Windows/Linux). It can:

• Chat using cloud (DeepSeek) or local (Ollama) models
• See your active app, window title, and clipboard (footer context strip)
• Run real shell commands and file operations in a controlled workspace
• Store skills and reference documents in a knowledge library

Closing the window hides Gnomad to the tray—it does not quit the app unless you choose Quit from the tray menu.

Installation

macOS

• Download the .dmg from GitHub Releases or the project site
• Drag Gnomad to Applications
• First open: right-click → Open if Gatekeeper blocks unsigned alpha builds

Windows

• Run the .msi or setup.exe installer
• Launch from Start Menu; allow tray icon if prompted

Linux

• Debian/Ubuntu: sudo apt install ./gnomad_*_amd64.deb
• Fedora/RHEL: sudo dnf install ./gnomad-*-1.x86_64.rpm
• Other: chmod +x gnomad_*.AppImage && run it

See LINUX_PACKAGES.md for distro-specific details.

First launch & onboarding

On first launch (when no API key and no Ollama URL are configured), a welcome wizard appears:

1. Choose provider — Cloud API (DeepSeek) or Local model (Ollama)
2. Configure — API key + model, or Ollama URL + model tag

Keys are saved to your system keychain. Change setup anytime in Settings → Re-run setup wizard.

Developers may use .env with DeepSeek_API_KEY; the UI shows Set from .env and locks that key slot.

Opening and closing Gnomad

Tray menu: Show Gnomad, Pop Out Window, Settings, Visit gnomadstudio.org, About, Quit.

Window modes

Use the four chips in the title bar (or View menu in windowed mode):

Main interface overview

Title bar: Window modes, theme toggle, Knowledge (book), Settings (gear).

Sidebar: New chat, history, knowledge shortcut; resize, collapse, flip side.

Center: Welcome, suggestion chips, messages, shell output blocks.

Composer: Input, attachments, terminal (local), provider/model, send.

Context footer: Active app, window title, clipboard, permission banner (macOS).

Chat & composer

1. Type or click a suggestion chip
2. Optionally attach files
3. Choose Cloud/Local and model
4. Press Send or Enter

While thinking: Click Stop to interrupt shell activity.

Direct shell (local): Prefix with $ or use the terminal icon.

Cloud vs local AI

Switch via composer or Settings → Model & API.

Changing models and API keys

Composer: Provider and model dropdowns.

Settings → Model & API: Cloud model or Ollama URL + model name.

Settings → API keys: Add/change/remove DeepSeek key (keychain). .env keys are locked in UI.

Agent: shell & filesystem

• Cloud: Tools for shell, files, workspace (up to 10 steps per message)
• Local: gnomad-run tags, $ commands, optional command planner
• Shell session: Persistent cwd; reset in Settings → Agent shell
• Workspace: Settings → Agent access → Change folder
• Trust: Standard (workspace + gates) or YOLO (broader FS)
• Audit: {app_data}/gnomad/agent-audit.jsonl

Safety: Sudo Gate & Path Gate

Sudo Gate — Risky shell (sudo, rm -rf, etc.): read reason, Approve or Deny. Approval mints a signed HITL token bound to the exact command (single-use, ~2 min TTL). Passing approval without a token is rejected.

Path Gate — Standard mode: files outside workspace need approval. Allow once mints a signed path token bound to the canonical path and scope (read/write).

Embedded GGUF (optional build)

When built with embedded-llm (npm run tauri:dev:embedded):

1. Settings → Agent access → GGUF path — point to a small .gguf (e.g. Qwen2.5-Coder 1.5B Q4)
2. Command planner uses GGUF in-process (no Ollama required for planner)
3. Experimental → Use GGUF for local chat — full local chat without Ollama
4. Experimental → Sandbox shell in YOLO — wrap shell in OS sandbox (macOS/Linux)

Terminal view (xterm.js)

While the agent runs commands, live PTY output streams in the thinking panel. On command cards, click Terminal view to replay ANSI-colored output in an embedded terminal.

Updates

Settings → Updates — choose Stable or Beta channel, then Check for updates. Requires signed release artifacts; see UPDATER.md.

Knowledge & skills library

Open via book icon or sidebar. Folders under gnomad/knowledge/:

• skills/ — instructions (.md, .txt, .json)
• agents/ — personas
• preferences/ — user preferences
• uploads/ — reference files

Add files in the panel; INDEX.md updates automatically.

Chat history & sidebar

• New chat: Sidebar + or ⌘/Ctrl+N
• Select / delete sessions in the list
• Layout: Resize, collapse, drag to flip side

Sessions stored locally on disk.

Settings reference

Theme: Sun/moon/monitor icon cycles Light → Dark → System.

Voice input (beta)

1. Settings → Privacy → Enable microphone dictation
2. Click the mic button in the composer (push-to-talk — click again to stop)
3. Speech is converted to text by your OS/browser engine and appended to the message

Audio may be processed by Apple, Google, or another vendor depending on platform — not sent to Gnomad servers. Disable anytime in Settings.

Keyboard shortcuts

Platform-specific notes

macOS: Accessibility for automation; admin auth for elevation.

Windows: Tray near notification area; elevated cmds in admin terminal.

Linux: WebKitGTK + AppIndicator; optional xdotool, wl-paste, xclip. On Wayland, left-click the tray icon to open the menu (Settings shows a hint when Wayland is detected).

Troubleshooting

See TROUBLESHOOTING.md for the full guide. Quick fixes:

Privacy & data

• Chat and knowledge stay on your device
• Cloud prompts go to DeepSeek per their terms
• Local prompts go to your Ollama server
• API keys in OS keychain
• Clipboard included only when you send a message

See PRIVACY.md for the full policy.

Built with ❤️ by Gnomad Studio 🦙