betterborg

The crust of this fork is the advanced_get plugin, which gives you a unix shell in Telegram, with the ability to exchange files. I’ll update the README when I have the time to document it.

Needs Python 3.7.2+.

Public Instances of Bots

Transcribe!

Chat!

Say!

llm-chat

# Install dash, zsh, tmux, grealpath (GNU realpath, on Linux you could probably use `alias grealpath=realpath`)
# Run in Zsh:
##
borgdir=~/code/betterborg/
# set this the directory containing betterborg
##
function ec {
    #: `ec` should almost always be used instead of `echo`.
    print -r -- "$@"
}

function ecn {
    print -rn -- "$@"
}

function ecerr {
    ec "$@" >&2
}

function gquote {
    ec "${(qq@)@}"
}
alias gq=gquote

tmuxnew () {
    tmux kill-session -t "$1" &> /dev/null
    tmux new -d -s "$@"
}

function realpath2 {
    test -e "$1" && grealpath -e -- "$1" || {
            (( ${+commands[$1]} )) && grealpath -e -- "${commands[$1]}"
        }
    ##
    # -e, --canonicalize-existing: all components of the path must exist
    ##
}
##

tmuxnew betterborg_llm_chat "dash -c 'cd $(gq $borgdir) && borg_session=session_llm_chat borg_plugin_path=llm_chat_plugins borg_brish_count=1 $(gq "$(realpath2 python3)") $(gq $borgdir/stdborg.py)'"

llm-stt

borgdir=~/code/betterborg/
# set this the directory containing betterborg
##
# IMPORTANT: needs the same functions as `llm_chat` defined, copy those function definitions here before running!
##

tmuxnew betterborg_stt "dash -c 'cd $(gq $borgdir) && borg_session=session_stt borg_plugin_path=stt_plugins borg_brish_count=1 $(gq "$(realpath2 python3)") $(gq $borgdir/stdborg.py)'"

reply-chainer

borgdir=~/code/betterborg/
# set this the directory containing betterborg
##
# IMPORTANT: needs the same functions as `llm_chat` defined, copy those function definitions here before running!
##

tmuxnew betterborg_reply_chainer "dash -c 'cd $(gq $borgdir) && borg_session=session_reply_chainer borg_plugin_path=reply_chainer_plugins borg_brish_count=1 $(gq "$(realpath2 python3)") $(gq $borgdir/stdborg.py)'"

uniborg

Pluggable =asyncio= Telegram userbot based on Telethon.

installing

Simply clone the repository and run the main file:

sudo apt-get install -y coreutils fzf zsh python3

mkdir -p ~/code
cd ~/code

git clone 'https://github.com/NightMachinary/betterborg.git'
cd betterborg

pip3 install -r requirements.txt

# Optional: override Telethon API credentials.
export borg_api_id='...'
export borg_api_hash='...'
# =TELEGRAM_API_ID= / =TELEGRAM_API_HASH= also work.

python3 stdborg.py

design

The modular design of the project enhances your Telegram experience through plugins which you can enable or disable on demand.

Each plugin gets the borg, logger and storage magical variables to ease their use. Thus creating a plugin as easy as adding a new file under the plugin directory to do the job:

# stdplugins/myplugin.py
from telethon import events

@borg.on(events.NewMessage(pattern='hi'))
async def handler(event):
    await event.reply('hey')

internals

The core features offered by the custom TelegramClient live under the =uniborg/= directory, with some utilities, enhancements and the core plugin.

history export

stdplugins/history_export.py adds an admin-only .export [number-of-messages=all] command that silently writes a Telegram Desktop-style, text-only result.json for the current chat.

By default exports are saved below ~/tmp/.borg/chat_exports/. Set BORG_HISTORY_EXPORT_DIR to override the root directory. Reactions include available reactor identities. Media files are not downloaded; placeholders and available media metadata are written instead. Progress is printed in the server terminal, and SIGINT during an active export writes a partial export instead of interrupting the process. Collection is newest-first for useful partial exports, while the saved JSON remains oldest-first. See docs/history_export.md.

Codex GPT-5.5

llm_chat can expose openai-codex/gpt-5.5 as an admin-only chat model using the published llm-openai-via-codex package and local Codex OAuth credentials. See docs/codex_gpt55.md.

learning

Check out the already-mentioned plugins directory to learn how to write your own, and consider reading Telethon’s documentation.