browser for the small internet
Go to file
Omar Polo 14728991ef add missing #include "compat.h" 2023-06-22 13:55:26 +00:00
compat readd rcs id to ease trackability 2022-03-19 14:36:29 +00:00
contrib fringes already have a prefix of "~" 2022-01-12 12:33:41 +00:00
data update emoji-data.txt to 14.0.0 2022-02-09 21:08:09 +00:00
extra rename images -> extra 2022-02-13 11:57:57 +00:00
include make clear to which struct every L_* flag is supposed to belong to 2022-11-07 22:56:35 +00:00
libgrapheme add the libgrapheme makefile 2022-11-04 18:38:22 +00:00
pages fix build out-of-tree 2022-02-26 18:27:07 +00:00
parser fmt; get rid of double `break' 2022-08-16 17:01:12 +00:00
phos make phos_uri compile with -Werror 2022-11-07 18:10:51 +00:00
site update the logo; from freezr! 2022-09-09 20:13:45 +00:00
test add some extra tests for the iri parser 2022-12-26 18:13:06 +00:00
u start to refactor the rendering 2022-11-07 18:18:53 +00:00
.gitignore add ignore entries for the site-generated files 2022-09-09 20:14:03 +00:00
ChangeLog changes for 0.8.1 2022-05-25 20:31:26 +00:00
LICENSE add LICENSE file 2021-03-12 19:17:36 +00:00 hook iri.[ch] into the build 2022-12-23 22:08:36 +00:00 mention libgrapheme in the 2022-11-02 20:20:13 +00:00 add bunch of compats for compatibility 2021-03-08 19:28:22 +00:00
cmd.c start to refactor the rendering 2022-11-07 18:18:53 +00:00
compl.c add compl_lu completion function for load-url and load-current-url 2022-02-26 17:45:38 +00:00 use pkg-config for libgrapheme 2022-11-02 20:10:55 +00:00
control.c work around macos lack of SOCK_CLOEXEC / SOCK_NONBLOCK 2022-05-25 18:03:07 +00:00
defaults.c replace has_prefix with strncmp 2022-04-24 12:24:18 +00:00
downloads.c garbage collect `dequeue_first_download' 2022-05-05 10:18:05 +00:00
fs.c move load session stuff to session.c 2022-04-24 12:14:54 +00:00
gencmd.awk add descr. to completions ; filter by descr. too 2021-07-18 10:25:43 +00:00
help.c replace TAILQ_EMPTY/INSERT_HEAD/TAIL dance with a single TAILQ_INSERT_TAIL 2021-08-12 09:09:52 +00:00
hist.c unroll recursion 2022-01-05 15:34:48 +00:00
iri.c add missing #include "compat.h" 2023-06-22 13:55:26 +00:00
iri.h iri: support framents and enable fragments tests 2022-12-25 18:49:56 +00:00
keymap.c add forgotten include for string.h 2022-04-24 15:02:52 +00:00
mcache.c partial revert of "abstract over evbuffers" 2022-04-13 16:51:01 +00:00
mime.c replace has_prefix with strncmp 2022-04-24 12:24:18 +00:00
minibuffer.c use the new iri parser in ir_select_gemini 2022-12-23 22:11:18 +00:00
net.c s/IMSG_GET_RAW/IMSG_GET and gc unused IMSG_GET_FILE 2022-05-27 17:55:15 +00:00
pagebundler.c prettify pagebundler output 2022-02-08 22:43:32 +00:00
parse.y fix add_proxy path check 2022-12-25 18:58:28 +00:00
sandbox.c don't include linux/prctl.h 2022-05-19 07:32:26 +00:00
session.c don't allow the history to grow too much + save_session refactoring 2022-05-11 19:41:54 +00:00
telescope.1 add mini-kill-whole-line 2022-04-15 09:13:28 +00:00
telescope.c s/IMSG_GET_RAW/IMSG_GET and gc unused IMSG_GET_FILE 2022-05-27 17:55:15 +00:00
tofu.c merge update_cert and tofu_update into tofu_update_persist 2022-04-24 11:29:02 +00:00
ui.c start to refactor the rendering 2022-11-07 18:18:53 +00:00
utils.c work around macos lack of SOCK_CLOEXEC / SOCK_NONBLOCK 2022-05-25 18:03:07 +00:00


Telescope is a Emacs/w3m-inspired browser for the "small internet" that supports Gemini, Gopher and Finger.


  • tabs
  • bookmarks
  • privsep
  • minibuffer live narrowing
  • multiple protocols support
  • fully customizable

There are still various things missing or, if you prefer, various things that you can help develop :)

  • subscriptions
  • tofu oob verification
  • client certificates
  • add other GUIs: at the moment it uses only ncurses, but telescope shouldn't be restricted to TTYs only!


Why yet another browser?

One of the great virtues of Gemini is its simplicity. It means that writing browsers or server is easy and thus a plethora of those exists. I myself routinely switch between a couple of them, depending on my mood.

More browsers brings more stability as it became more difficult to change the protocol, too.

However, Telescope was ultimately written for fun, on a whim, just to play with ncurses, libtls, libevent and the macros from sys/queue.h, but I'd like to finish it into a complete Gemini browser.


  • Fun: hacking on Telescope should be fun.
  • Clean: write readable and clean code mostly following the style(9) guideline. Don't become a kitchen sink.
  • Secure: write secure code with privilege separation to mitigate the security risks of possible bugs.
  • Fast: it features a modern, fast, event-based asynchronous I/O model.
  • Cooperation: re-use existing conventions to allow inter-operations and easy migrations from/to other clients.


Telescope aims to use the "Trust, but Verify (where appropriate)" approach outlined here: gemini://

The idea is to define three level of verification for a certificate:

  • untrusted: the server fingerprint does NOT match the stored value
  • trusted: the server fingerprint matches the stored one
  • verified: the fingerprint matches and has been verified out-of-band by the client.

Most of the time, the trusted level is enough, but where is appropriate users should be able to verify out-of-band the certificate.

At the moment there is no UI for oob-verification though.


Telescope depends on ncursesw, libtls (from either LibreSSL or libretls), libevent (either v1 or v2) and pkg-config. libgrapheme is an optional dependency: there's a bundled copy but it's reccomended to install it if available. When building from a git checkout, yacc (or bison) is also needed.

To build from a release tarball just execute:

$ ./configure
$ make
$ sudo make install

The configure script has optional support for building with libraries provided by your distribution instead of using the bundled versions:

If you want to build from the git checkout, something that's discouraged for users that don't intend to hack on telescope

$ ./
$ ./configure
$ make
$ sudo make install	# eventually

Please keep in mind that the main branch, from time to time, may be accidentally broken on some platforms. Telescope is developed primarily on OpenBSD/amd64 and commits on the main branch don't get always tested in other OSes. Before tagging a release however, a comprehensive testing on various platforms is done to ensure everything is working as intended.


Any form of contribution is appreciated, not only patches or bug reports: feel free to open an issue or send an email to

If you have a sample configuration, custom theme, a script or anything that could be helpful to others, consider adding it to the contrib directory.

User files

Telescope stores user files according to the XDG Base Directory Specification by default. The usage and contents of these files are described in the man page, under "FILES".

Only one instance of Telescope can be running at time per user.


Telescope is distributed under a BSD-style licence. The main code is under the ISC but for files under compat/ it varies.

data/emoji.txt is copyright © 1991-2021 Unicode, Inc. and distributed under the UNICODE, Inc license agreement.