TUI Web Browser

a42051e layout: list item improvements, fix inner markers

~bptato pushed to ~bptato/chawan git

23 hours ago

aca410c layout: add wrapper box for table caption + misc stuff

~bptato pushed to ~bptato/chawan git

a day ago

#Chawan - a web browser for your terminal

Project page

Screenshot of Chawan displaying its SourceHut page

#What is this?

A text-mode web browser. It displays websites in your terminal and allows you to navigate on them.

It can also be used as a terminal pager.


Note: a POSIX-compliant operating system is required.

  1. Clone the Chawan repository: git clone https://git.sr.ht/~bptato/chawan && cd chawan
  2. Install the Nim compiler: https://nim-lang.org/install.html
    • Please use 1.6.14 or newer, ideally 2.0.4. Versions older than 1.6.14 will not work. (You can check your Nim compiler's version using nim -v.)
  3. Install the following dependencies:
    • libcurl: https://curl.se/libcurl/
    • zlib: https://zlib.net/
    • pkg-config, pkgconf, or similar (must be found as "pkg-config" in your $PATH)
    • (Linux only) libseccomp: https://github.com/seccomp/libseccomp
    • GNU make. On systems where it is not the default make, install and use gmake in the following steps.
    • Recommended: a termcap library. e.g. ncurses comes with one.
    • TL;DR for Debian: apt install libcurl4-openssl-dev zlib1g-dev pkg-config make ncurses-base libseccomp-dev
  4. Download parts of Chawan found in other repositories: make submodule
  5. Run make.
  6. Install using make install (e.g. sudo make install).

Then, try:

$ cha -V # open in visual mode for a list of default keybindings
$ cha example.org # open your favorite website directly from the shell
$ mancha cha # read the cha(1) man page using `mancha'


Currently implemented features are:

  • multi-processing (several buffers can be loaded at once)
  • multi-charset, double-width aware text display (but no bi-di yet)
  • HTML5 support
  • CSS-capable layout engine
    • flow layout (with floats!), automatic table layout, flexbox layout (some flex attributes still WIP)
  • forms
  • incremental loading of documents
  • JavaScript based navigation (i.e. programmable keybindings)
  • JavaScript support in documents
    • some basic DOM manipulation APIs are supported
    • disabled by default; enable it at your own risk.
  • cookies
  • supports several protocols: HTTP(S), FTP, Gopher, Gemini, Finger, etc.
  • can load user-defined protocols/file formats using local CGI, urimethodmap and mailcap
  • markdown viewer
  • man page viewer (like w3mman)
  • mouse support
  • OS-level sandboxing on FreeBSD, OpenBSD and Linux (through Capsicum, pledge and libseccomp)

...with a lot more planned.



Many other text-based web browsers exist. Here's some recommendations if you want to try more established ones:

  • w3m - A text-mode browser, extensible using local-cgi. Also has inline image display and very good table support. Inspired many features of Chawan.
  • elinks - Has CSS and JavaScript support, and incremental rendering (it's pretty fast.)
  • lynx - "THE text-based web browser."
  • edbrowse - This one looks more like ed than less or vi. Mainly designed for blind users.
  • browsh - Firefox in your terminal.


#I can't select/copy text with my mouse?

Your options are:

  • Use v (and copy with y). Drawback: requires keyboard
  • Hold down the shift key while selecting. Drawback: can only select text currently on the screen
  • Disable mouse support (input.use-mouse = false in config.toml). Drawback: see above (plus now you can't use the mouse to move on the screen)

#Why do I get strange/incorrect/ugly colors?

Chawan's display capabilities depend on what your terminal reports. In particular:

  • if the $COLORTERM variable is not set, then it may fall back to 8-bit or ANSI colors
  • if it does not respond to querying the background color, then Chawan's color contrast correction will likely malfunction

You can fix this manually by adjusting the display.default-background-color, display.default-foreground-color, and display.color-mode variables. See doc/config.md for details.

#Can I view Markdown files using Chawan?

Yes; Chawan now has a built-in markdown converter. If you don't like it, you can always replace it with e.g. pandoc.

#I set my $PAGER to cha and now man pages are unreadable.

Most man implementations print formatted manual pages by default, which Chawan can parse if they are passed through standard input.

Unfortunately, mandoc passes us the formatted document as a file, which Chawan reasonably interprets as plain text without formatting.

At this point you have two options:

  • export PAGER='cha -T text/x-ansi' and see that man suddenly works as expected.
  • alias man=mancha and see that man suddenly works better than expected.

Ideally you should do both, to deal with cases like git help which shells out to man directly.

#Where are the keybindings?

Please run cha about:chawan for a list of default keybindings. Users familiar with vi, vim, etc. should find these defaults familiar.

A w3m-like keymap also exists at bonus/w3m.toml. Note that not every w3m feature is implemented yet, so it's not 100% compatible.

#How do I view text files with wrapping?

By default, text files are not auto-wrapped, so viewing plain text files that were not wrapped properly by the authors is somewhat annoying.

A workaround is to add this to your config's [page] section:

' f' = "pager.externFilterSource('fmt')"

and then press <space> f to view a wrapped version of the current text file. (This assumes your system has an fmt program - if not, fold -s may be an alternative.)

To always automatically wrap, you can add this to your user style:

plaintext { white-space: pre-wrap }

To do the same for HTML and ANSI text, use plaintext, pre.

#Why does $WEBSITE look awful?

Usually, this is because it uses some CSS features that are not yet implemented in Chawan. The most common offenders are grid and CSS variables.

There are three ways of dealing with this:

  1. If the website's contents are mostly text, install rdrview. Then bind the following command to a key of your choice in the config (e.g. <space> r):
    ' r' = "pager.externFilterSource('rdrview -H -u \"$CHA_URL\"')"
    This does not fix the core problem, but will significantly improve your reading experience anyway.
  2. Complain here, and wait until the problem goes away.
  3. Write a patch to fix the problem, and send it here.

#$WEBSITE's interactive features don't work!

Some potential fixes:

  • Logging in to websites requires cookies. Some websites also require cookie sharing across domains. For security reasons, Chawan does not allow any of this by default, so you will have to fiddle with siteconf to fix it. See doc/config.md#siteconf for details.
  • Set the referer-from siteconf value to true; this will cause Chawan to send a Referer header when navigating to other URLs from the target URL.
  • Enable JavaScript. If something broke, type M-c M-c to check the browser console, then follow step 3. of the previous answer.
    Warning: remote JavaScript execution is inherently unsafe. Please only enable JavaScript on websites you trust.

#I'm interested in the technical details of Chawan.

Here's some:

  • Written in Nim
  • Uses QuickJS for JavaScript execution. (The QuickJS regex engine, libregexp, is also used for in-document searches.)
  • Uses multi-processing provided by POSIX. (No threads.) Each buffer gets its own process; as a result, buffers can be duplicated by simply forking their process. File loading is done in yet another process. IPC happens through UNIX domain sockets.
  • Layout, CSS cascading, HTML parsing, etc. are handled by built-in modules, not external libraries. (However, the HTML parser and the character coding library are available as separate libraries as well.)
  • Uses termcap for basic terminal capability querying, and notcurses-style terminal queries for detecting "modern" features (like true color).

For further details, you will have to read the source code please read this.

#Why write another web browser?

I've found other text-based web browsers insufficient for my needs, so I thought it'd be a fun excercise to write one by myself, for myself.

Generally, I'm happy if Chawan works on websites I use frequently. If it also works on other websites, that's a bonus.


Chawan is dedicated to the public domain. See the UNLICENSE file for details.

Chawan also includes and depends on several other libraries. For further details, see license.html or check the about:license page in Chawan.