[Clone of ~nhanb/mcross] Python/Tk GUI browser for Gemini
96bf9cf2 — Frederick Yin 3 years ago
Restructure README
c5906579 — Frederick Yin 3 years ago
Bump version 0.6.0
19aa47e0 — Frederick Yin 3 years ago
GeminiUrl to str conversion in tab title parsing



You can also use your local clone with git send-email.

This is the repo for my personal flavor of McRoss, forked from ~nhanb/mcross.

Note: I/me/my/mine/myself in the following text refer to the fork maintainer, ~fkfd. "Nhân" refers to the original author, ~nhanb. "We" refers to us both.

McRoss is a minimal and usable gemini:// browser written in python and tkinter, meaning it Just Works (tm) on any self-respecting desktop OS: Linux, Windows, Mac OS, and maybe the BSDs? Never tried one of those.

It currently looks like this with my config file:

See Nhân's blog post for the rationale behind this project.

#Feature checklist

  • [x] back-forward buttons
  • [x] handle redirects
  • [x] non-blocking I/O using curio
  • [x] more visual indicators: waiting cursor, status bar
  • [x] parse gemini's advanced line types
  • [x] render text/* mime types with correct charset
  • [x] handle binary/* mime types
  • [x] configurable document styling
  • [ ] human-friendly distribution
  • [x] TOFU TLS (right now it always accepts self-signed certs)
  • [x] tabs
  • [ ] i18n

#Easy for end users to install

If the words cargo build exists in the installation guide for your G U I application then I'm sorry it's not software made for people to use. — Nhân

I agree. — Frederick


A rendered text/gemini viewport should preserve its original text content. This way once you've read a gemini page on the browser, you already know how to write one. No "View Source" necessary.

#Responsive & pleasant to use

The Castor browser doesn't have visual indicators at all, for example, when clicking on a link it just appears to do nothing until the new page is completely loaded. That is A Bad Thing (tm).


In terms of both disk space & memory/cpu usage. The python/tkinter combo already puts us at a pretty good starting point.


Run mcross -h to get a full list of CLI arguments. The same arguments can also be defined in a TOML config file: run mcross-info to know where this file should be for your OS. For example, running mcross like this:

mcross --background-color pink -t "Ubuntu"

is the same as putting this in $HOME/.config/mcross/mcross.toml for linux:

background-color = "pink"
text-font = "Ubuntu"

The priority is CLI arg > config file > default.

#Keyboard shortcuts:

  • Ctrl-l: jump to address bar.
  • Hold Alt to see possible button shortcuts underlined. This is what Qt calls Accelerator Keys.
  • Ctrl-PgUp/PgDown: switch to tab above/below.
  • Ctrl-r / F5: refresh page.
  • Ctrl-t: open new tab.
  • Ctrl-w: close current tab.

#Downloading files:

When the server responds with something that isn't decodable as a string, McRoss will download the response body as a file with a helper, for example, gemget.


# example for gemget; $URL is self-explanatory, and $DEST is just download-dest
# i.e. where the files will be downloaded to.
download-cmd = "gemget $URL -d $DEST"
download-dest = "~/Downloads/"

The download job will then be handed to the helper of your choice.

Note: if your download-dest contains spaces, you need to escape them with 2 backslashes. Like this: ~/My\\ Downloads. One for shell and one for TOML.


To get started:

pyenv install 3.7.7
pyenv virtualenv 3.7.7 mcross
pyenv activate
# or if you are more into virtualenv
virtualenv -p python3.7.7 venv
source venv/bin/activate

poetry install

# to publish, first bump version in pyproject.toml then
poetry publish --build

There are 2 McRoss-related mailing lists which we both subscribe to:

If you're not familiar with the mailing list workflow, check out git-send-email.io and mailing list etiquette. useplaintext.email also has useful plaintext setup tips for various email clients, though Nhân doesn't necessarily agree with its "plaintext or nothing" stance.

#Server bugs/surprises

#Forces gemini:// in request

Spec says protocol part is optional, but if we omit that one the server will respond with 53 No proxying to other hosts!.


Spec says a newline should be \r\n but the server running gemini.circumlunar.space just uses \n every time.