Bible TUI Footer

Bible TUI Footer turns agent wait time into reading time. While Pi works, a focused RSVP (Rapid Serial Visual Presentation) window advances through the King James Bible one word at a time and resumes where you stopped.

Genesis 1:1 ─────────────────────────────────────────────────
   beg[i]nning
450 WPM · 1,284 words read

The highlighted letter is the word's optimal recognition position, kept at a stable terminal column to reduce eye movement.

Features

• Sequential Genesis-to-Revelation reading with lazy, single-book loading and single-verse token caching
• Left-anchored, theme-aware Focus Window above Pi's editor
• Monotonic RSVP timing with punctuation, long-word, and verse-boundary pauses
• Serialized, atomic progress persistence across projects and Pi sessions
• Responsive one-line rendering in narrow terminals
• Entirely local and offline
• Effect v4 state, schema validation, typed errors, persistence, timing, and fiber lifecycle

Install

From npm:

pi install npm:bible-tui-footer

From git:

pi install git:github.com/rickyeescobar/bible-tui-footer

From a local checkout:

pnpm install
pi install /absolute/path/to/bible-tui-footer

For a temporary development run:

pi -e ./extensions/index.ts

Add -l to any pi install to write the package to project settings (.pi/settings.json) instead of user settings.

Bible TUI Footer starts automatically when an agent starts and disappears when the agent settles.

Commands

/bible status
/bible on
/bible off
/bible speed 500
/bible goto John 1:1
/bible restart

Speed is constrained to 100–1,200 WPM. The default is 450 WPM.

State

Progress is stored at:

$XDG_STATE_HOME/bible-tui-footer/progress.json

If XDG_STATE_HOME is unset, Bible TUI Footer uses:

~/.local/state/bible-tui-footer/progress.json

Writes are atomic and occur when the agent settles, the session shuts down, or a command changes progress.

Development

Bible TUI Footer supports the same Node.js range as Pi (22.19 or later) and is developed against Node 24 LTS, pnpm 11.15, TypeScript 7, and Effect 4 beta. The checked-in .nvmrc is an optional convenience for contributors who use nvm.

pnpm install
pnpm check
pnpm test

The extension ships as TypeScript source with no build step: Pi loads extensions/index.ts directly and installs the runtime dependencies itself. The generated scripture data is included in the package; users do not need to build it. Maintainers can regenerate it from a normalized JSON export derived from the Project Gutenberg text:

pnpm build:data -- input.json data

Scripture import format

The import file must contain a non-empty verses array with one object per verse:

{
  "verses": [
    {
      "book": "Genesis",
      "chapter": 1,
      "verse": 1,
      "text": "In the beginning God created the heaven and the earth."
    },
    {
      "book": "Genesis",
      "chapter": 1,
      "verse": 2,
      "text": "And the earth was without form, and void..."
    }
  ]
}

book and text must be non-empty strings; chapter and verse must be positive integers. Entries should be in canonical Bible order and verse order. The first appearance of each book determines its order in the generated manifest. Gutenberg's raw text must be parsed into this normalized representation before running the import.

The importer validates the input with Effect Schema, groups verses into per-book files, and calculates book offsets, verse totals, and the global word count.

Architecture

• extensions/index.ts — thin Pi lifecycle and synchronous rendering adapter
• src/command.ts — the /bible grammar: a BibleCommand tagged enum and a parser that fails syntax errors as typed UsageErrors
• src/controller.ts — FooterController service and Layer owning playback lifecycle, command handling, and persistence policy
• src/domain.ts — Effect Schema classes and immutable Data classes
• src/reader.ts — single-book/verse caching and an Effect SynchronizedRef/Option/Data reader state machine
• src/playback.ts — monotonic deadlines and scope-managed Effect fiber playback
• src/progress.ts — schema-validated persistence through Effect FileSystem
• src/files.ts — scoped temporary resources and atomic file replacement
• src/rsvp.ts — tokenization, pivot placement, and timing policy
• src/view.ts — pure responsive Focus Window renderer
• data/manifest.json — schema-validated book offsets and precomputed totals
• data/books/ — compact, lazily loaded book data

All persisted and bundled JSON is decoded and encoded with Effect Schema. Domain errors use Schema.TaggedErrorClass; validated records use Schema.Class; trusted internal aggregates use Data.Class. A BibleLibrary service and Layer capture filesystem access and load only the active book. A FooterController service layered on top owns all application state — reader, playback handle, and persistence/playback locks — and returns notices as values, with host side-effects injected as hooks. Its Layer resolves the progress path from XDG_STATE_HOME through Effect Config, so tests can rebind it with a ConfigProvider. Pi requires synchronous render() methods and Promise-returning event callbacks, so a ManagedRuntime builds the controller layer once and bridges it at that imperative boundary. Effect tests use @effect/vitest, scoped resources, and TestClock.

Scripture data

The bundled text is derived from the Project Gutenberg King James Version. See NOTICE for its exact source and jurisdiction-specific redistribution considerations.

License

The software is available under the MIT License. Scripture text rights and provenance are addressed separately in NOTICE.