fenrir/docs/fenrir.1

.\" Automatically generated by Pandoc 3.12.1
.\"
.TH "fenrir" "1" "" "" "Fenrir User Manual"
.SH Fenrir User Manual
Fenrir is a Linux console screen reader written in Go.
It reads Linux text consoles and can run in an X11 terminal as a regular
user.
.PP
\f[B]Current maintainer:\f[R] Storm Dragon
.PD 0
.P
.PD
\f[B]Original creator:\f[R] Chrys (see CREDITS)
.PP
For build requirements and setup, see the README.
.SS Starting and stopping
Run these commands from the checkout root after building
\f[CR]fenrir\f[R]:
.IP
.EX
\f[I]# Linux text console, with console and keyboard device access\f[R]
sudo ./fenrir

\f[I]# Linux console in the foreground (also use \-f with service managers)\f[R]
sudo ./fenrir \-f

\f[I]# X11 terminal, as your regular user\f[R]
\&./fenrir \-x

\f[I]# Either mode can select the laptop layout\f[R]
\&./fenrir \-x \-\-keyboard\-layout laptop
.EE
.PP
Console mode starts in the background by default.
Add \f[CR]\-f\f[R] to keep it in the foreground, including under a
service manager.
The launcher returns after the reader initializes and reports startup
failures in the launching terminal.
Use \f[CR]\-\-debug\-file PATH\f[R] to retain diagnostics after
detaching.
Help, version, and configuration\-only commands always run in the
foreground.
.PP
X11 mode (\f[CR]\-x\f[R]) always stays in the foreground because it owns
the terminal and its child shell.
Press \f[B]Fenrir+Q\f[R] to quit either mode.
Run only one reader on a given Linux console.
Separate X11 terminal instances can run at once.
.PP
X11 mode starts a shell in a new PTY.
The launching terminal must supply valid \f[CR]DISPLAY\f[R] and
\f[CR]WINDOWID\f[R] environment variables.
Keyboard interception is scoped to that terminal window; a desktop
screen reader can handle other windows.
.PP
Console mode needs access to console devices, keyboard event devices,
and \f[CR]/dev/uinput\f[R].
It releases keyboard input on graphical virtual terminals and on text
consoles selected in \f[CR]screen.ignored_vts\f[R].
.SS Keyboard layouts and help
The \f[B]Fenrir key\f[R] is Insert, Super/Windows, or keypad 0 with
NumLock off.
Hold it while pressing the other keys in a shortcut.
Bare keypad review keys also require NumLock off.
.PP
The desktop layout uses the numeric keypad.
The laptop layout uses Fenrir chords on the main keyboard.
Select a layout with \f[CR]\-\-keyboard\-layout desktop\f[R] or
\f[CR]\-\-keyboard\-layout laptop\f[R], or set
\f[CR]keyboard.layout\f[R] in the settings file.
.PP
Press \f[B]Fenrir+H\f[R] or \f[B]Fenrir+F1\f[R] to enter the tutorial.
Command shortcuts are announced and described instead of executed.
Up and Down browse commands; Left and Right switch between active
actions, unbound actions, and scripts.
Space repeats the current item.
Escape or Fenrir+F1 exits.
.PP
The complete layouts are desktop.toml and laptop.toml.
.SS Screen review
Review moves Fenrir\(cqs reading position without moving the
application\(cqs cursor.
Return to the application cursor with the Follow cursor shortcut.
By default, application cursor movement or a screen change also leaves
review.
.IP \(bu 2
\f[B]Previous / current / next line\f[R]
.RS 2
\f[B]Desktop:\f[R] Keypad 7 / 8 / 9
\f[B]Laptop:\f[R] Fenrir+U / I / O
.RE
.IP \(bu 2
\f[B]Previous / current / next word\f[R]
.RS 2
\f[B]Desktop:\f[R] Keypad 4 / 5 / 6
\f[B]Laptop:\f[R] Fenrir+J / K / L
.RE
.IP \(bu 2
\f[B]Previous / current / next character\f[R]
.RS 2
\f[B]Desktop:\f[R] Keypad 1 / 2 / 3
\f[B]Laptop:\f[R] Fenrir+M / Comma / Period
.RE
.IP \(bu 2
\f[B]Top / bottom of screen\f[R]
.RS 2
\f[B]Desktop:\f[R] Fenrir+Keypad 7 / 9
\f[B]Laptop:\f[R] Fenrir+Shift+U / O
.RE
.IP \(bu 2
\f[B]Line start / end\f[R]
.RS 2
\f[B]Desktop:\f[R] Fenrir+Keypad 4 / 6
\f[B]Laptop:\f[R] Fenrir+Shift+J / L
.RE
.IP \(bu 2
\f[B]First / last text on line\f[R]
.RS 2
\f[B]Desktop:\f[R] Fenrir+Keypad 1 / 3
\f[B]Laptop:\f[R] Fenrir+Control+J / L
.RE
.IP \(bu 2
\f[B]Read screen\f[R]
.RS 2
\f[B]Desktop:\f[R] Fenrir+Keypad 5
\f[B]Laptop:\f[R] Fenrir+Shift+K
.RE
.IP \(bu 2
\f[B]Screen before / after cursor\f[R]
.RS 2
\f[B]Desktop:\f[R] Fenrir+Keypad 8 / 2
\f[B]Laptop:\f[R] Fenrir+Shift+I / Comma
.RE
.IP \(bu 2
\f[B]Character above / below\f[R]
.RS 2
\f[B]Desktop:\f[R] Fenrir+Control+Keypad 8 / 2
\f[B]Laptop:\f[R] Fenrir+Control+I / Comma
.RE
.IP \(bu 2
\f[B]Follow cursor\f[R]
.RS 2
\f[B]Desktop:\f[R] Fenrir+Keypad Period
\f[B]Laptop:\f[R] Fenrir+Slash
.RE
.IP \(bu 2
\f[B]Review position\f[R]
.RS 2
\f[B]Desktop:\f[R] Keypad Period
\f[B]Laptop:\f[R] Fenrir+Shift+Period
.RE
.PP
Press the current\-line or current\-word shortcut twice quickly to spell
the text, or three times for phonetic reading.
Press the current\-character shortcut twice for its phonetic name.
The default interval between presses is 200 ms;
\f[CR]keyboard.multi_press_timeout_ms\f[R] changes it at launch.
.SS Tracking modes
Cycle through \f[B]cursor\f[R], \f[B]table\f[R], and \f[B]highlight\f[R]
with \f[B]Fenrir+Keypad Asterisk\f[R] on desktop or \f[B]Fenrir+Y\f[R]
on laptop.
The startup selection is \f[CR]reading.mode\f[R].
.IP \(bu 2
\f[B]Cursor\f[R]: follows application cursor movement.
.IP \(bu 2
\f[B]Table\f[R]: treats delimited or space\-aligned text as cells.
.IP \(bu 2
\f[B]Highlight\f[R]: follows changes to highlighted text, such as menu
selections.
.PP
In table mode, word navigation moves between cells, line start/end moves
to the first/last cell, and first/last text moves to the first/last
character in the current cell.
Fenrir uses visible headings automatically when a text heading is
followed by a row with at least two numeric fields.
You can enter table mode, run \f[CR]free \-h\f[R], and review its cells
without setting headers yourself.
Aligned tables use shared column boundaries so an unnamed heading or an
empty field does not shift the remaining columns.
Multiword headings and values stay in their cells when the visible
alignment distinguishes them.
.PP
When you begin reviewing a recognized table at or immediately above the
application cursor, review starts at the first cell of its first data
row.
For example, after \f[CR]free \-h\f[R], current word reads
\f[CR]Mem:\f[R] and next word reads the total memory value.
The application cursor stays in place.
Existing review positions are preserved while output updates; manual
headers or clearing headers disable this automatic starting position.
.PP
Automatic headers are inferred from the visible output block being
reviewed; they are not remembered after the heading scrolls off screen.
Text\-only tables, wrapped output, and ambiguous or grouped headings may
require manual selection.
Place review on the desired header row and press \f[B]Fenrir+X\f[R] to
replace the automatic headers.
For grouped headings, select the row naming individual columns.
Manual headers remain until cleared, table mode is left, or the screen
session changes.
.PP
Press \f[B]Fenrir+Control+Shift+X\f[R] to clear headers and use generic
column numbers.
Automatic header assignment stays off until you leave and re\-enter
table mode or the screen session changes; \f[B]Fenrir+X\f[R] can still
set headers manually.
Outside table mode, Fenrir+X places a text\-selection mark instead.
.SS Speech and automatic reading
.IP \(bu 2
\f[B]Control\f[R] interrupts speech.
.IP \(bu 2
\f[B]Fenrir+F4\f[R] toggles mute.
.IP \(bu 2
\f[B]Keypad Enter\f[R] on desktop temporarily silences speech.
Speech can return on the next keypress or a newly recognized prompt or
completion.
.IP \(bu 2
\f[B]Fenrir+Keypad Enter\f[R] on desktop, or \f[B]Fenrir+Enter\f[R] on
laptop, toggles automatic reading of new text.
.IP \(bu 2
\f[B]Fenrir+Backspace\f[R] passes the next key through to the
application.
.PP
Character echo, word echo, and cursor echo can be configured separately.
Punctuation levels are \f[CR]none\f[R], \f[CR]some\f[R],
\f[CR]most\f[R], and \f[CR]all\f[R].
At \f[CR]some\f[R] and \f[CR]most\f[R], punctuation inside words, URLs,
email addresses, and filenames is also named.
Apostrophes within words and single numeric separators such as those in
\f[CR]3.14\f[R], \f[CR]1,000\f[R], and \f[CR]12:30\f[R] follow the
selected level.
Sentence punctuation follows the selected level too.
Character review always names punctuation.
Capital indicators, emoticons, repeated\-symbol summaries, indentation
feedback, and attribute feedback are configurable in Reading.
.PP
\f[B]Fenrir+T\f[R] announces the time; press twice quickly for the date.
\f[B]Fenrir+Shift+V\f[R] announces the Fenrir version.
.SS Fenrir Menu and quick settings
Press \f[B]Fenrir+F\f[R] to open the Fenrir Menu.
It contains settings tabs for presentation, speech, sound, reading,
keyboard, internal UI, clipboard, and other options.
The form captures its navigation keys until it closes.
.IP \(bu 2
At the tab selector, use arrows to choose a tab.
.IP \(bu 2
Tab and Shift+Tab move between controls and the tab selector.
.IP \(bu 2
Space or Enter toggles a checkbox.
.IP \(bu 2
Arrows change list selections and numeric values.
.IP \(bu 2
Activate \f[B]OK\f[R] to save, or \f[B]Cancel\f[R] or Escape to discard
the form\(cqs changes.
.PP
Speech rate, pitch, and volume use a scale from \-100 to 100.
For speech rate, Up and Down change the value by 10; Left and Right
change it by 1.
Sound volume is between 0.0 and 1.0.
Backend, device, keyboard layout, sound theme, and other launch\-only
settings take effect on the next start.
.PP
The \f[B]Internal UI\f[R] tab controls speech in Fenrir\(cqs own menus
and dialogs.
\f[B]Announce grid row and column\f[R] and \f[B]Announce item
position\f[R] are independent checkboxes, both enabled by default.
Disable coordinates to omit \(lqrow 1, column 2\(rq; disable item
position to omit \(lq2 of 20\(rq.
Item names and grid navigation remain available with both disabled.
Saved changes apply immediately to Emoji and Spellcheck grids and
persist across launches.
These are global settings, so this tab is omitted from application
settings.
The TOML keys are \f[CR]internal_ui.announce_grid_coordinates\f[R] and
\f[CR]internal_ui.announce_item_position\f[R].
.PP
Settings saves use mode \f[CR]644\f[R] for the standard system settings
file at \f[CR]/etc/fenrirscreenreader/settings/settings.toml\f[R], so
other users can read it as a startup fallback.
Personal settings and application profiles use mode \f[CR]600\f[R].
.PP
Quick settings work without opening the form:
.IP \(bu 2
\f[B]Fenrir+Space\f[R]
.RS 2
\f[B]Action:\f[R] Announce current setting
.RE
.IP \(bu 2
\f[B]Fenrir+Left / Right\f[R]
.RS 2
\f[B]Action:\f[R] Previous / next setting
.RE
.IP \(bu 2
\f[B]Fenrir+Control+Left / Right\f[R]
.RS 2
\f[B]Action:\f[R] Previous / next category
.RE
.IP \(bu 2
\f[B]Fenrir+Up / Down\f[R]
.RS 2
\f[B]Action:\f[R] Change value
.RE
.IP \(bu 2
\f[B]Fenrir+Control+S\f[R]
.RS 2
\f[B]Action:\f[R] Save settings
.RE
.PP
Quick changes apply to the current session.
Save to retain them for future launches.
Session controls such as mute and temporary silence are separate from
saved startup preferences.
.SS Application overrides
Press \f[B]Fenrir+A\f[R] to open \f[B]Applications\f[R].
Up and Down select an item; Enter activates it and closes the menu.
Escape or the Cancel button closes the menu without changing the
selection.
Tab and Shift+Tab move between the list, Copy alias to clipboard,
Cancel, and the tab selector.
The active override is initially selected.
.PP
Type the start of a name to jump to it: \f[B]n\f[R] selects
NetworkManager, then \f[B]i\f[R] selects Ninjam.
Searching ignores letter case and does not activate the item.
Backspace removes a search character; Control+Backspace clears the
search.
Up, Down, or moving focus away from the list also clears the search.
Unmatched characters announce \f[B]No matches\f[R] and leave the last
matching search intact.
.PP
Start the application normally, then select its override.
This menu does not launch programs.
Choose \f[B]Default\f[R] to restore the settings and reading regions
that were in effect before the override.
Overrides are built into Fenrir and are never selected automatically or
remembered across restarts.
.PP
To launch a program with its override, select its name in this list,
then Tab to \f[B]Copy alias to clipboard\f[R] and press Enter.
This copies a Bash alias into Fenrir\(cqs clipboard without selecting
the override or closing the menu.
Paste it into your Bash configuration, such as \f[CR]\(ti/.bashrc\f[R],
and load that configuration in a new shell.
The aliases use the executable names \f[CR]cninjam\f[R],
\f[CR]nmtui\f[R], \f[CR]rogue\f[R], and \f[CR]codex\f[R]; Default has no
alias.
Existing aliases with those names are replaced when you load the
definition.
.PP
The alias requests the override through \f[CR]socat\f[R], then launches
the real program with the arguments you supplied.
Errors remain visible, and the program still launches if the request
fails, remote control is disabled, or Fenrir or \f[CR]socat\f[R] is
missing.
Socket inactivity is limited to two seconds.
It uses the standard socket, or your configured
\f[CR]remote.socket_file\f[R], rather than a process\-specific socket
that changes at restart.
Paste with Fenrir\(cqs clipboard command; desktop clipboard
synchronization follows your normal clipboard settings.
.PP
While an override is active, \f[B]Fenrir+F\f[R] opens its application
settings, with the application name in the title.
\f[B]OK\f[R], \f[B]Fenrir+Control+S\f[R], and remote
\f[CR]SETTING SAVE\f[R] save that application\(cqs preferences.
Quick and remote changes remain temporary until saved.
Default settings are kept separately, including any unsaved adjustments
made before activating the override.
.PP
Profiles live in an \f[CR]applications/\f[R] subdirectory of the
ordinary settings save directory.
For example:
.IP \(bu 2
System settings:
\f[CR]/etc/fenrirscreenreader/settings/applications/ninjam.toml\f[R].
.IP \(bu 2
Personal settings:
\f[CR]\(ti/.local/share/stormux/fenrirscreenreader/settings/applications/ninjam.toml\f[R].
.IP \(bu 2
With \f[CR]\-\-config /path/settings.toml\f[R]:
\f[CR]/path/applications/ninjam.toml\f[R].
.PP
NetworkManager uses \f[CR]networkmanager.toml\f[R]; Rogue uses
\f[CR]rogue.toml\f[R]; Codex uses \f[CR]codex.toml\f[R].
The directory and file are created on the first successful save.
Files contain only customized settings; omitted values inherit ordinary
settings followed by the built\-in application defaults.
A customized voice selection saves module, language, and voice together
so a later change to the ordinary voice does not break that selection.
Profiles are loaded when their override first recognizes the
application; restarting Fenrir still starts with Default.
Reselect the application to reload an edited file.
.PP
Application settings include voice, rate, pitch, volume, reading
behavior, sound enablement/volume, and typing echo.
Startup settings such as speech driver, serial device, keyboard layout,
and sound theme remain in the default menu; clipboard storage and
console routing also remain global.
Session mute and the temporary automatic\-reading toggle are not
implicitly saved.
Remote \f[CR]SAVEAS\f[R] and \f[CR]screen#ignore_screen\f[R] are
unavailable while an application is active.
Saving is blocked during context transitions or failed voice
restoration.
A malformed profile or unavailable voice leaves ordinary settings in
effect and reports an error.
Select the application again after correcting the file.
.PP
For example, a rate\-only profile contains current TOML setting names,
with no top\-level \f[CR]version\f[R] field:
.IP
.EX
\f[B][presentation.speech]\f[R]
rate = 40
.EE
.PP
To make a saved value inherit again, remove that setting from the
application file and reselect the override.
Removing the file restores complete inheritance.
.PP
An override belongs to its terminal.
Switching VTs or leaving the terminal suspends its effects; returning
resumes it when the application screen is recognized.
Unrecognized screens use ordinary reading.
A fresh shell prompt on the cursor row, with the application interface
absent, clears the selection and announces \f[B]Default settings
restored\f[R].
This works from screen contents, so it does not require access to remote
processes over SSH or inside GNU Screen.
Unusual prompts may require selecting Default manually.
Password prompts, confirmation questions, and old shell prompts in
scrollback do not clear it.
Split windows, heavily customized application colors, and localized or
unfamiliar layouts may prevent recognition; Default is always available.
.PP
\f[B]NetworkManager\f[R] targets \f[CR]nmtui\f[R] and temporarily
selects highlight tracking.
.PP
\f[B]Ninjam\f[R] targets the \f[CR]cninjam\f[R] curses client.
It announces selected controls with master, metronome, or channel
context; mute, transmit, and receive controls are spoken as states.
While adjusting a volume/pan control, Left/Right announces only the pan
percentage and direction, or center; Up/Down announces only the volume,
with minus and plus spoken explicitly.
Peak meters and the interval bar remain quiet.
Navigating the application\(cqs controls after manual review resumes
tracking; passive updates leave review in place.
Incoming chat is announced independently of control changes.
The following shortcuts temporarily replace numbered region reads:
.IP \(bu 2
\f[B]Fenrir+1\f[R]
.RS 2
\f[B]Ninjam information:\f[R] Latest new chat message received since
activation
.RE
.IP \(bu 2
\f[B]Fenrir+2\f[R]
.RS 2
\f[B]Ninjam information:\f[R] Selected channel or control
.RE
.IP \(bu 2
\f[B]Fenrir+3\f[R]
.RS 2
\f[B]Ninjam information:\f[R] Connection, tempo, and interval position
.RE
.PP
Fenrir+Shift+B lists these application assignments.
Existing user regions are preserved and restored when the override ends.
Review, Read Screen, and copying continue to expose the actual terminal
text, including its literal \f[CR]X\f[R] marks.
Chat history is baselined on activation, resize, buffer changes, and
history paging to avoid announcing old messages as new.
Messages that appear and disappear between screen captures cannot be
recovered reliably.
.PP
The laptop shortcut for reading attributes is \f[B]Fenrir+Shift+A\f[R];
Fenrir+A opens Applications in both layouts.
.PP
\f[B]Rogue\f[R] targets the classic English Rogue 5.4 terminal game,
including the 5.4.4 package.
Start \f[CR]rogue\f[R], then select \f[B]Rogue\f[R] with
\f[B]Fenrir+A\f[R] (type \f[B]r\f[R], then Enter).
The override announces messages and prompts, including \f[B]More; press
Space\f[R], changes in health, hunger, dungeon level, strength, armor,
and experience level, and newly visible monsters, objects, doors,
stairs, and traps.
Ordinary map redraws stay quiet.
Moving monsters are compared by letter and count to reduce repeated
announcements.
Their current positions remain available on request.
Appearing and disappearing messages between captures, or one monster
replacing another of the same letter without a count change, cannot
reliably be distinguished from the visible display alone.
.IP \(bu 2
\f[B]Fenrir+1\f[R]
.RS 2
\f[B]Rogue information:\f[R] Health, for example \(lqHealth: 12 of
12\(rq
.RE
.IP \(bu 2
\f[B]Fenrir+2\f[R]
.RS 2
\f[B]Rogue information:\f[R] Full status line
.RE
.IP \(bu 2
\f[B]Fenrir+3\f[R]
.RS 2
\f[B]Rogue information:\f[R] Latest message or prompt
.RE
.IP \(bu 2
\f[B]Fenrir+4\f[R]
.RS 2
\f[B]Rogue information:\f[R] Eight neighboring cells, clockwise from
north
.RE
.IP \(bu 2
\f[B]Fenrir+5\f[R]
.RS 2
\f[B]Rogue information:\f[R] Visible monsters and their positions
relative to you
.RE
.IP \(bu 2
\f[B]Fenrir+6\f[R]
.RS 2
\f[B]Rogue information:\f[R] Visible objects and landmarks, with
relative positions
.RE
.PP
These explicit reads include their region names.
Names are supported by the shared application\-region API, so other
overrides can use them as needed.
\f[B]Fenrir+Shift+B\f[R] lists the assignments.
Slots 7 through 10 remain available for manual regions.
Existing user regions are preserved while the override is active and
restored when it ends, as with Ninjam.
.PP
Directions give cell offsets, for example \(lqbat, north 2, east 3.\(rq
Descriptions use only displayed symbols; they do not reveal hidden
monsters, secret doors, or unidentified items.
Blank cells are described as unseen, and hallucination or disguised
monsters can make the displayed symbols misleading.
The playfield uses the first 24 rows and 80 columns even in a larger
terminal, with status on row 24.
Inventory, help, and options pages use ordinary reading and review; map
regions report information unavailable on those pages.
Slow inventory uses the ordinary message region.
Read Screen, review, and copying retain the actual terminal text.
Unrecognized screens return to ordinary reading.
.PP
Developers can exercise an installed classic Rogue in private PTYs
without touching the active reader:
.IP
.EX
FENRIR_ROGUE_TEST_BINARY=/usr/bin/rogue go test ./internal/terminal \-run TestRogueLiveOverride \-v
.EE
.SS Codex CLI
The \f[B]Codex\f[R] override replaces automatic terminal diffs with
completed assistant messages.
It suppresses tool output, streaming fragments, and redraws.
Manual screen review remains available, and typing echo is limited to
the composer.
Messages are retained in memory even while speech is muted or automatic
reading is disabled.
Existing lifecycle alerts remain separate from reply reading.
Left/Right navigation retains character feedback inside the composer.
While Codex is working, the existing activity tone sounds once every
four seconds without requiring redraws.
It stops for approval/question waits and completion, respects the sound
and progress toggles, and remains independent of speech mute.
.IP \(bu 2
\f[B]Fenrir+1 through Fenrir+9\f[R]
.RS 2
\f[B]Codex information:\f[R] Recent completed assistant messages, newest
first
.RE
.IP \(bu 2
\f[B]Fenrir+0\f[R]
.RS 2
\f[B]Codex information:\f[R] Working, ready, waiting for approval or an
answer, finished, or interrupted
.RE
.PP
Select \f[B]Codex\f[R] with \f[B]Fenrir+A\f[R], type \f[B]c\f[R], then
Enter.
Select \f[B]Default\f[R] to leave the override.
Without its bridge, the override suppresses automatic screen changes and
the status shortcut says \f[B]Waiting for Codex bridge\f[R].
.PP
The optional bridge requires Python 3 and Fenrir remote command control
enabled.
Merge a command hook invoking
\f[CR]python3 /absolute/path/to/fenrir/tools/codex_bridge.py\f[R] into
each of these events in \f[CR]\(ti/.codex/hooks.json\f[R]:
\f[CR]SessionStart\f[R], \f[CR]UserPromptSubmit\f[R],
\f[CR]PermissionRequest\f[R], \f[CR]PostToolUse\f[R], \f[CR]Stop\f[R],
\f[CR]Interrupt\f[R], and \f[CR]SessionEnd\f[R].
For example, one event entry is:
.IP
.EX
{
  \(dqhooks\(dq: {
    \(dqSessionStart\(dq: [{\(dqhooks\(dq: [{\(dqtype\(dq: \(dqcommand\(dq, \(dqcommand\(dq: \(dqpython3 /absolute/path/to/fenrir/tools/codex_bridge.py\(dq, \(dqtimeout\(dq: 3}]}]
  }
}
.EE
.PP
Preserve existing hooks.
Review and trust the added hooks through Codex\(cqs \f[CR]/hooks\f[R]
interface; restart or resume Codex if required by the installed version.
Starting or resuming a conversation starts a detached bridge follower;
submitting a prompt also restarts it if necessary.
The bridge never speaks or answers approvals.
.PP
The follower reads only the transcript path supplied by that
conversation\(cqs hook and verifies its session identifier.
It accepts completed assistant events, never tool results, reasoning, or
streamed deltas.
It keeps the nine latest replies in memory and writes only status,
conversation identifiers, and lock files to a private runtime directory.
Switching conversations replaces the terminal binding; packets from an
older conversation cannot overwrite the new history.
Existing history is loaded silently on attachment or bridge restart.
Long replies are transported in chunks and announced only after
assembly; the current per\-message limit is 1 MiB.
The worker stops when Codex exits or a \f[CR]SessionEnd\f[R] hook runs.
.PP
X11 routing requires the same \f[CR]WINDOWID\f[R] as the Fenrir
instance; Linux console routing uses Codex\(cqs controlling VT and the
reader\(cqs existing authorization.
Other windows and consoles do not receive the replies.
This local bridge does not forward SSH audio or attach a remote Codex
server to a local terminal.
.PP
The transcript parser was checked against Codex CLI 0.165.0.
It uses Codex\(cqs local completed\-event records, rather than a public
subscription API; a changed record format may require an update.
Status comes from hooks and recorded turn events, not the terminal\(cqs
animated activity label.
Check \f[B]Fenrir+0\f[R] after resuming.
.PP
For a private protocol and keyboard test without live speech or Codex
requests:
.IP
.EX
go build \-o fenrir ./cmd/fenrir
python3 \-m unittest discover \-s tests \-p test_codex_bridge.py
xvfb\-run \-a env FENRIR_PRIVATE_X11=1 python3 tests/native_codex.py
.EE
.PP
Real acceptance still needs a Codex reply spoken once after completion,
working status on demand, history review, composer typing,
approval/question handling, and returning to ordinary reading after
choosing Default or exiting Codex.
.SS Clipboard
Use review navigation to place two marks around text with
\f[B]Fenrir+X\f[R], then press \f[B]Fenrir+C\f[R] to copy it.
In table mode Fenrir+X sets headers instead.
.IP \(bu 2
\f[B]Fenrir+Shift+X\f[R]
.RS 2
\f[B]Action:\f[R] Read marked text
.RE
.IP \(bu 2
\f[B]Fenrir+Control+Shift+X\f[R]
.RS 2
\f[B]Action:\f[R] Remove marks
.RE
.IP \(bu 2
\f[B]Fenrir+C\f[R]
.RS 2
\f[B]Action:\f[R] Copy marked text
.RE
.IP \(bu 2
\f[B]Fenrir+Control+C\f[R]
.RS 2
\f[B]Action:\f[R] Copy last presented text
.RE
.IP \(bu 2
\f[B]Fenrir+Shift+C\f[R]
.RS 2
\f[B]Action:\f[R] Read selected clipboard
.RE
.IP \(bu 2
\f[B]Fenrir+Control+Shift+C\f[R]
.RS 2
\f[B]Action:\f[R] Clear selected clipboard
.RE
.IP \(bu 2
\f[B]Fenrir+Home / End\f[R]
.RS 2
\f[B]Action:\f[R] First / last clipboard
.RE
.IP \(bu 2
\f[B]Fenrir+PageUp / PageDown\f[R]
.RS 2
\f[B]Action:\f[R] Previous / next clipboard
.RE
.IP \(bu 2
\f[B]Fenrir+V\f[R]
.RS 2
\f[B]Action:\f[R] Paste selected clipboard
.RE
.IP \(bu 2
\f[B]Fenrir+F5 / F6\f[R]
.RS 2
\f[B]Action:\f[R] Import from / export to file
.RE
.IP \(bu 2
\f[B]Fenrir+F7 / F8\f[R]
.RS 2
\f[B]Action:\f[R] Import from / export to X clipboard
.RE
.PP
\f[CR]clipboard.number_of_clipboards\f[R] limits history; the default is
200.
\f[CR]clipboard.export_path\f[R] selects the import/export file,
initially \f[CR]/tmp/fenrirClipboard\f[R].
\f[CR]clipboard.sync\f[R] enables automatic X clipboard synchronization,
which requires \f[CR]xclip\f[R] and access to the X display.
.PP
Persistent history is optional and off by default.
Set \f[CR]clipboard.persistent\f[R] to retain unencrypted history across
launches.
Terminal sessions use
\f[CR]\(ti/.local/state/fenrir/clipboard/terminal.json\f[R]; console
sessions use \f[CR]/var/lib/fenrir/clipboard/tty.json\f[R].
Same\-user readers of the same mode share persistent history.
.SS Spell checking and emoji
Automatic spell checking uses Enchant 2 and a dictionary matching the
session language.
Reading settings control word repetition, spoken misspelling feedback,
and misspelling sounds.
.PP
Press \f[B]Fenrir+S\f[R] to open the Spellcheck Menu for the current
word.
The Suggestions tab lets you edit the word and choose a suggested
spelling.
The Exceptions tab lets you add words, remove selected entries with
Delete, and undo a removal.
Selecting a suggestion copies it to Fenrir\(cqs clipboard; paste it with
Fenrir+V.
.PP
Press \f[B]Fenrir+Control+E\f[R] to open the Emoji Menu.
Choose a category at the tab selector, then Tab to the emoji grid.
Arrows navigate, typing filters by name prefix, and Control+Backspace
clears the filter.
Enter copies the selected emoji to Fenrir\(cqs clipboard.
Escape closes the menu.
.SS Reading windows and live regions
Reading regions belong to the current terminal and last for the reader
session.
A reading window restricts automatic reading to a rectangle.
Live regions exclude changing areas from automatic speech while allowing
explicit reading and progress monitoring.
.PP
Outside table mode, place two marks with \f[B]Fenrir+X\f[R] to define
opposite corners.
Press \f[B]Fenrir+Keypad Slash\f[R] on desktop or
\f[B]Fenrir+Control+8\f[R] on laptop to set a reading window.
Press the shortcut twice quickly to clear it.
.PP
To create a live region, place one mark for the rest of that line, or
two marks for a rectangle, then press \f[B]Fenrir+B\f[R].
Fenrir assigns the first free slot, up to ten.
Region creation clears the marks.
.IP \(bu 2
\f[B]Fenrir+1\f[R] through \f[B]Fenrir+0\f[R] read live regions 1
through 10.
.IP \(bu 2
\f[B]Fenrir+Shift+1\f[R] through \f[B]Fenrir+Shift+0\f[R] clear
individual live regions.
.IP \(bu 2
\f[B]Fenrir+Shift+B\f[R] lists the current reading regions.
.IP \(bu 2
\f[B]Fenrir+Control+B\f[R] clears all live regions.
.IP \(bu 2
\f[B]Fenrir+Control+Shift+B\f[R] clears both the reading window and live
regions.
.SS Sound and progress
Sound output uses \f[CR]pulse\f[R] for PulseAudio or PipeWire\(cqs
PulseAudio service, or \f[CR]alsa\f[R] for an ALSA PCM device.
Select the driver and theme in Sound settings.
The ALSA device name is set with \f[CR]presentation.sound.device\f[R] in
the file.
.PP
Speech Dispatcher has its own synthesis and audio configuration,
separate from Fenrir\(cqs sound cues.
For an X11 terminal session, run \f[CR]./fenrir \-x\f[R] as your regular
user.
With sudo, Fenrir uses \f[CR]SUDO_UID\f[R] to locate the invoking
user\(cqs PulseAudio socket.
The default sound driver tries the user session, then
\f[CR]/tmp/pulse.sock\f[R], then \f[CR]/run/pulse/native\f[R].
Set \f[CR]PULSE_SERVER\f[R] to select an explicit server; the sound
driver does not read PulseAudio\(cqs \f[CR]client.conf\f[R].
The sound service must already be running and accessible to the reader.
See Speech synthesizers for Speech Dispatcher addresses and autostart
behavior.
.PP
If root sound needs additional configuration, the checkout includes
configure_pulse.sh for PulseAudio and configure_pipewire.sh for
PipeWire.
Read the appropriate script before running it.
Each has a regular\-user part and a root part, and writes audio
configuration files.
The PulseAudio script replaces the user\(cqs \f[CR]default.pa\f[R] and
configures an anonymously accessible socket at
\f[CR]/tmp/pulse.sock\f[R].
The PipeWire script also changes WirePlumber settings.
These scripts change system audio configuration and are only needed when
the existing audio setup does not provide the required access.
.PP
For ALSA, select \f[CR]driver = \(dqalsa\(dq\f[R] under
\f[CR][presentation.sound]\f[R] in \f[CR]settings.toml\f[R] and set
\f[CR]device\f[R] to the desired PCM name, such as
\f[CR]\(dqdefault\(dq\f[R].
Driver and device changes apply at the next launch.
.PP
Personal themes are searched under
\f[CR]\(ti/.local/stormux/fenrir/sounds/\f[R] before bundled and system
themes.
A theme contains WAV files and \f[CR]soundicons.toml\f[R].
.PP
Progress tones are controlled separately from speech and automatic
reading.
Press \f[B]Keypad Plus\f[R] on desktop or \f[B]Fenrir+Shift+P\f[R] on
laptop to toggle them.
Fenrir recognizes percentages, fractions, progress bars, and activity
indicators; tones rise with progress.
Startup behavior is set by \f[CR]presentation.progress.enabled\f[R].
.SS Configuration files
Settings are TOML.
The annotated settings.toml lists all available options.
Fenrir loads one settings file rather than merging files.
.IP \(bu 2
Regular users: first
\f[CR]\(ti/.local/share/stormux/fenrirscreenreader/settings/settings.toml\f[R],
then \f[CR]/etc/fenrirscreenreader/settings/settings.toml\f[R].
.IP \(bu 2
Root: \f[CR]/etc/fenrirscreenreader/settings/settings.toml\f[R].
.IP \(bu 2
\f[CR]\-\-config PATH\f[R]: use that file explicitly.
.PP
If default files are absent, Fenrir uses built\-in defaults.
Python \f[CR]settings.conf\f[R] files are ignored.
Regular users save to their personal TOML file, including when startup
loaded system defaults; root saves to the system file.
\f[CR]\-\-config PATH\f[R] explicitly selects both the load and save
path, and that file must exist at startup.
.PP
Create a personal settings file and validate it without opening devices:
.IP
.EX
\&./fenrir \-\-write\-config \(ti/.local/share/stormux/fenrirscreenreader/settings/settings.toml
\&./fenrir \-\-config \(ti/.local/share/stormux/fenrirscreenreader/settings/settings.toml \-\-check\-config
.EE
.PP
Named keyboard layouts are searched in the regular user\(cqs
\f[CR]\(ti/.local/share/stormux/fenrirscreenreader/keyboard/\f[R], then
\f[CR]/etc/fenrirscreenreader/keyboard/\f[R], then
\f[CR]config/keyboard/\f[R] beside the binary.
Root searches the system and bundled locations.
An explicit TOML path selects one file.
Custom layouts replace the complete layout; they are not overlays.
See the keyboard guide for an example.
.SS Speech synthesizers
The default driver is \f[CR]speech\-dispatcher\f[R].
Select its module, language, and voice in Speech settings; empty values
use server defaults.
.PP
Fenrir uses \f[CR]SPEECHD_ADDRESS\f[R] when set:
\f[CR]unix_socket:/absolute/path\f[R] selects a Unix socket, and
\f[CR]inet_socket:HOST:PORT\f[R] selects TCP (default host
\f[CR]127.0.0.1\f[R], port \f[CR]6560\f[R]).
Invalid addresses report an error.
Otherwise, \f[CR]SPEECHD_SOCKET\f[R] selects a Unix socket.
Without either variable, Fenrir uses
\f[CR]$XDG_RUNTIME_DIR/speech\-dispatcher/speechd.sock\f[R], falling
back to \f[CR]$XDG_CACHE_HOME/speech\-dispatcher/speechd.sock\f[R] or
\f[CR]\(ti/.cache/speech\-dispatcher/speechd.sock\f[R] when the runtime
directory is unset.
With sudo, the default remains
\f[CR]/run/user/$SUDO_UID/speech\-dispatcher/speechd.sock\f[R].
Sudo may remove address variables; preserve them explicitly if needed.
.PP
When opening speech, Fenrir first tries the selected server.
If its socket is missing or refuses connections, Fenrir requests
\f[CR]speech\-dispatcher \-\-spawn\f[R] and briefly retries.
The daemon\(cqs configuration controls whether spawning is allowed.
\f[CR]SPEECHD_CMD\f[R] can select another executable.
Autostart is limited to Unix sockets and local loopback TCP servers.
When sudo changes the account, start Speech Dispatcher as the invoking
user first; Fenrir will not launch a root\-owned daemon for that user.
Settings discovery never starts a daemon or interrupts the active
speaking client.
.PP
Hardware driver IDs are \f[CR]dectalk\f[R], \f[CR]dectalk\-usb\f[R],
\f[CR]litetalk\f[R], \f[CR]doubletalk\f[R], and \f[CR]tripletalk\f[R].
Serial drivers require \f[CR]presentation.speech.hardware_device\f[R],
for example \f[CR]/dev/ttyUSB0\f[R], and default to 9600 baud when
\f[CR]hardware_baud_rate = 0\f[R].
DoubleTalk support targets the external LT device.
TripleTalk USB devices need to expose a serial tty.
.PP
Native \f[CR]dectalk\-usb\f[R] uses libusb 1.0 and ignores serial
settings.
The process needs access to the device.
The Speech form\(cqs \f[B]Test synthesizer\f[R] button previews hardware
choices before saving.
Driver and port changes apply at launch.
.SS Script shortcuts
Fenrir searches \f[CR]\(ti/.local/stormux/fenrir/\f[R], the configured
\f[CR]general.script_path\f[R] (default
\f[CR]/usr/share/fenrirscreenreader/scripts\f[R]), and the bundled
\f[CR]config/scripts/\f[R] beside the binary.
Earlier directories take priority.
.PP
A filename such as \f[CR]example__\-__key_y.sh\f[R] assigns the script
key plus Y. The script key defaults to Compose and is configured by
\f[CR]general.script_keys\f[R].
Scripts must be executable to run.
Fenrir invokes them directly and passes the current account name as the
first argument.
Commands appear in the tutorial\(cqs script list.
.SS Remote control
Unix socket remote control is enabled by default.
The standard socket is \f[CR]/tmp/fenrirscreenreader\-daemon.sock\f[R],
and instances also have private sockets
\f[CR]/tmp/fenrirscreenreader\-<pid>.sock\f[R].
Set \f[CR]remote.socket_file\f[R] for a custom socket.
.PP
Use \f[CR]ls\f[R] to discover instances.
Use a private socket to address one reader:
.IP
.EX
echo \(dqls\(dq \f[B]|\f[R] socat \- UNIX\-CLIENT:/tmp/fenrirscreenreader\-daemon.sock
echo \(dqcommand say Hello\(dq \f[B]|\f[R] socat \- UNIX\-CLIENT:/tmp/fenrirscreenreader\-daemon.sock
echo \(dqcommand interrupt\(dq \f[B]|\f[R] socat \- UNIX\-CLIENT:/tmp/fenrirscreenreader\-daemon.sock
echo \(dqsetting set reading#mode=highlight\(dq \f[B]|\f[R] socat \- UNIX\-CLIENT:/tmp/fenrirscreenreader\-daemon.sock
.EE
.PP
Remote requests use \f[CR]section#setting=value\f[R] syntax
independently of TOML.
Remote speech rate, pitch, and volume use \f[B]0.0 to 1.0\f[R], mapped
to the \-100 to 100 scale used in settings files and menus.
For example, \f[CR]speech#rate=0.8\f[R] selects rate 60.
.PP
Other supported operations include:
.IP \(bu 2
\f[CR]command tempdisablespeech\f[R]: temporarily silence speech.
.IP \(bu 2
\f[CR]command clipboard TEXT\f[R]: add text to the clipboard.
.IP \(bu 2
\f[CR]command exportclipboard\f[R]: export the selected clipboard.
.IP \(bu 2
\f[CR]command application ID\f[R]: select \f[CR]default\f[R],
\f[CR]networkmanager\f[R], \f[CR]ninjam\f[R], \f[CR]rogue\f[R], or
\f[CR]codex\f[R] for this reader\(cqs active terminal, like Fenrir+A.
This requires command remote control.
An empty reply means selection succeeded; invalid IDs, busy settings,
and restoration failures return an error.
Application recognition and profile loading happen later, when the
application appears; this command does not launch it.
\f[CR]default\f[R] restores ordinary settings.
Use a private socket when targeting a particular reader.
.IP \(bu 2
\f[CR]command window X1 Y1 X2 Y2\f[R]: set a reading window, using
zero\-based, inclusive coordinates.
.IP \(bu 2
\f[CR]command resetwindow\f[R]: clear the window.
.IP \(bu 2
\f[CR]setting save\f[R]: save settings.
.IP \(bu 2
\f[CR]setting reset\f[R]: clear quick and remote overrides back to the
last loaded or successfully saved settings.
.IP \(bu 2
\f[CR]command quitapplication\f[R]: quit Fenrir.
.PP
Set \f[CR]remote.enabled = false\f[R] to disable the service.
Command and setting requests have separate switches,
\f[CR]enable_command_remote\f[R] and \f[CR]enable_settings_remote\f[R].
Requests are authorized against the caller\(cqs account; console
self\-voicing also allows an account logged into the active console.
.SS Command\-line options
Fenrir runs as \f[CR]fenrir [options]\f[R].
Use \f[CR]\-\-help\f[R] for the built\-in reference.
.IP \(bu 2
\f[B]\f[CB]\-\-help\f[B]\f[R]
.RS 2
\f[B]Purpose:\f[R] Show usage and options
.RE
.IP \(bu 2
\f[B]\f[CB]\-\-version\f[B]\f[R]
.RS 2
\f[B]Purpose:\f[R] Print version and release channel
.RE
.IP \(bu 2
\f[B]\f[CB]\-f\f[B]\f[R]
.RS 2
\f[B]Purpose:\f[R] Keep console mode in the foreground (always enabled
with \f[CR]\-x\f[R])
.RE
.IP \(bu 2
\f[B]\f[CB]\-x\f[B]\f[R]
.RS 2
\f[B]Purpose:\f[R] Start a shell inside this X11 terminal
.RE
.IP \(bu 2
\f[B]\f[CB]\-\-config PATH\f[B]\f[R]
.RS 2
\f[B]Purpose:\f[R] Load a specific TOML settings file
.RE
.IP \(bu 2
\f[B]\f[CB]\-\-keyboard\-layout NAME_OR_PATH\f[B]\f[R]
.RS 2
\f[B]Purpose:\f[R] Select a named layout or TOML file
.RE
.IP \(bu 2
\f[B]\f[CB]\-\-punctuation\-profile NAME_OR_PATH\f[B]\f[R]
.RS 2
\f[B]Purpose:\f[R] Select a punctuation profile
.RE
.IP \(bu 2
\f[B]\f[CB]\-\-check\-config\f[B]\f[R]
.RS 2
\f[B]Purpose:\f[R] Validate settings, layout, and punctuation without
opening devices
.RE
.IP \(bu 2
\f[B]\f[CB]\-\-write\-config PATH\f[B]\f[R]
.RS 2
\f[B]Purpose:\f[R] Write effective settings to a file and exit
.RE
.IP \(bu 2
\f[B]\f[CB]\-\-speech\-driver ID\f[B]\f[R]
.RS 2
\f[B]Purpose:\f[R] Override the configured speech driver
.RE
.IP \(bu 2
\f[B]\f[CB]\-\-speech\-rate NUMBER\f[B]\f[R]
.RS 2
\f[B]Purpose:\f[R] Override rate, from \-100 to 100
.RE
.IP \(bu 2
\f[B]\f[CB]\-\-speech\-module NAME\f[B]\f[R]
.RS 2
\f[B]Purpose:\f[R] Select a Speech Dispatcher module
.RE
.IP \(bu 2
\f[B]\f[CB]\-\-input\-device PATH\f[B]\f[R]
.RS 2
\f[B]Purpose:\f[R] Select a console keyboard event device; may be
repeated
.RE
.IP \(bu 2
\f[B]\f[CB]\-\-debug\-file PATH\f[B]\f[R]
.RS 2
\f[B]Purpose:\f[R] Append timing and reader\-decision diagnostics
.RE
.SS Troubleshooting
.SS Speech or sound is missing
Check that speech and sound are enabled, and that the selected backend
is available.
Speech Dispatcher needs a configured synthesizer.
Pulse output needs access to a running PulseAudio service, including
PipeWire\(cqs PulseAudio service; ALSA needs access to its selected PCM
device.
Root console sessions may need separate audio configuration; see the
README\(cqs setup section.
.PP
For hardware speech, check the driver, device path, device permissions,
and serial baud rate.
Use \f[B]Test synthesizer\f[R] before saving a new hardware selection.
.SS Keyboard input or X11 mode fails
In console mode, check access to keyboard event devices and
\f[CR]/dev/uinput\f[R].
In X11 mode, check \f[CR]DISPLAY\f[R], \f[CR]WINDOWID\f[R], and
competing grabs on the terminal.
Use NumLock off for bare keypad review.
A configured \f[CR]keyboard.devices\f[R] list or
\f[CR]\-\-input\-device\f[R] applies to console mode and cannot be used
with \f[CR]\-x\f[R].
.SS Check configuration and collect diagnostics
Validate an edited settings file with
\f[CR]\-\-config PATH \-\-check\-config\f[R].
For reader diagnostics, add
\f[CR]\-\-debug\-file /tmp/fenrir\-debug.log\f[R] to the launch command.
This appends timing and reader decisions without screen text or key
values.
\f[CR]./fenrir \-\-version\f[R] identifies the build when reporting a
problem.
.SS Documentation maintenance and support
\f[CR]docs/user.md\f[R] is the shared manual source.
With Pandoc installed, run \f[CR]./docs/create_manpage.sh\f[R] to
regenerate \f[CR]docs/user.txt\f[R] and \f[CR]docs/fenrir.1\f[R].
The script can run from any working directory.
Edit the Markdown source rather than the generated files.
The bundled \f[CR]docs/man_tables.lua\f[R] filter renders man\-page
tables as labeled lists for narrow terminals.
.PP
Please review documentation and test instructions for the affected
workflow before submitting a change, as described in the README\(cqs
contribution policy.
.IP \(bu 2
\c
.UR https://git.stormux.org/storm/fenrir
Project repository and issue tracker
.UE \c
.IP \(bu 2
\c
.UR https://git.stormux.org/storm/fenrir/wiki
Fenrir Wiki
.UE \c
.IP \(bu 2
Email list: \f[CR]stormux+subscribe\(atgroups.io\f[R], with the subject
\f[CR]subscribe\f[R].
.IP \(bu 2
IRC: \f[CR]irc.stormux.org\f[R], channel \f[CR]#stormux\f[R].