textsmith-electron: a different experience of The Textsmith, a terminal
whose output is a web document, written for screen readers first. (The main
edition, textsmith, is a native GTK terminal; both read the same bookmarks.
Site and manual: https://thetextsmith.com.)
Copyright 2026 Ishe Chinyoka. Distributed under the GNU General Public
License, version 3 or later; see LICENSE.
In this edition, each command becomes a heading and its output is the text under that heading, so a screen reader's heading navigation moves from command to command. The host and current directory live in the title bar; there is no prompt line.
The title bar shows your own prompt (your PS1, without colours), the shell
and the program name: [ishe@forge Downloads] — bash — The Textsmith. With no
PS1 it shows user@host: directory.
The Textsmith runs your login shell, as set with chsh (read from
/etc/passwd, so a change applies to the next tab or window, without logging
out). bash and zsh are supported; other shells run bash. Preferences, under
Title and start, can choose one regardless of the login shell.
With zsh, your own .zshenv and .zshrc are read as usual, then The
Textsmith adds its hooks: completion is zsh's own (your compdefs and plugins
included), history comes from $HISTFILE (~/.zsh_history if unset), and
INTERACTIVE_COMMENTS is switched on so #label: command bookmarks and
#@ work. zsh's spelling question ("correct 'sl' to 'ls' [nyae]?") is read
out, and Y, N, A or E answers it without Enter.
Linux and macOS.
npm install
npm start
npm run install-desktop
This links textsmith-electron into ~/.local/bin and adds The Textsmith
(Electron edition) to your desktop's application menu as a terminal. Before
1.0 this edition was called textsmith; that name is the main edition's now,
and an old link is removed. textsmith-electron starts a new window
detached from wherever you typed it, so it is safe to run from inside The
Textsmith itself. It takes the options desktops use for "open a terminal
here": --working-directory DIR and -e command args....
To make it the default terminal:
- Desktops using xdg-terminal-exec (recent GNOME, KDE and others):
echo textsmith-electron.desktop >> ~/.config/xdg-terminals.list - MATE:
gsettings set org.mate.applications-terminal exec textsmith-electron - Cinnamon:
gsettings set org.cinnamon.desktop.default-applications.terminal exec textsmith-electron - Older GNOME:
gsettings set org.gnome.desktop.default-applications.terminal exec textsmith-electron - i3 or sway:
bindsym $mod+Return exec textsmith-electron - Many programs also honour
export TERMINAL=textsmith-electronin~/.profile. - For Ctrl+Alt+T, add a custom keyboard shortcut running
textsmith-electron.
Ctrl+Comma opens them; they are saved as you change them, in
prefs.json in The Textsmith's folder. Categories:
- Display: commands as headings or as traditional prompt-and-$ lines (still headings underneath), light, dark or high-contrast colours, text size, font, and whether program colours are shown.
- Speech: reading output while a command runs, how many lines of finished output are read in full, and character and word reading in full-screen programs.
- Title and start: the window title (
{prompt} — {shell} — {app}) and the folder new tabs start in. - Keyboard: every shortcut below can be changed. Press an action's button, then the new keys; a combination already in use is refused, and plain letters are refused because they would get in the way of typing.
If Electron complains about the sandbox on Linux, use npm start -- --no-sandbox.
Type a bookmark as a comment, so bash ignores it if you press Enter by
mistake, with a label in front ending in : , then press Alt+M:
#vps: ssh forge call it as: vps
#sync music: rclone sync <> . --progress sync drive:Music
#notes: find . -type f -iname '*<>*' notes artificial
#copy: cp <src> <dst> copy a.txt backup/
#burn: dd if=<iso> of=/dev/sdb bs=1M status=progress
#copy(2): cp exactly 2 arguments, added at the end
#copy(2..): cp -v at least 2
#l(..1): ls -l at most 1
#copy(1..3): cp 1 to 3
#burn: dd if=<iso> of=<disk:/dev/sdb> burn arch.iso (disk defaults to /dev/sdb)
#install: sudo apt install -y <..> install vim git htop (any number)
<name:default> (or <:default>) is filled in when your arguments run out
before it. <..> (or <name..>, repeated by its name) takes every argument
the other places leave over, wherever it stands; add a count such as (1..)
to require at least one. The GTK version reads these the same way.
A default can be another place: #send: rclone sync <from> drive:Library/<to:<from>>
makes send Music mean rclone sync Music drive:Library/Music, and
send Music Songs still gives the second its own value.
A bookmark can have a command per machine, for bookmarks that travel in your dotfiles:
#update: [:anvil "sudo apt update -y && sudo apt upgrade -y", :brainpower "sudo pacman -Syu --noconfirm", :* "echo no update here"]
:* is for any other machine; several names can share a command
(:anvil :forge "..."). The machine's name is TEXTSMITH_MACHINE, else the
first line of machine in The Textsmith's folder (keep it out of your dotfiles), else
/etc/hostname. The bookmarks file never names the machine: it travels. A
bookmark for one machine only needs no list: #update: sudo pacman -Syu.
While a program runs (ssh, tmux), Ctrl+Space and the bookmark list put a
bookmark in the box as input for it, without sending it: Enter sends it.
Inside ssh forge, however it was started (an alias, a bookmark), a
bookmark with a command per machine takes forge's command, and the list has
a row for each machine, forge's first.
Bash has no global aliases; #@ gives you one. Save a bookmark whose label
starts with |, and add it to the end of any command:
#|count: wc -l ls -1F #@count runs ls -1F | wc -l
#|grab: grep -i <> find . #@grab todo @count runs find . | grep -i todo | wc -l
#quiet: 2>/dev/null make #@quiet runs make 2>/dev/null
| means "pipe into this"; without it the bookmark's text is simply added.
Several can follow each other (@grab todo @count), each with its own
arguments. Tab completes the names after #@. Bash reads the #@ part as a
comment, so a command typed elsewhere loses nothing but the addition.
The label is the name, an optional count in brackets and an optional
description. Only the label is read, so =, $, &, # and colons in the
command itself are left alone. A command with no label is a bookmark without
a name. Bookmarks are stored the same way, one per line, in
the bookmarks file; lines there starting with # are notes. The older
forms (ssh forge#vps, ssh forge =vps) are still read.
<>marks a place for an argument;<name>names it. Arguments fill the places in order, and a named place used twice gets the same value twice.- Arguments go in exactly as typed, so quote names with spaces.
- Calling a bookmark with the wrong number of arguments is refused with an explanation ("sync takes 1 argument; you gave 0.").
- Alt+M on the same line again removes it; the same name with a new command replaces the old one.
They are kept in bookmarks, one per line, which you can also edit by hand,
in The Textsmith's folder, shared with the main edition. The folder is the
first of: TEXTSMITH_CONFIG (or TEXTSMITH_HOME); ~/.textsmith, if it is
there; $XDG_CONFIG_HOME/textsmith (~/.config/textsmith).
To keep bash's own <> redirection in a bookmark, write it as \<>
(exec 3\<>/dev/tcp/<host>/80); a backslash before any place keeps it as
written.
npm testruns the shell session without the window and prints the events, then checks how bookmark lines are read and filled in.npm run test:zshrepeats the shell-dependent checks with zsh (skipped when zsh is not installed).npm run test:uistarts The Textsmith and drives it from the keyboard: commands and headings, the errors view, links, Tab completion, input to running programs (secret input must never become a heading), a full-screen list program with the F2 page, and reading in vim. It opens a window while it runs; on Linux,xvfb-run -a npm run test:uikeeps it out of sight. The python and vim tests are skipped when those are not installed.
- Enter: run the command. While a command is running, the box sends a line of input to it. In a program with its own prompt (psql, python, sqlite3) each line you send becomes a heading 3 inside that command, with the answer under it.
- Shift+Enter: run the command as administrator.
pacman -Syubecomessudo pacman -Syu. - Quotes close as they are opened: typing
"gives""with the caret between, typing it again steps over it, and Backspace in an empty pair removes both. Never after a letter (it's) or inside quotes. Parentheses are left alone, sincecaseuses them unpaired. Can be turned off. - Readline keys in the command box: Ctrl+A, Ctrl+E, Ctrl+B, Ctrl+F, Alt+B, Alt+F, Ctrl+K, Ctrl+U, Ctrl+W, Alt+D, Alt+Backspace, Ctrl+Y, Alt+C, Alt+U, Alt+L, Ctrl+T and Alt+. (last word of the previous command), as in bash; what is deleted is read out. Turn them off in the preferences for desktop keys instead (Ctrl+A selects all, Home and End, Ctrl+arrows by word).
- Pagers: when less, more or man shows its pages in the document (as journalctl and git do, and any pager over ssh), the box says "Pager", and from an empty box Space gives the next page, B the previous one and Q quits.
- Up / Down in the command box: history, including earlier sessions (read
from your shell's history file,
~/.bash_historyor$HISTFILE; each command is saved as soon as it runs). - Ctrl+R: search history. Type to filter; Down moves into the matches; Enter runs one, Ctrl+Enter puts it in the box to edit first.
- Alt+M: bookmark the command in the box and clear the box. Alt+Shift+M bookmarks it and runs it (or asks for its arguments). See "Bookmarks" below.
- Ctrl+Space: call a bookmark by name, such as
sync drive:Music. Tab completes the name, then the arguments; Up and Down step through the bookmarks; Escape goes back to commands; Shift+Enter runs it with sudo. - Alt+Shift+B: all bookmarks, newest first. Enter runs one (or asks for its arguments). Ctrl+Enter puts the whole bookmark, name and all, in the box to edit; Enter then saves it in place of the old one (Escape cancels, an emptied box removes it). Delete removes one, typing filters them.
- Tab: complete what is under the caret: commands, files, and whatever the
program's own bash completion offers (git branches, rustup and adb
subcommands, systemctl units...), including your own
complete -Wword lists. Tab works on the command being typed even inside loops and lists (for f in *; do restic …,a && b,x | y,$( … )), and completes variable names after$($HOME,"$REPO",${PATH}). With several matches, Tab again steps through them and Shift+Tab steps back. Tab never leaves the box. - Tab while a program is running (a remote shell over ssh or adb, psql, python) works the same way: the program completes the line, and the result comes back into the box. With several matches, the program's own list is read out.
- Ctrl+Shift+C: select and copy. The current block's text (or a full-screen program's screen) opens in a read-only text box where Shift+arrows select, Ctrl+C copies and Ctrl+A selects everything. Escape goes back.
- Alt+Up / Alt+Down: move to the previous / next heading, commands and their sub-headings alike.
- Escape: back to the command box.
- Alt+1: normal view, stdout and stderr together.
- Alt+2: errors only, what each command wrote to stderr.
- Alt+0: the list of commands. Enter on a command opens its output.
- Ctrl+C with nothing selected: interrupt the running command. Ctrl+D on an empty box: end of input.
- Alt+G: hand the window to the running command as a classic terminal grid, and back.
- Ctrl+Shift+T: new tab with its own shell. Ctrl+PageDown and Ctrl+PageUp (or
Ctrl+Tab and Ctrl+Shift+Tab) move between tabs, and the tab you land on says
which it is ("Tab 2 of 3, ~/Downloads"). Ctrl+Shift+W or
exitcloses a tab. These keys work inside full-screen programs too.
When a program asks for a password (sudo, ssh, read -s), the box says so and
hides what you type, and the password never appears in the document.
Full-screen programs (vim, neomutt, htop) take over the window by themselves and the title becomes "Vim, active". Quitting them returns to the document.
When a full-screen program steps aside, prints something and waits (neomutt
with an external pager, vim after :!make), that text gets a heading 3 named
after its first line and focus moves to it. Escape returns to the box, and
Enter there usually tells the program to carry on.
To read mail as document text, tell neomutt to hand messages to cat when it
runs inside The Textsmith. In neomuttrc:
set pager=`[ -n "$TEXTSMITH" ] && echo cat || echo builtin`
($ANVIL is still set too, so older configs keep working.)
F2 (or Alt+R) turns a full-screen program's screen into a web page. Its list
(neomutt's messages, htop's processes, a menu) becomes a list of buttons:
Enter on one moves the program's selection there and presses Enter, so in
neomutt it opens that message; Shift+Enter only moves the selection. Other
lines are plain text. A "Keys" field at the bottom sends keys to the program as
typed (q, d, /), an empty field sends Enter, and named keys go in angle
brackets: <esc>, <pgdn>, <up>. F5 refreshes the page; F2 or Escape goes
back to the program. Alt+1 from there reads the whole session document while
the program waits. When a program has stepped aside by itself (neomutt
showing a message as text), F2 tells it to carry on.
Inside a full-screen program, The Textsmith speaks for it:
- Moving to another line reads that line.
- Left and right (arrows, or h and l in vim) read the character under the cursor; jumps such as w, b or Ctrl+arrows read the word.
- In lists (neomutt's index, htop, menus) the highlighted row is read as the
selection moves, even when the program parks its cursor elsewhere. For
neomutt,
set braille_friendlyalso puts the cursor on the selected line. - Typing a space reads the word just finished.
- A new message on the bottom line (vim's mode and messages) is read out.
- Alt+L: read the line under the cursor.
- Alt+S: read the bottom line.
In output, web addresses open in the browser and references such as ls(1)
run man 1 ls. Pagers are switched off (PAGER=cat), so man pages and
git log arrive as ordinary document text.
shell/zsh/.zshenv,shell/zsh/.zshrc: the same for zsh, which is started withZDOTDIRpointing there and reads your own files from it.shell/textsmith.bashrc: shell integration. Marks where each command ends, reports the directory, and sends each command's stderr down a separate pipe.session.js: runs bash on a pty, turns the stream into events, and keeps a small terminal emulator per command so progress bars and\rrewrites settle into their final text. No Electron in here.main.js,preload.js: the Electron window and the bridge to the page.renderer/: the page itself.
- stdout and stderr travel separately, so in the combined view a line of stderr can land slightly before or after neighbouring stdout.
- Programs see that stderr is not a terminal; some drop colour or progress output there.
- A password prompt from a remote machine (sudo over ssh) is recognised by its wording ("Password:"); one worded differently will not hide your typing.
- No fish integration yet.
- Output of a running command is read out whenever it pauses for a moment, which is what makes sqlite3 or python answer after each line. A long build that pauses often will be chatty; there is no switch for that yet.