Elephant - cuz it's phat - is a powerful data provider service and backend for building custom application launchers and desktop utilities. It provides various data sources and actions through a plugin-based architecture, communicating via Unix sockets and Protocol Buffers.

Elephant acts as a unified backend service that aggregates data from various sources (desktop applications, files, clipboard history, etc.) and provides a consistent interface for frontend applications like custom launchers, productivity tools, or desktop widgets.

• 🚀 Desktop Applications

  • Auto-detection of uwsm or app2unit
  • Application launch history
  • Desktop entry parsing

• 📁 Files

  • File preview (text/image)
  • File operations: open, copy path, copy content
  • Directory navigation

• 📋 Clipboard

  • Text and image clipboard history
  • Clipboard content management

• ⚡ Runner

  • Command execution from explicit lists
  • $PATH scanning for executables

• 🔣 Symbols/Emojis

  • Multi-locale emoji and symbol support
  • Unicode character database

• 🧮 Calculator/Unit Conversion

  • Mathematical calculations with history
  • Unit conversion using qalc

• 📋 Custom Menus

  • User-defined menu creation
  • Custom action definitions

• 📊 Provider List

  • Dynamic listing of all loaded providers and menus

• 🌐 Websearch

  • ... define custom search engines

yay -S elephant

# Providers, f.e.

yay -S elephant-desktopapplications

# Clone the repository
git clone https://github.com/abenz1267/elephant
cd elephant

# Build and install the main binary
cd cmd
go install elephant.go

# Create configuration directories
mkdir -p ~/.config/elephant/providers

# Build and install a provider (example: desktop applications)
cd ../internal/providers/desktopapplications
go build -buildmode=plugin
cp desktopapplications.so ~/.config/elephant/providers/

# Start elephant with default configuration
elephant

# Start with debug logging
elephant --debug

# Use custom configuration directory
elephant --config /path/to/config

Elephant includes a built-in client for testing and basic operations:

# Query provider (providers;query;limit;exactsearch)
elephant query "files;documents;10;false"

# activate item (qid;provider;identifier;action;query)
elephant activate "1;files;<identifier>;open;"

# List all installed providers
elephant listproviders

# Open a custom menu, requires a subscribed frontend.
elephant menu "screenshots"

# Show version
elephant version

# Generate configuration documentation
elephant generatedoc

Elephant uses a configuration directory structure:

~/.config/elephant/
├── elephant.toml        # Main configuration
├── .env                 # Environment variables
└── providers/           # Provider plugins
    ├── files.so
    ├── desktopapplications.so
    └── ...

Elephant uses Unix domain sockets for IPC and Protocol Buffers for message serialization. The main message types are:

• Query Messages: Request data from providers
• Activation Messages: Execute actions
• Menu Messages: Request custom menu data
• Subscribe Messages: Listen for real-time updates

To integrate with Elephant, your application needs to:

1. Connect to the Unix socket (typically at /tmp/elephant.sock)
2. Send Protocol Buffer messages
3. Handle responses and updates

See the pkg/pb/ directory for Protocol Buffer definitions.

elephant/
├── cmd/                 # Main application entry point
├── internal/
│   ├── comm/           # Communication layer (Unix sockets, protobuf)
│   ├── common/         # Shared utilities and configuration
│   ├── providers/      # Data provider plugins
│   └── util/          # Helper utilities
├── pkg/pb/            # Protocol Buffer definitions
└── flake.nix          # Nix development environment

Providers are Go plugins that implement the provider interface. See existing providers in internal/providers/ for examples.

# Clone repository
git clone https://github.com/abenz1267/elephant
cd elephant

# Install dependencies
go mod download

# Build main binary
go build -o elephant cmd/elephant.go

# Run tests
go test ./...

A Nix flake is provided for reproducible development:

nix develop

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Please ensure your code follows Go best practices and includes appropriate documentation.

⚠️ Work in Progress: This project is in active development and the API may change. Use with caution in production environments.

This project is licensed under the GNU General Public License v3.0. See LICENSE for details.

• 💬 Discord Community
• 🐛 Issue Tracker