XMD Desktop - Terminal Navigator

A modern, lightning-fast terminal navigator and application launcher built with Material Design 3

✨ Features

🚀 Core Functionality

• Global Hotkey Access: Launch instantly with Ctrl+Space (configurable)
• Real-time Search: Find applications, files, and commands as you type
• Terminal-First Workflow: Direct command execution with persistent sessions
• Application Launcher: Launch desktop applications seamlessly

🖥️ Terminal Integration

• x: <command> Syntax: Execute commands directly with x: ls -la, x: htop, etc.
• Persistent Sessions: Interactive terminals that stay active across toggles
• Session Management: Real-time counter showing running terminal count
• Multi-Session Support: Run multiple terminals simultaneously

🎨 Modern UI/UX

• Material Design 3: Google's latest design system with dynamic theming
• Tron-Style Accents: Electric blue highlights for terminal and AI elements
• Responsive Interface: Smooth animations and keyboard-driven navigation
• Dark Theme: Optimized for low-light coding sessions

🤖 AI Integration (Coming Soon)

• Natural Language Queries: Ask AI questions directly from the search bar
• Context-Aware Responses: AI understands your current directory and workflow
• Command Suggestions: Get help with complex terminal operations

🚀 Quick Start

Prerequisites

• Linux: Fedora, Ubuntu, or any modern distribution
• Go: Version 1.20 or later
• Node.js: Version 16+ with npm
• Wails v2: go install github.com/wailsapp/wails/v2/cmd/wails@latest

Installation

1. Clone the repository:

   git clone https://github.com/clmurray/xmd.git
   cd xmd/desktop

2. Install dependencies:

   wails build

3. Run XMD:

   ./build/bin/xmd-desktop

GNOME Integration (Recommended)

For the best experience on GNOME:

1. Open Settings → Keyboard → View and Customize Shortcuts
2. Add a Custom Shortcut:
   • Name: XMD Terminal Navigator
   • Command: /path/to/xmd-desktop --toggle
   • Shortcut: Super+Space (or your preference)

📖 Usage Guide

Basic Navigation

• Open XMD: Press your configured hotkey (default: Ctrl+Space)
• Search: Start typing to find apps, files, or commands
• Select: Use arrow keys or mouse, press Enter to execute
• Close: Press Esc or click outside the window

Terminal Commands

• Direct Execution: Type x: ls -la and press Enter
• Interactive Sessions: Commands like x: python3 or x: htop remain interactive
• Session Tracking: See running terminal count in the search window
• Multi-Tasking: Launch multiple terminals and switch between them

Search Types

• Applications: firefox, code, gimp - Launch desktop applications
• Commands: x: git status, x: docker ps - Execute in terminal
• Files: /home/user/project - Navigate to directories
• AI Queries: ask how to use git rebase - Get AI assistance (coming soon)

Keyboard Shortcuts

Key	Action
Ctrl+Space	Toggle XMD window
↑ ↓	Navigate results
Enter	Execute selected item
Esc	Close window
Tab	Cycle through UI elements

🏗️ Architecture

See docs/ARCHITECTURE.md for detailed technical documentation.

High-Level Overview

┌─────────────────────────────────────────────────────────┐
│                    XMD Desktop                          │
├─────────────────────────────────────────────────────────┤
│  Frontend (Svelte + Material Design 3)                 │
│  ├── SpotlightWindow (Main UI)                         │
│  ├── CommandInput (Search & Command Entry)             │
│  ├── ResultsList (Search Results Display)              │
│  └── TerminalView (Interactive Terminal)               │
├─────────────────────────────────────────────────────────┤
│  Backend (Go + Wails)                                  │
│  ├── App (Main Application Logic)                      │
│  ├── Terminal Manager (PTY Session Handling)           │
│  ├── Search Engine (Application & File Indexing)       │
│  ├── AI Client (OpenAI Integration)                    │
│  └── Hotkey Handler (Global Keyboard Shortcuts)        │
├─────────────────────────────────────────────────────────┤
│  System Integration                                    │
│  ├── Desktop Files (.desktop parsing)                  │
│  ├── PTY/Shell Integration                             │
│  ├── IPC (Single Instance Management)                  │
│  └── Platform-Specific Hotkeys                        │
└─────────────────────────────────────────────────────────┘

🛠️ Development

Project Structure

xmd/desktop/
├── app.go                 # Main application logic
├── main.go               # Application entry point
├── wails.json            # Wails configuration
├── frontend/             # Svelte frontend
│   ├── src/
│   │   ├── components/   # UI components
│   │   ├── styles/       # Material Design 3 styles
│   │   └── App.svelte    # Root component
│   └── package.json      # Frontend dependencies
├── pkg/                  # Go packages
│   ├── terminal/         # Terminal session management
│   ├── search/           # Search and indexing
│   └── ai/              # AI integration
├── internal/             # Internal packages
│   └── hotkeys/         # Global hotkey handling
└── docs/                # Documentation

Development Commands

XMD uses a comprehensive Makefile build system for all development tasks:

# Show all available commands
make help

# Development
make dev           # Development server with hot reload
make dev-frontend  # Frontend development server only
make dev-debug     # Development server with debug logging

# Building
make build         # Build complete application
make build-wails   # Build using Wails build system
make build-all     # Clean, test, and build everything
make build-release # Build optimized release version

# Cross-platform builds
make build-linux   # Build for Linux
make build-darwin  # Build for macOS  
make build-windows # Build for Windows
make build-multiplatform # Build for all platforms

# Testing
make test          # Run all tests
make test-go       # Run Go tests only
make test-frontend # Run frontend tests only
make test-go-coverage # Run Go tests with coverage

# Code quality
make fmt           # Format all code
make lint          # Run all linters
make check         # Format, lint, and test

# Dependencies
make deps          # Install all dependencies
make deps-update   # Update all dependencies

# Installation
make install       # Install to system (/usr/local/bin)
make install-user  # Install to user directory (~/.local/bin)

# Environment
make setup         # Set up development environment
make doctor        # Check environment health

Code Style & Standards

• Go: Follow standard Go conventions, use gofmt
• Svelte: TypeScript-first, reactive patterns
• CSS: Material Design 3 tokens, utility-first approach
• Git: Conventional commits with emoji prefixes

🎨 Customization

Theming

XMD uses Material Design 3 with customizable color schemes:

• Primary Colors: Purple-based palette (customizable)
• Tron Accents: Electric blue for terminal/AI elements
• Dark Theme: Optimized for developer workflows
• Typography: Roboto for UI, JetBrains Mono for terminal

Configuration

Configuration is managed through:

• Wails Config: wails.json for build settings
• Environment Variables: Runtime configuration
• CSS Variables: Theme customization in styles/md3-tokens.css

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Areas for Contribution

• AI Integration: Enhance OpenAI client and context awareness
• Platform Support: macOS and Windows compatibility
• Terminal Features: Advanced PTY features, session persistence
• UI/UX: Animation improvements, accessibility features
• Performance: Search optimization, memory management

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Wails: Fantastic Go + Web framework
• Material Design 3: Google's design system
• Svelte: Reactive UI framework
• PTY Library: Terminal session handling
• Contributors: Thanks to all who have contributed to this project

🔗 Links

• Project Repository: GitHub
• Bug Reports: Issues
• Feature Requests: Discussions
• Documentation: Wiki

---

Built with ❤️ by developers, for developers

Making terminal navigation beautiful and efficient