selamta

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 11 Open GitHub ↗

Display proverbs on macOS

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Selamta

A delightful macOS utility that displays random Amharic proverbs from a collection of 1,440+ traditional Ethiopian sayings. Perfect for staying connected to Ethiopian culture while you work.

![macOS](https://img.shields.io/badge/macOS-10.15+-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)
![Bash](https://img.shields.io/badge/bash-5.0+-orange.svg)

</div>

## ✨ Features

🖥️ **Terminal Display** - Beautiful colored proverb output  
🔔 **macOS Notifications** - Pop-up notifications with Ethiopian proverbs  
🔒 **Lock Screen Messages** - See wisdom when you lock your Mac  
⏰ **Automatic Updates** - New proverb every 15 minutes (customizable)  
🎯 **1,440+ Proverbs** - Rich collection of traditional Ethiopian sayings  
⚙️ **Highly Configurable** - Sound, frequency, and display options

## 🎬 Quick Demo

```bash
# Display a random proverb
$ selamta
የሚያልፈው ጊዜ አይመለስም።
```

## 📦 Installation

### Prerequisites

- macOS 10.15 (Catalina) or later
- Admin/sudo access

### Install Steps

1. **Clone the repository**
```bash
git clone https://github.com/HenokB/selamta.git
cd selamta
```

2. **Run the installer**
```bash
sudo ./install.sh
```

3. **Done!** The proverb daemon is now running. 🎉

### What Gets Installed

- `/usr/local/bin/selamta` - Main script
- `/usr/local/share/selamta/amharic_cleaned.csv` - Proverb database
- `/Library/LaunchDaemons/com.ethiopia.selamta.plist` - Auto-run configuration

## 🚀 Usage

### Basic Commands

```bash
# Display a random proverb
selamta

# Show help and all options
selamta --help

# Terminal-only mode (no notifications)
selamta -t

# Enable sound notification
selamta -s

# Disable lock screen message
selamta --no-lock
```

### Notification Setup

To receive notification pop-ups:

1. **Run the script once** to trigger macOS permission prompt:
   ```bash
   selamta
   ```

2. **Allow notifications** when prompted

3. **Or manually enable in System Settings**:
   - Open **System Settings** (or **System Preferences**)
   - Go to **Notifications**
   - Find **"Terminal"** or **"Script Editor"** in the list
   - Enable **"Allow Notifications"**

> On Linux, the script falls back to `notify-send`. Make sure `libnotify` is installed and desktop notifications are enabled for your session.

### Lock Screen Setup

To display proverbs on your lock screen:

1. **Grant Full Disk Access** (macOS Catalina+):
   - Open **System Preferences** → **Security & Privacy** → **Privacy**
   - Select **Full Disk Access** from the sidebar
   - Click the 🔒 lock and authenticate
   - Click **+** and add `/usr/local/bin/selamta`

2. **Test it**: Lock your screen (`⌘ + ^ + Q`)
3. **See the proverb** displayed above the login field! ✨

## ⚙️ Configuration

### Change Update Frequency

Edit the daemon configuration:

```bash
sudo nano /Library/LaunchDaemons/com.ethiopia.selamta.plist
```

Change the interval (in seconds):
```xml
<key>StartInterval</key>
<integer>900</integer>  
```

Reload the daemon:
```bash
sudo launchctl unload /Library/LaunchDaemons/com.ethiopia.selamta.plist
sudo launchctl load /Library/LaunchDaemons/com.ethiopia.selamta.plist
```

### Enable/Disable Features

Edit environment variables in the plist file:

```xml
<key>ENABLE_NOTIFICATION</key>
<string>1</string>

<key>ENABLE_LOCK_SCREEN</key>
<string>1</string>

<key>ENABLE_SOUND</key>
<string>0</string>  
```

## 📊 Monitoring

### View Logs

```bash
# See proverb output (daemon logs)
tail -f /var/log/selamta_output.log

# See any errors (daemon logs)
tail -f /var/log/selamta_error.log

# View activity log (user logs)
tail -f ~/Library/Logs/selamta.log
```

### Check Daemon Status

```bash
# Check if running
sudo launchctl list | grep selamta

# Should show: com.ethiopia.selamta
```

### View Current Lock Screen Message

```bash
sudo defaults read /Library/Preferences/com.apple.loginwindow LoginwindowText
```

## 🗑️ Uninstall

```bash
cd /path/to/selamta
sudo ./uninstall.sh
```

This will remove all installed files, stop the daemon, and clear the lock screen message.

## 🛠️ Troubleshooting

<details>
<summary><b>Lock screen message not showing?</b></summary>

- Ensure Full Disk Access is granted (see Lock Screen Setup above)
- Try running manually: `sudo selamta`
- Check error log: `tail -f /var/log/selamta_error.log`
- Restart your Mac if needed
</details>

<details>
<summary><b>Notifications not appearing?</b></summary>

**Check notification permissions:**

1. Go to **System Settings** → **Notifications**
2. Look for **"Terminal"**, **"Script Editor"**, or **"osascript"**
3. Enable **"Allow Notifications"** for each

**Test manually:**
```bash
# This should show a notification
osascript -e 'display notification "Test notification" with title "Testing"'
# Linux fallback
notify-send "Testing" "Test notification"
```

**If daemon notifications don't work:**
- Wait for the next scheduled run (every 15 min)
- Check `/var/log/selamta_error.log` for errors
- Make sure the daemon is running: `sudo launchctl list | grep selamta`

**Still not working?**
- Run: `selamta` and approve any permission prompts
- Restart your Mac to refresh notification permissions
</details>

<details>
<summary><b>Daemon not running?</b></summary>

```bash
# Check if loaded
sudo launchctl list | grep selamta

# Reload daemon
sudo launchctl unload /Library/LaunchDaemons/com.ethiopia.selamta.plist
sudo launchctl load /Library/LaunchDaemons/com.ethiopia.selamta.plist

# Check logs
tail -f /var/log/selamta_error.log
```
</details>

<details>
<summary><b>Getting "CSV file not found" error?</b></summary>

Make sure the installation completed successfully:
```bash
ls -la /usr/local/share/selamta/amharic_cleaned.csv
```

If missing, reinstall:
```bash
sudo ./install.sh
```
</details>

## 📁 Project Structure

```
selamta/
├── selamta                    # Main script
├── amharic_cleaned.csv        # Database of 1,440+ proverbs
├── com.ethiopia.selamta.plist # LaunchDaemon configuration
├── install.sh                 # Installation script
├── uninstall.sh               # Uninstallation script
├── README.md                  # This file
└── LICENSE                    # MIT License
```

## 📝 Proverb Format

The `amharic_cleaned.csv` file contains one proverb per line in UTF-8 format:

```
እህል ያለ ውሀ ንጉስ ያለድሀ ።
ከሰነፍ ገበሬ ማሳ፥ ሞፈር ይቆረጣል።
...
```

To add your own proverbs, simply add new lines to this file!

## 📜 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Thanks to [dyacob](https://github.com/dyacob) for providing additional proverb data, sourced from [GeezOrg](https://github.com/geezorg/ebooks/tree/master/amharic/poetry/Miscellaneous/src).
- Some dataset entries are also from [ProverbEval](https://aclanthology.org/2025.findings-naacl.350v1.pdf).
- Shout-out to [nebiyuelias1](https://github.com/nebiyuelias1) for highlighting the `notify-send` fallback for Arch/Linux.

selamta

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

selamta

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README