A powerful Terminal User Interface (TUI) application for creating, editing, and managing HyperLists - a methodology for describing anything in a hierarchical, structured format.
HyperList is a universal methodology for describing anything - any state, item, pattern, action, process, transition, program, instruction set, etc. It can be used as an outliner, a todo list handler, a process design tool, a data modeler, or any other way you want to describe something.
Learn more about the HyperList methodology at: https://isene.org/hyperlist/
For historical context and the original VIM implementation, see: hyperlist.vim
- Ampersand support: Properties like "Day 1 & 2:" now color correctly
- Chained properties: Lines like "09.03: Silje: Opening" now color the entire "09.03: Silje:" chain red
- Faster navigation: File change detection now runs every 2 seconds instead of on every keypress
- Improved responsiveness when holding DOWN/UP keys
- Fixed invisible cursor on blank separator lines in help (?) and documentation (??) viewers
- Presentation mode state now properly preserved when entering/exiting viewers
- Dynamic folding: Presentation mode now works like hyperlist.vim - folds/unfolds dynamically as you navigate
- Cursor preservation: Entering presentation mode (C-P) stays on the current item instead of jumping to the first line
- Proper navigation: Moving up/down reveals the path to the current item while folding everything else
- Auto-detect external changes: HyperList now monitors when the file is modified by other processes (vim, another Claude Code session, etc.)
- Reload prompt: Shows "File changed externally. Reload? (y/n)" when changes are detected
- Cursor preservation: Your cursor position is preserved after reload
- Skip option: Press 'n' to ignore external changes and continue editing
- Fixed an issue where quotes inside parentheses (comments) like
(this is a "comment" in here)would break the cyan coloring - The entire parentheses content now stays cyan as intended
- Tag items: Press 't' to tag/untag items for batch operations
- Auto-advance: Cursor automatically moves to next item after tagging for fast consecutive tagging
- Visual feedback: Tagged items show dark blue background, lighter blue when selected
- Status indicator: Shows
[T:N]in status line with count of tagged items - Clear tags: Press 'u' to clear all tags
- Regex tagging: Press 'C-T' to tag all items matching a regex pattern
- Batch operations: Delete (D/C-D), yank (y/Y), and indent (Tab/S-Tab) work on all tagged items
- Tag consecutive or non-consecutive items, then perform operations on the entire set
- Edit in $EDITOR: Press 'E' to spawn your preferred editor (vim, nano, emacs, etc.)
- Seamless workflow: File saved automatically, editor launched, changes reloaded on exit
- Terminal management: Terminal state properly saved and restored
- Uses
$EDITORenvironment variable (defaults to vi if not set)
- Paste above: Press 'P' to paste above current item (vim-style)
- Paste below: Press 'p' to paste below current item (existing)
- Presentation mode: Moved to 'C-P' (was 'P') for consistency
- Templates: Moved to 'T' key (was 't')
- Undo: Moved to 'U' key (was 'u') - consistent with RTFM
- Intelligent tracking:
[+]indicator automatically removed when undoing back to original file state - Clean status: No false "modified" indicator after complete undo to original
- Paste multiple lines: When pasting multi-line content into item insertion prompts ('o', 'O', 'a', 'A'), each line becomes a separate item
- Visual feedback: Shows
[+N lines]indicator during multi-line paste - Smart insertion: All pasted lines inserted as siblings at the same level
- Great for importing bullet lists from PDFs, emails, or other documents
- Requires rcurses 6.1.5+
- Export to PDF:
:export pdf filename.pdf- Full LaTeX-based PDF generation - Export to LaTeX:
:export latex filename.tex- Get the LaTeX source - Professional output: Color-coded elements, table of contents, headers
- Complete HyperList support: All syntax elements rendered beautifully
- Requires: texlive-latex-base and texlive-latex-extra packages
- Yank to clipboard: 'y' and 'Y' now copy to system clipboard
- Middle-click paste: Yanked items can be pasted into other terminals
- Preserves indentation: Copied text maintains proper structure
- Configuration Lines: Add settings at the bottom of HyperList files using
((option=value, option2=value)) - Theme Support: Three color themes -
light(bright colors),normal(standard),dark(for light terminals) - Line Wrapping: Enable with
wrap=yes- wrapped lines use+prefix per HyperList spec - Line Numbers: Enable with
show_numbers=yes - Manual Configuration: Use
:set option=valueto change settings on the fly - View Settings: Use
:setto see all settings,:set optionto see one setting - Auto-apply: Settings from config lines are applied when files are loaded
- Invisible Config Lines: Config lines are stored but never displayed in the editor
- Persistent Settings: All
:setcommands automatically update the config line in the file
theme- Color theme: light, normal, or darkwrap- Line wrapping: yes or noshow_numbers- Show line numbers: yes or nofold_level- Default fold level: 0-99 (0=all folded, 99=all open)auto_save- Enable auto-save: yes or noauto_save_interval- Auto-save frequency in secondstab_width- Indentation width: 2-8 spaces
Example config line: ((theme=dark, wrap=yes, fold_level=2))
Add a configuration line at the bottom of any HyperList file:
My HyperList
Item 1
Item 2
((fold_level=2, theme=light))
Use :set commands while editing:
:set # Show all current settings
:set fold_level # Show current fold level
:set fold_level=3 # Set fold level to 3
:set theme=dark # Switch to dark theme
:set wrap=yes # Enable line wrapping
All :set commands automatically update the file's configuration line.
- Save as Template: Save any HyperList document as a reusable template (
:st) - Template Manager: List and delete your custom templates (
:lt,:dt) - Enhanced Template Browser: Shows both built-in and user templates
- Template Metadata: Includes description and creation date
- Templates stored in
~/.hyperlist/templates/for easy backup and sharing
- File-level encryption for sensitive files (dot files like
.passwords.hl) - Line-level encryption for individual items (Ctrl-E to toggle)
- Secure AES-256-CBC encryption with PBKDF2 key derivation
- Password caching for the session
- Auto-collapse everything outside the current context
- Smart focus: Shows only current item, ancestors, and immediate children
- Visual hierarchy: Focused items in full color, others greyed out
- Improved navigation with proper cursor tracking
- Improved highlighting: Dark gray background preserves syntax colors
- Subtle selection: No more harsh reverse video
- Preserved colors: All HyperList elements maintain their colors when selected
- Hierarchical Organization: Create multi-level nested lists with unlimited depth
- Rich Syntax Highlighting: Color-coded elements for better readability
- Properties and dates in red
- Operators (AND, OR, IF, THEN) in blue
- Checkboxes in various shades of green
- References in magenta
- Hash tags in yellow/orange
- Comments in cyan
- Advanced Folding: Collapse and expand sections with multiple fold levels
- Powerful Navigation: Jump between items, references, and markers
- Full Editing Capabilities: Create, edit, delete, move, and reorganize items
- Checkbox Support: Multiple checkbox types with completion tracking
- Template System: Built-in templates plus save/load custom templates
- Presentation Mode: Focus on current item with auto-collapse
- Encryption: Protect sensitive data with AES-256 encryption
- Automatic detection: Dot files automatically prompt for encryption
- Line-level security: Encrypt individual sensitive items
- Visual indicators: Encrypted lines show lock icon
- Bold:
*text* - Italic:
/text/ - Underline:
_text_ - References:
<reference name>or<file:/path/to/file> - Hash tags:
#tag - Comments:
; comment text - Dates:
2025-08-12or2025-08-12 14:30
- PDF: Professional LaTeX-based PDF with color coding and TOC
- LaTeX: Source .tex files for customization
- HTML: Full-featured HTML with syntax highlighting
- Markdown: GitHub-flavored Markdown
- Plain Text: Clean text output
- PNG Graph: Visual representation using Graphviz
- Multiple file support with recent files list
- Autosave functionality with configurable intervals
- Split view for working with multiple lists
- Encryption support for sensitive files
- Ruby 3.0 or higher
- rcurses gem:
gem install rcurses - Optional: Graphviz for PNG export (
apt-get install graphvizorbrew install graphviz)
gem install hyperlistgit clone https://github.com/isene/HyperList.git
cd HyperList
chmod +x hyperlist
./hyperlisthyperlist # Start with empty document
hyperlist file.hl # Open existing HyperList file
hyperlist .passwords.hl # Open encrypted file (will prompt for password)
hyperlist file.txt # Open any text filej/↓- Move downk/↑- Move uph- Go to parent iteml- Go to first childg/Home- Go to topG/End- Go to bottom/- Searchn- Next search matchN- Next template marker (=)
i/Enter- Edit lineo- Insert line belowO- Insert line abovea- Insert child itemA- Insert outdented item (one level less)I- Cycle indentation size (2-5 spaces)D- Delete and yank lineC-D- Delete and yank item with descendantsy/Y- Copy line/treep- Paste belowP- Paste aboveU- UndororC-R- RedoE- Edit in $EDITOR
t- Tag/untag current itemu- Clear all tagsC-T- Tag items matching regex pattern- Operations (D/C-D, y/Y, Tab/S-Tab) work on all tagged items when tags exist
Space- Toggle foldza- Toggle all folds1-9- Expand to level0- Multi-digit fold level
v- Toggle checkboxV- Toggle checkbox with timestampC-E- Encrypt/decrypt current lineR- Go to referenceF- Open file referenceC-P- Presentation mode (with auto-collapse)T- Insert template (built-in or custom)?- Help screen
:w- Save:q- Quit:wqorW- Save and quit:e file- Open file:export pdf- Export to PDF (requires LaTeX):export latex- Export to LaTeX source:export html- Export to HTML:export md- Export to Markdown:graph- Export to PNG graph
:st- Save current document as template:dt- Delete a user template:lt- List all user templatest- Browse and insert templates
Daily Tasks
[ ] Morning review
[ ] Check emails
[ ] Review calendar
[ ] Development work
[ ] Fix bug #123
[ ] Code review
[X] Lunch break
[ ] Afternoon tasks
Save as .passwords.hl for automatic encryption:
Online Accounts
GitHub
Username: myuser
Password: [will be encrypted]
2FA: enabled
Banking
Account: 12345678
PIN: [will be encrypted]
MyProject #project
Planning Phase
[X] Define objectives
[O] Identify stakeholders
[ ] Create timeline
Implementation
Backend Development
Authentication module
Database schema
REST endpoints
Frontend Development
Login page
Dashboard
Documentation
Technical docs
User manual
Team Meeting 2025-08-12 14:00
Participants
John (PM)
Sarah (Dev)
Mike (Design)
Discussion Points
Sprint planning <Sprint-23>
Bug review <file:./bugs.hl>
Design updates
; Mike will share mockups
Action Items
[ ] John: Update roadmap
[ ] Sarah: Fix critical bugs
[ ] Mike: Finalize designs
The application stores configuration in ~/.hyperlist/:
recent_files.txt- List of recently opened filesmarks.yml- Saved marks across sessionscommand_history- Command history for:commandstemplates/- User-defined templates
Each HyperList file can have its own configuration line at the bottom:
((option=value, option2=value))
This configuration line is:
- Automatically applied when the file is loaded
- Updated when you use
:setcommands - Invisible in the editor (not displayed as content)
- Preserved when saving the file
Available options:
theme- light/normal/darkwrap- yes/noshow_numbers- yes/nofold_level- 0-99auto_save- yes/noauto_save_interval- secondstab_width- 2-8
Run the included test suite:
./hyperlist test.hlFollow the instructions in the test file to verify all features are working correctly.
Contributions are welcome! Please feel free to submit issues and pull requests.
- Fixed: Critical navigation bug where the last item (line 154 in test.hl) was not reachable when pressing 'G'
- Fixed: Improved scrolling behavior to properly handle wrapped lines using rcurses built-in capabilities
- Fixed: Split view navigation - g/G/Home/End/PgUp/PgDown now correctly affect the active pane
- Added: Wrap-around navigation in split view right pane (UP from first goes to last, DOWN from last goes to first)
- Added: Visual end-of-document indicator (blank line at bottom) for better UX
- Improved: Scroll calculations now dynamically account for line wrapping
- Added encryption support for sensitive documents
- Enhanced presentation mode
- Various bug fixes and improvements
This software is released into the Public Domain.
Created by Geir Isene - https://isene.org
Based on the HyperList methodology and inspired by the original hyperlist.vim plugin.
- The rcurses library for excellent terminal UI capabilities
- The Ruby community for a wonderful programming language
- All contributors and users of HyperList
For more information about HyperList, visit https://isene.org/hyperlist/