---
title: Plugins
---

CProof supports plugins written in Python and C. The CProof-Plugins project includes both official plugins maintained by the CProof team and community-contributed plugins.

The master branch of the plugins repository is in sync with the latest developments on the master branch of CProof. Branching is used to maintain plugins for releases of CProof.

There is a <a href="https://github.com/profanity-im/profanity/issues/749" target="_blank" rel="noopener noreferrer">known issue</a> that C plugins do not currently work on Cygwin.

To install a Python plugin:

```bash
/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 _~/.local/share/profanity/plugins/_

To install a C plugin:

```bash
/plugins install ~/projects-git/profanity-plugins/pid/pid.so
```

See the [/plugins](/command-reference#plugins) command for more information on installing and enabling/disabling plugins.

If a plugin registers it's own commands, the usual [/help](/command-reference#help) command can be used to find out more information:

```bash
/help say
```

## Featured Plugins

This section list some of the plugins currently available.

|                                                                                                                                                                                | Plugin                                                                                                                                                                                                                                              | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/master/stable/ascii.py" target="_blank" rel="noopener noreferrer"><code>ascii.py</code></a>                     | Convert text to ascii art text and send to the current recipient or room.                                                                                                                                                                           |
| <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/master/stable/browser.py" target="_blank" rel="noopener noreferrer"><code>browser.py</code></a>                 | Open received links in the system default browser.                                                                                                                                                                                                  |
| <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/master/stable/clients.py" target="_blank" rel="noopener noreferrer"><code>clients.py</code></a>                 | Show client software used by each occupant in the current chat room, using <a href="https://xmpp.org/extensions/xep-0092.html" target="_blank" rel="noopener noreferrer">xep-0092 Software Version</a>.                                             |
| <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/master/stable/imgur.py" target="_blank" rel="noopener noreferrer"><code>imgur.py</code></a>                     | Send a local image file or a screenshot to a recipient or chat room using imgur.com.                                                                                                                                                                |
| <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/master/stable/paste.py" target="_blank" rel="noopener noreferrer"><code>paste.py</code></a>                     | Send the contents of the clipboard to the current recipient or room.                                                                                                                                                                                |
| <a href="https://github.com/Neo-Oli/profanity-termux-notification" target="_blank" rel="noopener noreferrer"><code>termuxnotify.py</code></a>                                  | Notifications for Termux on Android.<br> See also <a href="https://github.com/Neo-Oli/profanity-notifycmd" target="_blank" rel="noopener noreferrer"><code>notifycmd.py</code></a> for a generic version to run any system command on new messages. |
| <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/master/stable/presence_notify.py" target="_blank" rel="noopener noreferrer"><code>presence_notify.py</code></a> | Configure desktop notifications for presence updates from contacts.                                                                                                                                                                                 |
| <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/master/stable/say.py" target="_blank" rel="noopener noreferrer"><code>say.py</code></a>                         | Read out loud messages from recipients or in chat rooms.                                                                                                                                                                                            |
| <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/master/stable/sounds.py" target="_blank" rel="noopener noreferrer"><code>sounds.py</code></a>                   | Play sounds when messages received.                                                                                                                                                                                                                 |
| <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/master/stable/syscmd.py" target="_blank" rel="noopener noreferrer"><code>syscmd.py</code></a>                   | Display the result shell commands in a new window.<br> Send results of shell commands to recipients or chat rooms.                                                                                                                                  |
| <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/master/stable/wikipedia-prof.py" target="_blank" rel="noopener noreferrer"><code>wikipedia-prof.py</code></a>   | Search wikipedia and show search results, pages, links etc in a new window.                                                                                                                                                                         |

## Developing Plugins

CProof provides an API for plugins to access various functionality. Plugins may also implement 'hooks' that CProof will call on specific events.

### Python

Python plugins need to import the _prof_ module to access the API.

CProof may be compiled against Python 2 or Python 3, so plugins should be able to work with both, the <a href="https://pypi.org/project/future/" target="_blank" rel="noopener noreferrer">future</a> library can be used in most cases.

Full documentation of the _prof_ module and the hooks a plugin may implement can be found at:

[Python API documentation](/python-api-docs)


### C

C plugins need to include the _profapi.h_ header to access the API, and must be linked against _libprofanity_ using the linker flag _-lprofanity_.

C plugins should include a _Makefile_ to build a shared library (a _.so_ file) which is the file CProof will load.

Full documentation of the _profapi.h_ header and the hooks a plugin may implement can be found at:

[C API documentation](/c-api-docs)

### Themes and Settings

Plugins may make use of themes and settings by accessing the following files:

```plaintext
~/.local/share/profanity/plugin_themes
~/.local/share/profanity/plugin_settings
```

Example theme properties for <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/0.5.1/stable/syscmd.py" target="_blank" rel="noopener noreferrer">syscmd.py</a>:

```ini
[system]
command=cyan
result=green
```

Example settings for <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/0.5.1/stable/say.py" target="_blank" rel="noopener noreferrer">say.py</a>:

```ini
[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.

### Contributing Plugins

Submit a pull request to the <a href="https://git.jabber.space/devs/profanity-plugins" target="_blank" rel="noopener noreferrer">CProof-plugins</a> project.

If the current API doesn't have what you need, raise an issue at the <a href="https://git.jabber.space/devs/profanity" target="_blank" rel="noopener noreferrer">CProof</a> repository.