Profanity supports plugins written in Python and C. The profanity-plugins project contains various plugins maintained by Profanity's author and other community maintained plugins.
The master branch of the plugins repository is in synch with development in the master branch of Profanity. Branching is used to maintain plugins for releases of Profanity:
There is a known issue that C plugins do not currently work on Cygwin.
To install a Python plugin:
/plugins install ~/projects-git/profanity-plugins/say.py
Any module dependencies for the plugin should be on the Python system path. If a plugin imports modules relative to its location, these modules need to manually be copied to
To install a C plugin:
/plugins install ~/projects-git/profanity-plugins/pid/pid.so
/plugins command for more information on installing and enabling/disabling plugins.
If a plugin registers it's own commands, the usual
/help command can be used to find out more information:
This section list some of the plugins currently available.
||Convert text to ascii art text and send to the current recipient or room.|
||Open received links in the system default browser.|
||Show client software used by each occupant in the current chat room, using xep-0092 Software Version.|
||Send a local image file or a screenshot to a recipient or chat room using imgur.com.|
||Send the contents of the clipboard to the current recipient or room.|
||Notifications for Termux on Android.
||Configure desktop notifications for presence updates from contacts.|
||Read out loud messages from recipients or in chat rooms.|
||Play sounds when messages received.|
||Display the result shell commands in a new window.
Send results of shell commands to recipients or chat rooms.
||Search wikipedia and show search results, pages, links etc in a new window.|
Profanity provides an API for plugins to access various functionality. Plugins may also implement 'hooks' that Profanity will call on specific events.
Python plugins need to import the
prof module to access the API.
Profanity may be compiled against Python 2 or Python 3, so plugins should be able to work with both, the future library can be used in most cases.
Full documentation of the
prof module and the hooks a plugin may implement can be found at:
0.5.1 Python API documentation
C plugins need to include the
profapi.h header to access the API, and must be linked against
libprofanity using the linker flag
C plugins should include a
Makefile to build a shared library (a
.so file) which is the file Profanity will load.
Full documentation of the
profapi.h header and the hooks a plugin may implement can be found at:
0.5.1 C API documentation
Themes and Settings
Plugins may make use of themes and settings by accessing the following files:
Example theme properties for syscmd.py:
[system] command=cyan result=green
Example settings for say.py:
[say] args=-v english -s 120 enabled=active
API functions are available to read and write to the settings and theme files.
Plugins should contain documentation on the available settings and colours, most plugins have a command to manipulate settings.
Submit a pull request to the profanity-plugins project.
If the current API doesn't have what you need, raise an issue at the Profanity repository.