txtui

A terminal (TUI) reader for .txt novels written in Python, built on Textual.

Designed for Chinese text novels: it auto-detects UTF-8/GBK encoding, helps you match a single-level chapter outline with presets or a custom regex, and remembers your reading position and time spent in each book.

Features

• Recent list — open txtui with no arguments to pick a book from your reading history, sorted by most recently closed
• Chapter outline — outline on the left (25%) vs. content on the right (75%), flat chapter list that highlights and auto-scrolls to the current chapter
• Preset chapter matching — 章体 (第X章), 节体 (第X节), and 自定义 (custom regex)
• Custom regex matching — validate your own regex, with feedback when it matches no chapters
• Encoding handling — auto-detects UTF-8 vs. GBK; for GBK it asks before converting the file in place to UTF-8
• Reading state — per-book position (chapter + line), timestamps, accumulated reading time, and chapter config, persisted to JSON
• Configurable location — data directory via --data-dir

Requirements

• Python 3.10+

Installation

uv sync

Run from the checkout:

uv run txtui /path/to/novel.txt

Or install into your environment and use the txtui command:

uv pip install -e .
txtui /path/to/novel.txt

Usage

txtui [-d/--data-dir PATH] [target.txt]

Example:

txtui my_novel.txt

First time opening a book

1. Its encoding is checked (UTF-8 first, then GBK). If it is GBK you are asked whether to convert it to UTF-8 in place.
2. A full-screen preview shows the text with line numbers. You can flip pages with space, scroll lines with j/k.
3. Press Enter to set up the chapter outline: choose a preset (章体/节体/自定义), or type your own regex.
4. If a valid outline already exists for the book (or you finish configuring), you land in the reader.

Keybindings

Recent list

Chapter config screen

Reader — content mode

Reader — outline mode

Entered with esc. Press esc again to return to the content at your previous spot.

Dialogs

Data layout

By default state is stored in ~/.local/share/txtui/state.json and looks like:

{
  "records": {
    "/abs/path/novel.txt": {
      "path": "/abs/path/novel.txt",
      "title": "小说名",
      "encoding": "utf-8",
      "chapter_config": {
        "level1_pattern": "^\\s*第[一二三四五六七八九十百千\\d]+章",
        "preset_name": "章体"
      },
      "chapter_index": 2,
      "line": 48,
      "last_read": 1721800000.0,
      "total_reading_time": 3600.0
    }
  }
}

Override its location with --data-dir.

Development

uv run pytest          # run the test suite
uv run python -m txtui # launch the app

License

MIT