The Lounge Plugin: Aliases

A The Lounge plugin that allows users to create command aliases. Each user has their own separate configuration file, so aliases are private to each user.

This plugin was originally based on thelounge-plugin-shortcuts, but since that plugin lacked user-awareness, it was rewritten with additional features.

Features

• User-specific aliases: Each user has their own separate set of aliases
• Placeholder support: Use placeholders in your commands for dynamic content
• Simple management: Easy-to-use commands for adding, removing, and listing aliases
• Persistent storage: Aliases are saved per user and restored on restart

Installation

git clone https://github.com/mhajder/thelounge-plugin-aliases.git
thelounge install file:./thelounge-plugin-aliases/

Usage

Adding Aliases

Create a new alias with the /alias add command:

/alias add <name> <command>

Examples:

/alias add hello /msg #general Hello everyone!
/alias add k /kick {0} {1}
/alias add myip /whois {currentChannel}

Removing Aliases

Remove an existing alias:

/alias remove <name>
/alias rm <name>

Example:

/alias remove hello

Listing Aliases

View all your aliases:

/alias list
/alias ls

Help

Show usage information:

/alias help

Placeholders

You can use placeholders in your alias commands:

• {args} - All arguments passed to the alias
• {0}, {1}, {2}, etc. - Individual arguments (0-indexed)
• {currentChannel} - The name of the current channel

Examples:

1. Kick with reason: /alias add k /kick {0} {1}

   • Usage: /k username reason for kick
   • Expands to: kick username reason for kick

2. Message with all args: /alias add announce /msg #general {args}

   • Usage: /announce This is my announcement
   • Expands to: msg #general This is my announcement

3. Channel-specific command: /alias add topic /topic {currentChannel} {args}

   • Usage: /topic This is the new topic (in #mychannel)
   • Expands to: topic #mychannel This is the new topic

Configuration

The plugin stores aliases per user in separate files:

• <thelounge-home>/packages/thelounge-plugin-aliases/aliases-<username>.json

Each user's aliases are completely isolated from other users. Users can only manage their own aliases.

Global Aliases

Administrators can set up global aliases that are available to all users by creating an aliases.json file in the plugin's storage directory:

• <thelounge-home>/packages/thelounge-plugin-aliases/aliases.json

Example aliases.json:

[
  {
    "name": "rules",
    "command": "/msg {currentChannel} Please follow the channel rules: 1) Be respectful 2) No spam 3) Stay on topic"
  },
  {
    "name": "welcome",
    "command": "/msg {currentChannel} Welcome {0}! Please read the rules and feel free to ask questions."
  },
  {
    "name": "admin",
    "command": "/msg chanserv op {currentChannel}"
  }
]

Global alias behavior:

• Available to all users automatically
• Cannot be removed by users
• Cannot be overridden by user aliases (users cannot create aliases with the same name)
• Are displayed separately in the alias list with a [global] indicator
• Support all the same placeholders as user aliases
• Take precedence over user aliases when both exist with the same name

Development

Requirements

• Node.js 18.0.0 or higher
• pnpm package manager
• The Lounge 4.3.0 or higher

Testing

The project uses Vitest for testing:

# Run all tests
pnpm test

# Run with coverage
pnpm test:coverage

Code Quality

The project uses ESLint and Prettier for code quality:

# Check linting
pnpm lint

# Fix linting issues
pnpm lint:fix

# Check formatting
pnpm format:check

# Format code
pnpm format

License

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