Skip to main content
Thank you for your interest in contributing to Dracula tmux! This guide will help you get started with contributing code, reporting bugs, suggesting features, and more.

​
Ways to contribute

There are many ways to contribute to Dracula tmux:
  • Report bugs and issues
  • Suggest new features or widgets
  • Improve documentation
  • Submit bug fixes
  • Add new widgets
  • Improve existing widgets
  • Review pull requests
  • Help other users in discussions

​
Getting started

1

Fork the repository

Visit the Dracula tmux GitHub repository and click the “Fork” button to create your own copy.
2

Clone your fork

git clone https://github.com/YOUR-USERNAME/tmux.git
cd tmux
3

Create a branch

git checkout -b feature/your-feature-name
# Or for bug fixes:
git checkout -b fix/bug-description
4

Make your changes

Edit the relevant files, test your changes, and commit them with clear messages.
5

Push and create a pull request

git push origin feature/your-feature-name
Then create a pull request on GitHub.

​
Reporting bugs

Before reporting a bug, please:
  1. Search existing issues to see if it’s already been reported
  2. Test with the latest version to ensure the bug still exists
  3. Create a minimal reproduction to isolate the issue

​
How to submit a bug report

Create a bug report

Use the bug report template on GitHub
Include the following information:
  • Operating system: macOS, Linux (distribution), FreeBSD, etc.
  • OS version: e.g., macOS 14.0, Ubuntu 22.04
  • tmux version: Run tmux -V to check
  • Terminal emulator: iTerm2, Alacritty, GNOME Terminal, etc.
  • What happened: Clear description of the issue
  • What you expected: What should have happened instead
  • Steps to reproduce: Numbered list of steps to trigger the bug
  • Frequency: Does it happen always, sometimes, or rarely?
# Include relevant parts of your .tmux.conf
set -g @plugin 'dracula/tmux'
set -g @dracula-plugins "battery cpu-usage git"
# ... other relevant settings
If the issue is visual, include screenshots showing:
  • The problem
  • Expected vs actual appearance
  • Terminal emulator settings (if relevant)
The more detailed your bug report, the easier it is to diagnose and fix the issue.

​
Suggesting features

We welcome feature suggestions! Before submitting:
  1. Check existing feature requests to avoid duplicates
  2. Consider the scope - does it fit Dracula tmux’s goals?
  3. Think about implementation - how would it work?

​
How to submit a feature request

Request a feature

Use the feature request template on GitHub
Include:
  • Clear description of the feature you’d like
  • Use case explaining why this would be valuable
  • Potential risks or concerns to consider
  • Alternative approaches you’ve considered
  • Examples from other tools (if applicable)

​
Contributing code

​
Code style and guidelines

  • Use bash for scripts
  • Include shebang: #!/usr/bin/env bash
  • Use meaningful variable names
  • Add comments for complex logic
  • Follow existing code style in the project
  • Use consistent indentation (2 spaces)
Widgets should be placed in the scripts/ directory:
scripts/
├── battery.sh          # Widget script
├── cpu_usage.sh        # Another widget
└── your-widget.sh      # Your new widget
Basic widget template:
#!/usr/bin/env bash

# Get options
CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
source $CURRENT_DIR/utils.sh

main()
{
  # Your widget logic here
  echo "Your output"
}

main
Before submitting:
  1. Test on your system: 
    # Reload tmux config
tmux source-file ~/.tmux.conf
  2. Test with different configurations:
    • With and without powerline
    • With different color schemes
    • With minimal and maximal widget lists
  3. Test edge cases:
    • What if data is unavailable?
    • What if commands fail?
    • What if network is down?
  4. Check for errors: 
    # Look for errors in tmux
tmux show-messages
If adding a new widget or feature:
  1. Update CONFIG.md:
    • Add section for your widget
    • Document all configuration options
    • Include usage examples
  2. Update README.md:
    • Add to features list if applicable
    • Update compatibility notes
  3. Include code comments:
    • Explain non-obvious logic
    • Document function parameters
    • Add usage examples

​
Pull request process

When you’re ready to submit your changes:
1

Ensure your code works

  • Test thoroughly on your system
  • Check for shell script errors
  • Verify no existing functionality is broken
2

Commit your changes

Write clear, descriptive commit messages:
# Good commit messages:
git commit -m "Add network-vpn widget with Tailscale support"
git commit -m "Fix battery detection on FreeBSD"
git commit -m "Update git widget to show repository name"

# Avoid vague messages:
# "fix bug", "update", "changes"
3

Push to your fork

git push origin feature/your-feature-name
4

Create pull request

Use the pull request template:
## Issue
Closes #123

## Description of Changes
- Added new network-vpn widget
- Supports standard VPN detection and Tailscale exit nodes
- Works on Linux and macOS

## Testing
Tested on:
- Ubuntu 22.04 with tmux 3.3a
- macOS 14.0 with tmux 3.4

To test:
1. Enable widget: `set -g @dracula-plugins "network-vpn"`
2. Connect to VPN or Tailscale
3. Verify VPN status appears in status bar
Pull requests should reference the issue they’re solving using “Closes #issue-number”.

​
What to expect

After submitting a pull request:
  1. Maintainers will review your code
  2. You may receive feedback or requests for changes
  3. Make requested changes and push updates to your branch
  4. Once approved, a maintainer will merge your PR
Be patient and responsive to feedback. Maintainers are volunteers and may take time to review.

​
Adding new widgets

Creating a new widget is a great way to contribute!

​
Widget development guide

1

Plan your widget

  • Purpose: What information will it display?
  • Data source: Where does the data come from?
  • Dependencies: What commands or tools are required?
  • Platforms: Which OS will it support?
2

Create the script

Create scripts/your-widget.sh:
#!/usr/bin/env bash

CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
source $CURRENT_DIR/utils.sh

main()
{
  # Get custom options
  label=$(get_tmux_option "@dracula-your-widget-label" "Default")
  
  # Get your data
  data=$(your_command_here)
  
  # Handle errors
  if [ -z "$data" ]; then
    echo "N/A"
    return
  fi
  
  # Format and output
  echo "$label $data"
}

main
3

Register the widget

Update scripts/dracula.sh to include your widget in the plugin list.
4

Document it

Add a section to docs/CONFIG.md with the widget description, available options, and example configuration.
5

Test thoroughly

  • Test on multiple platforms if possible
  • Test with missing dependencies
  • Test with various configurations
  • Test error handling

​
Widget best practices

  • Cache data when possible
  • Avoid expensive operations in tight loops
  • Respect the global refresh rate
  • Consider adding widget-specific refresh options
  • Check if required commands exist: command -v cmd
  • Handle missing data gracefully
  • Return meaningful defaults
  • Don’t spam error messages
  • Allow users to customize labels
  • Support Nerd Font icons
  • Provide text-only fallbacks
  • Use sensible defaults
  • Test on Linux and macOS if possible
  • Document platform-specific limitations
  • Use portable commands when available
  • Gracefully handle unsupported platforms

​
Documentation contributions

Improving documentation is valuable! You can:
  • Fix typos and grammar
  • Clarify confusing sections
  • Add missing examples
  • Update outdated information
  • Improve formatting
  • Add troubleshooting tips
Documentation changes follow the same pull request process as code changes.

​
Community guidelines

When participating in the Dracula tmux community:

Be respectful

Treat everyone with respect and kindness. We’re all here to help.

Be constructive

Provide helpful feedback. Criticism should be constructive and actionable.

Be patient

Maintainers are volunteers. Responses may take time.

Be helpful

Help other users when you can. Share your knowledge and experience.

​
Maintainers

Dracula tmux is maintained by: And supported by many awesome contributors.

​
Additional resources

GitHub Repository

Source code and issue tracker

GitHub Discussions

Ask questions and discuss ideas

Discord Community

Chat with the community

Twitter

Follow for updates

​
License

By contributing to Dracula tmux, you agree that your contributions will be licensed under the MIT License.
All contributions are reviewed by maintainers before being merged. This ensures code quality and maintains the project’s standards.
Thank you for contributing to Dracula tmux! Every contribution, no matter how small, helps make the project better for everyone.

Build docs developers (and LLMs) love

Get started for freeTalk to us