hcclient 1.19.6

A terminal client for connecting to hack.chat

hcclient

A cross-platform terminal client for hack.chat

• Introduction
• Features
• Prerequisites
• Installation
• Usage
• Styling
• LaTeX Simplification
• Configuration
• Notifications
• Updatable Messages
• Hooks
• Contributing

Introduction

"hack.chat is a minimal, distraction-free, accountless, logless, disappearing chat service which is easily deployable as your own service." - hack.chat

hcclient is a configurable and feature-rich cross-platform terminal client for connecting to hack.chat

[!IMPORTANT] This client is written to be compatible with the official live instance. Compatibility with your own self-hosted instance or other alternate instances is not guaranteed.

Features

Some of the features hcclient has to offer:

• Cross-platform: Tested to work on Windows, Linux, macOS and Android. See Prerequisites for more information.
• Suggestions: Starting your message with @ or / will bring up a menu with a list of online users or commands. Cycle through them with arrow keys or continue typing to filter the suggestions even more. Suggestion aggressiveness can be set with --suggest-aggr.
• Markdown: Messages are parsed as markdown, with support for bold, italics, strikethrough, code blocks, backticks, links and spec compliant escaping. See Styling for more information.
• Syntax highlighting: Code blocks in messages are highlighted with user specified languages or language guessing.
• LaTeX simplification: LaTeX expressions are parsed and converted to sympy expressions, which are more readable. See LaTeX Simplification for more information.
• Configuration: Generate and load YAML/JSON configuration files with no editing required. Change configuration options from within the client with commands, modifying behaviour and colors without having to restart. See Configuration for more information.
• Desktop notifications: Receive notifications whenever someone mentions you or sends you a whisper. Android notifications are supported when running on Termux. See Notifications for more information.
• Aliases: Set aliases for messages and phrases you send often, because why wouldn't you?
• Whisper locking: Lock the client with a command to send only whispers, preventing accidental information leaks.
• Ignore list: Message blocking using tripcodes and connection hashes.
• Proxy support: Connect through SOCKS4, SOCKS5 or HTTP proxies. Tested to work with Tor.

Prerequisites

• Python >= 3.10
• Pip
• An xterm-256color terminal emulator that supports ANSI escape sequences

Notification support requires different dependencies on different platforms, see Notifications for more information.

Installation

Cross-platform installation:

# Install the PyPI package
pip install hcclient

# Run hcclient
hcclient --help

For LaTeX support, install hcclient[latex] instead.

On Arch Linux (and most Arch-based distributions), install the AUR package with makepkg or an AUR helper.
This will install an isolated environment with all dependencies in /opt/hcclient.

Alternatively, install the LaTeX enabled AUR package.

Usage

$ hcclient --help

usage: hcclient [-h] [-v] [--gen-config] [--defaults] [--colors]
                [--themes] [-c CHANNEL] [-n NICKNAME] [-p PASSWORD]
                [-w ADDRESS] [-l FILE] [--no-config] [--no-parse]
                [--clear] [--is-mod] [--no-unicode]
                [--highlight-theme THEME] [--no-markdown] [--no-notify]
                [--prompt-string STRING] [--timestamp-format FORMAT]
                [--suggest-aggr 0-3] [--proxy TYPE:HOST:PORT]

terminal client for hack.chat

commands:
  -h, --help                        display this help message
  -v, --version                     display version information
  --gen-config                      generate config file
  --defaults                        display default config values
  --colors                          display valid color values
  --themes                          display valid highlight themes

required arguments:
  -c CHANNEL, --channel CHANNEL     set channel to join
  -n NICKNAME, --nickname NICKNAME  set nickname to use

optional arguments:
  -p PASSWORD, --password PASSWORD  specify tripcode password
  -w ADDRESS, --websocket ADDRESS   specify alternate websocket
  -l FILE, --load-config FILE       specify config file to load
  --no-config                       ignore global config file
  --no-hooks                        ignore global hooks
  --no-parse                        log received packets as JSON
  --clear                           clear console before joining
  --is-mod                          enable moderator commands
  --no-unicode                      disable unicode UI elements
  --sheriff-badges                  show stars beside mods/admins
  --highlight-theme THEME           set highlight theme
  --no-markdown                     disable markdown formatting
  --no-linkify                      disable linkifying of urls
  --backticks-bg 0-255              set backticks background color
  --latex                           enable LaTeX simplifying
  --no-notify                       disable desktop notifications
  --prompt-string STRING            set custom prompt string
  --timestamp-format FORMAT         set timestamp format
  --suggest-aggr 0-3                set suggestion aggressiveness
  --proxy TYPE:HOST:PORT            specify proxy to use
  --ssl-no-verify                   disable SSL cert verification

Styling

The default color scheme can be overidden with a configuration file. See Configuration for more information.
A list of valid colors can be viewed with --colors.

Syntax highlighting and markdown are enabled by default. They can be disabled with --no-markdown or with the no_markdown option.
The markdown implementation supports:

• Bold: **bold**
• Italics: *italics*
• Bold-italics: ***bold-italics***
• Strikethrough: ~~strikethrough~~
• Code blocks: (With syntax highlighting and language guessing)

  ```<lang>
  <code>
  ```
  

• Backticks: `backticks`
• Links:
  • [link](https://example.com)
  • ![image](https://example.com/image.png
  • <https://example.com>
  • <mailto:[e-mail]
  • https://example.com
  • example.com
• Escaping: \*escaped* (Spec compliant)

Highlight themes can be listed with --themes and set with --highlight-theme or with the highlight_theme option
The default theme is monokai.

LaTeX Simplification

LaTeX simplification is disabled by default. It can be enabled with --latex or with the latex option.
When enabled, LaTeX expressions will be parsed and converted to sympy expressions, which are more readable.

Expressions must be enclosed in $ or $$ for inline and block expressions respectively.

For example, the following LaTeX expression:

$\frac{1}{2}$

Will be simplified and displayed as:

|latex: 1/2|

Conversion is done using latex2sympy2.
Not all LaTeX expressions are supported of course, but it's good enough for most use cases.

Configuration

A configuration file can be generated with the provided arguments using --gen-config and loaded using --load-config. For example:

hcclient --gen-config

The above command will create config.yml with default options in the working directory, which can then be loaded with:

hcclient -c mychannel -n mynick --load-config <path_to_config.yml>

Generated configuration files are in YAML format by default.
Alternatively, a JSON configuration file can be generated by running --gen-config again in the same directory. Both formats can be loaded the same way.

Override defaults when generating the configuration file by specifying options:

hcclient --no-notify --proxy socks5:127.0.0.1:9050 --gen-config

hcclient searches for config.yml or config.json in the following directories by default:

• Windows:  %APPDATA%/hcclient
• Other platforms:  $HOME/.config/hcclient

[!NOTE] The configuration file does not affect channel and nickname, which have to be specified as flags every time.

You can also configure hcclient while it's running, without having to restart it. For example:

> /configset no_notify true

The changes will be applied live and lost once you exit the client, but you can save it to the configuration file with /save
Configuration options can be listed with /configdump

Notifications

Desktop notifications are enabled by default. They can be disabled with --no-notify or with the no_notify option

hcclient doesn't have a built-in audio file for sound alerts, so you'll have to provide your own.
Place a wave file named tone.wav in the default config directory and it will be played when a notification is sent.

Default config directory location:

• Windows:  %APPDATA%/hcclient
• Other platforms:  $HOME/.config/hcclient

On Linux, libnotify and aplay are required for notifications to work.

On Android, notifications are supported when running on Termux.
Install the Termux:API app and termux-api package and notifications will just work.

Updatable Messages

hack.chat has support for updatable messages, which allows editing previously sent messages on the official web client. This is usually used by bots to display streamed/delayed output.
Since hcclient is a terminal client, editing messages that have been previously printed isn't possible.

However, updateMessage events are still handled, just differently.

When an updatable message is received, it will be printed as per normal but with an unique identifier. For example:

23:06|jEuh/s| [⧗ 84263] [user] hi

Here, 84263 is the message identifier.

As the sender continues to update and edit the message, hcclient will track the changes in memory.
Once the sender sends the complete status, the message will be printed again with the same identifier and all changes applied:

23:06|jEuh/s| [⧗ 84263] [user] hi
...
...
...
23:08|jEuh/s| [✓ 84263] [user] hi guys!

It's displayed as a new message, but it's actually the previous message, edited.

If no complete status is received in 3 minutes, the message will expire. All changes applied so far will be printed like normal, but with the ✗ icon instead.

[!NOTE] If no_unicode is enabled, the ⧗, ✓ and ✗ icons will be replaced with Updatable.ID:, Completed.ID: and Expired.ID: respectively.

Hooks

You can tweak hcclient's behaviour by placing hooks in the default hooks directory:

• Windows:  %APPDATA%/hcclient/hooks
• Other platforms:  $HOME/.config/hcclient/hooks

Hooks are python scripts that are run on startup.

A hook should have a HookInfo class and a hook() function.
The HookInfo class should have the following attributes:

• name: The name of the hook.
• description: (Optional) A description of the hook.
• version: The version of the hook, must be a valid version string.
• compat: (Optional) A version specifier for the client version the hook is compatible with. See the Packaging User Guide for more information.
• Any other attributes you want to add, hcclient will ignore them.

The hook() function should take a single argument, which is the client instance.
You can modify, add or remove the instance's attributes and methods to change its behaviour.

Example hooks can be found here.

[!WARNING] Hook support is experimental. hcclient is not stable and the API is subject to change, hooks may not work after an update.

Contributing

All contributions are welcome! :D

Please read CONTRIBUTING.md before submitting a pull request.

Credits to everyone here