elephant

README

Elephant 🐘

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.

Overview

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.

Features

Current Providers

• 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

• Bluetooth

  • basic bluetooth management
  • connect/disconnect
  • trust/untrust
  • pair/remove

• Clipboard

  • Text and image clipboard history
  • Clipboard content management
  • post-edit text content

• 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

• Archlinux Packages

  • list all packages: official and AUR
  • list all explicitly installed packages i:
  • remove / install packages (pacman, yay/paru)

• Todo List

  • add items, mark as active/done, clear done items
  • create items with due times
  • notifications

• Unicodes

  • find unicode symbols

Installation

Installing on Arch

yay -S elephant

# Providers, f.e.

yay -S elephant-desktopapplications

Building from Source

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

# Build and install the main binary
cd cmd/elephant
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/

Usage

Important

It is utterly important that elephant runs in the appropriate environment. Starting a system-level systemd service f.e. will lead to missing environment variables. It needs to run with the users environment.

Starting the Service

On a systemd based system, you can use elephant service enable/disable to manage a service.

The service file will be placed in ~/.config/systemd/user/elephant.service.

Feel free to create your own service file/adjust the one created.

# Start elephant with default configuration
elephant

# Start with debug logging
elephant --debug

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

Command Line Interface

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

Querying Data

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

Activating Items

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

Other Commands

# 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

# Systemd service management
elephant service enable/disable

Configuration

Elephant uses a configuration directory structure:

~/.config/elephant/
├── elephant.toml        # Main configuration
├── .env                 # Environment variables
└── <provider>.toml      # Provider config

API & Integration

Communication Protocol

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

Building Client Applications

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.

Development

Project Structure

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

Creating Custom Providers

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

Building from Source

# 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 ./...

Development Environment

A Nix flake is provided for reproducible development:

nix develop

Contributing

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.

License

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

Support

• 💬 Discord Community
• 🐛 Issue Tracker