https://github.com/rexolt/spoty
https://github.com/rexolt/spoty
Last synced: 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/rexolt/spoty
- Owner: Rexolt
- License: mit
- Created: 2025-07-06T15:26:10.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2026-04-25T17:56:16.000Z (2 months ago)
- Last Synced: 2026-04-25T19:11:44.108Z (2 months ago)
- Language: JavaScript
- Size: 352 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ✨ Spoty
**A modern, lightning-fast Spotlight-like launcher for Windows, macOS, and Linux**
[](https://github.com/Rexolt/spoty/releases/latest)
[](LICENSE)
[](#installation)
[](https://www.electronjs.org/)
*Search apps, files, bookmarks — or chat with AI. All from one shortcut.*
---
## 🚀 Features
### 🔍 Search & Launch
- **App launcher** — Fuzzy search across installed apps
- **File search** — Desktop, Documents, Downloads
- **Browser bookmarks** — Chrome, Brave, Edge, Chromium
- **System commands** — `lock`, `sleep`, `shutdown`, `restart`
- **Web search** — `g query` or `? query`
- **Clipboard history** — type `clip`
### 🧠 AI & Tools
- **AI Mode** — OpenAI, Google Gemini, or Ollama (local)
- **Multi-turn chat** — Context-aware conversations
- **Chat history** — Save & browse past conversations
- **Calculator** — `2+2`, `(5*3)+10`
- **Unit converter** — `5 km to mi`, `100 usd to eur`
- **Weather** — `weather budapest`
### 🎨 Customization
- **5 Themes** — Dark, Light, Ocean, Forest, Midnight (OLED)
- **Custom aliases** — Multi-action shortcuts in JSON
- **Bilingual** — Hungarian 🇭🇺 & English 🇬🇧
- **Configurable hotkey** — Auto-fallback if the preferred key is taken
---
## 📦 Installation
### Linux
AppImage (universal)
```bash
chmod +x Spoty-x64.AppImage
./Spoty-x64.AppImage
```
Debian / Ubuntu (.deb)
```bash
sudo dpkg -i Spoty-x64.deb
```
Fedora / RHEL (.rpm)
```bash
sudo rpm -i Spoty-x64.rpm
```
Arch Linux (.pacman)
```bash
sudo pacman -U Spoty-x64.pacman
```
### macOS
Download the `.dmg` from [**Releases**](https://github.com/Rexolt/spoty/releases/latest), open it and drag Spoty to Applications.
> [!NOTE]
> The app is unsigned. On first launch: **right-click → Open → Open**.
### Windows
Download the **Installer** (`.exe`) or the **Portable** version from [**Releases**](https://github.com/Rexolt/spoty/releases/latest).
---
## ⌨️ Keyboard Shortcuts
| Shortcut | Action |
|---|---|
| `Alt+Space` | Toggle Spoty *(configurable)* |
| `↑` `↓` | Navigate results |
| `Enter` | Open selected item |
| `Shift+Enter` | Open containing folder |
| `Tab` / `Shift+Tab` | Cycle through results |
| `Ctrl+1`–`9` | Quick-select result |
| `Ctrl+N` | New AI conversation |
| `Ctrl+,` | Open / close Settings |
| `Esc` | Clear search / hide window |
### Search Prefixes
| Prefix | Function | Example |
|---|---|---|
| `g ` or `? ` | Web search | `g electron docs` |
| `>` | Run terminal command | `>htop` |
| `weather ` | Weather lookup | `weather london` |
| `clip` | Clipboard history | `clip` |
| *(number)* | Calculator | `(5+3)*2` |
| *(conversion)* | Unit / currency converter | `10 usd to eur` |
---
## 🛠️ Build from Source
**Prerequisites:** [Node.js](https://nodejs.org/) ≥ 18, npm ≥ 9
```bash
# Clone & install
git clone https://github.com/Rexolt/spoty.git
cd spoty
npm install
# Run in development
npm start
# Build for your platform
npm run build:linux # AppImage, deb, rpm, pacman
npm run build:mac # dmg, zip (unsigned)
npm run build:win # NSIS installer, portable
npm run build:all # All platforms
```
Output goes to `dist/`.
---
## ⚙️ Configuration
Settings are accessible via the **gear icon** in the app, or by editing the config file directly:
| Platform | Path |
|---|---|
| Linux | `~/.config/spoty/config.json` |
| macOS | `~/.config/spoty/config.json` |
| Windows | `%APPDATA%\spoty\config.json` |
### AI Setup
| Provider | What you need |
|---|---|
| **OpenAI** | API key from [platform.openai.com](https://platform.openai.com/) |
| **Google Gemini** | API key from [aistudio.google.com](https://aistudio.google.com/) |
| **Ollama** | Local install from [ollama.com](https://ollama.com/) — no key needed |
---
## 🏗️ Architecture
```
spoty/
├── main.js # Electron main process (search, AI, IPC)
├── preload.js # Secure IPC bridge with channel whitelist
├── src/
│ ├── index.html # App shell with CSP
│ ├── renderer.js # UI logic, keyboard navigation, i18n
│ └── styles.css # Theming, animations, frosted glass
├── build/icons/ # App icons (ico, png)
└── package.json # Config, scripts, electron-builder
```
---
## 🔒 Security
- **Context Isolation** — Renderer has no access to Node.js
- **Sandbox** — Renderer runs in a sandboxed process
- **IPC Whitelist** — Only known channels are allowed in preload
- **CSP** — Content Security Policy blocks inline scripts
- **Safe Math** — Calculator uses a custom parser, not `eval()`
- **URL Validation** — `shell.openExternal` only allows `http(s)://`
- **Ollama Guard** — SSRF protection: only `localhost` is allowed
---
## 📄 License
[MIT](LICENSE) — Made with ❤️ by [Rexolt](https://github.com/Rexolt)