HalpTask 🚀

A high-performance, keyboard-driven Terminal User Interface (TUI) bullet point outliner & task manager for Vim users. Written in Go and Bubble Tea, storing tasks in human-readable Markdown files with AES-256 encryption support.

---

📸 Screenshots & Showcase

⌨️ WhichKey Leader Popup & Config Dashboard

 

---

⚡ Quick Install (macOS, Linux & Windows)

Warning

⚠️ SECURITY WARNING: Never trust install scripts blindly! Always inspect the source code before running remote scripts piped into your shell. You can inspect the installer source code at scripts/install.sh (or scripts/install.ps1 for PowerShell).

Install the latest halptask binary automatically for your OS and architecture:

curl -fsSL https://raw.githubusercontent.com/halpworld/halptask/main/scripts/install.sh | bash

For native Windows PowerShell:

irm https://raw.githubusercontent.com/halpworld/halptask/main/scripts/install.ps1 | iex

---

📚 Documentation & GitHub Wiki

Comprehensive guides and persona workflows are documented in our GitHub Wiki:

• 🚀 Getting Started Guide: 5-minute quickstart, installation, and core concepts.
• 👥 User Personas & Workflows: Tailored workflows for Programmers, DevOps/SRE, Product Managers, Lawyers, and Knowledge Workers.
• ⚡ Power User Guide: Vim motion combos, subtree hoisting (ff), tag inheritance, and shell integration.
• 🔒 Configuration & Security: Config options, theme palettes, and AES-256-GCM encryption architecture.
• ⌨️ Keybindings Cheatsheet: Full interactive Leader Key (<space>) map and Vim shortcuts.
• 🤖 Agent Maintenance Guidelines: Protocols for future AI agents to maintain documentation.

---

✨ Features

• Vim Native Keybindings: Native Vim navigation (j, k, h, l, gg, G, oo, oc, O, dd, x, u, ctrl+r, tab, shift+tab).
• Leader Menu (<space>): Leader key popup window displaying all available shortcuts non-intrusively.
• Dynamic WhichKey Popup: Visual popup updates as you type key prefixes for Leader options (<space> b, <space> t, <space> z, <space> e) as well as all multi-character Vim prefixes (o, d, z, g, w, f).
• Bullet & Task Management:
  • Convert any bullet point into a task with checkbox statuses.
  • Todo: [ ] (Gray empty box)
  • In Progress: [~] (Orange ~ indicator)
  • Done: [x] (Green X checkmark with faint strikethrough text styling)
• Task Tags & Labels 🏷️:
  • Assign direct tags (T or <space> t a) with emojis and customizable colors.
  • Subtasks dynamically inherit parent tags ([↖🔥 urgent]). Unindenting/moving subtasks automatically cleans up inherited tags.
  • Plain text Markdown storage as #tagname.
• Focus Mode & Top Focus Banner 🎯:
  • Quickly mark any task or task group as your active focus item (fo / tf / <space> t f), and exit focus mode instantly with Esc or q.
  • Highlights focused tasks with vivid 🎯 FOCUS badges, bold cyan text, and subtle subtask group focus indicators.
  • Renders a top Focus Banner pane with task context path and attached note previews for instant visibility.
• Task Archiving 📦:
  • Archive selected bullet/task subtrees (<space> a a) or sweep all completed tasks (<space> a c).
  • Gzip-compressed and AES-256-GCM encrypted storage (archive.dat) for minimal disk usage and long-term schema compatibility.
  • Interactive Archive Browser modal (<space> a v / <space> a r) to filter, inspect, restore (r), or permanently delete (d).
• Task Notes & Internal Task Linking 📝:
  • Attach rich Markdown notes (N or <space> n or <space> t n) to any task/bullet point.
  • Built-in rendered view mode with styled headings, bullet lists, quotes, and code blocks.
  • Internal cross-task links (#123, [Label](#123), [Label](123), task:123) with keyboard link navigation (Tab/Shift+Tab) and instant jump (Enter).
  • Visual 📝 note indicator displayed in the tree view for items with notes.
• Hierarchical Folding:
  • Collapse (zc, h), Expand (zo, l), Toggle (za), Close All (zM), Open All (zR).
  • Child count badges for collapsed subtrees (▶ [3]).
• Plain Text & Encryption:
  • Data stored in clean human-readable Markdown format by default (~/.config/halptask/data.txt).
  • AES-256-GCM + PBKDF2 encryption mode for secure task storage.
• Cross Platform Support:
  • Binaries built for macOS, Linux, and Windows (amd64 and arm64).
• Customizable Configuration:
  • Configured via ~/.config/halptask/config.yaml.

---

📦 Alternative Installation Methods

🍺 Homebrew (macOS & Linux)

Install via Homebrew tap:

brew install halpworld/tap/halptask

Standalone Binary Download

Download direct executable binaries for your OS and Architecture directly from GitHub Releases:

# macOS (Apple Silicon arm64)
curl -LO https://github.com/halpworld/halptask/releases/latest/download/halptask_Darwin_arm64
chmod +x halptask_Darwin_arm64 && sudo mv halptask_Darwin_arm64 /usr/local/bin/halptask

# Linux (x86_64)
curl -LO https://github.com/halpworld/halptask/releases/latest/download/halptask_Linux_x86_64
chmod +x halptask_Linux_x86_64 && sudo mv halptask_Linux_x86_64 /usr/local/bin/halptask

# Windows (x86_64)
curl -LO https://github.com/halpworld/halptask/releases/latest/download/halptask_Windows_x86_64.exe

🐧 Linux Packages (.deb / .rpm)

• Debian / Ubuntu: sudo apt install ./halptask_<version>_amd64.deb
• Fedora / RHEL: sudo dnf install ./halptask_<version>_amd64.rpm

🛠️ Build & Install from Source

# Using Go
go install github.com/halpworld/halptask@latest

# Or clone and build manually
git clone https://github.com/halpworld/halptask.git
cd halptask
go build -o halptask .
./halptask

CLI Flags & Headless Subcommands

HalpTask supports both interactive TUI launching and Headless Subcommands for instant task capture and status bar querying:

# 1. Instant Quick-Capture to Inbox (sub-second)
halptask add "Fix Redis connection timeout in worker #ops due:tomorrow"
halptask add "Draft sprint review" --tag urgent --tag meeting
halptask add "Deploy hotfix" --top

# 2. Status Bar & Shell Querying
halptask list --count        # Outputs: 📋 4 todo, 1 in-progress, 2 overdue (for tmux / Waybar)
halptask list --today        # Outputs formatted table of tasks due today or in progress
halptask list --json         # Outputs structured JSON for shell automation scripts

# 3. Encrypted Vault Automation
HALPTASK_PASSPHRASE="secret" halptask add "Confidential notes #vault" -f ~/.config/halptask/vault.pb

CLI Subcommand & Flag Reference:

Command / Flag	Short	Description	Example
halptask add <text>	capture	Quick-capture task into Inbox	halptask add "Fix bug #ops due:tomorrow"
halptask list	ls	List active tasks in formatted table	halptask list / halptask list --today
--count	-c	Single-line compact status summary	halptask list --count
--today	-t	Filter tasks due today, overdue, or in-progress	halptask list --today
--in-progress	-p	Filter tasks currently in progress	halptask list --in-progress
--json	-j	Output structured JSON array	halptask list --json
--tag	-t	Add tag(s) to captured task	halptask add "Meeting" --tag sprint
--top		Prepend to top of Inbox instead of bottom	halptask add "Hotfix" --top
--bullet		Create as non-task bullet point	halptask add "Note item" --bullet
-f	--file	Path to custom halptask data file	halptask -f ~/tasks.pb
-e	--encrypt	Force enable AES-256-GCM encryption	halptask -e
-v	--version	Print version info	halptask -v
-u	--update	Check and auto-update binary	halptask -u
-c	--check-update	Check if new version is available	halptask -c
-r	--repo	Override target GitHub repository	halptask -r owner/repo

---

⌨️ Summary Keybindings Quick Reference

Leader Key	Category	Command / Action
<space> b n	Bullets	New bullet below
<space> b N	Bullets	New bullet above
<space> b c	Bullets	Add child bullet
<space> b e	Bullets	Edit bullet text
<space> b d	Bullets	Delete bullet & subtree
<space> b i	Bullets	Indent bullet (demote)
<space> b o	Bullets	Unindent bullet (promote)
<space> b j	Bullets	Move bullet down
<space> b k	Bullets	Move bullet up
<space> t t	Tasks	Toggle bullet into task [ ]
<space> t c	Tasks	Cycle status (Todo ➜ In Progress ➜ Done)
<space> t d	Tasks	Mark Done [x] (Green X, strikethrough)
<space> t p	Tasks	Mark In Progress [~] (Orange ~)
<space> t s	Tasks	Mark Todo [ ] (Gray empty)
<space> t a / T	Tasks	Manage task tags & labels
<space> n / N	Tasks	Open / edit task Markdown note
<space> t D	Tasks	Toggle default creation type (bullet <-> task)
<space> c c	Config	Open interactive Config Dashboard modal
<space> c a	Config	Toggle Auto-Save
<space> c d	Config	Toggle default creation item type (bullet <-> task)
<space> c t	Config	Cycle visual theme palette
<space> c w	Config	Toggle WhichKey popup menu
<space> c e	Config	Open config.yaml in $EDITOR (auto-reloaded on exit)
<space> z c	Folds	Close fold
<space> z o	Folds	Open fold
<space> z a	Folds	Toggle fold
<space> z M	Folds	Close all folds
<space> z R	Folds	Open all folds
<space> e e	Encrypt	Toggle encryption
<space> e p	Encrypt	Set / Change passphrase
<space> w	File	Save file
<space> /	Search	Search bullet points
<space> ?	Help	Show keymap cheat sheet modal
<space> q	Quit	Save and exit

For full details, view the Keybindings Cheatsheet.

---

⚙️ In-App & File Configuration (~/.config/halptask/config.yaml)

HalpTask provides a LazyVim-inspired configuration model:

1. Interactive Config Dashboard (<space> c c): Browse categorized settings (General, UI & Appearance, Storage & Security), toggle booleans with Space/Enter, and cycle themes with instant disk persistence.
2. Quick Leader Toggles: One-keypress toggles like <space> c a (Auto-Save), <space> c d (Default Item), and <space> c t (Cycle Theme).
3. External Editor Harmony (<space> c e): Launches your preferred $EDITOR on ~/.config/halptask/config.yaml, auto-reloading changes on save.

auto_save: true
check_updates: true
data_file: ~/.config/halptask/data.txt
default_item_type: bullet # "bullet" or "task"
encrypted: false
indent_spaces: 2
leader_key: " "
show_which_key: true
theme: default

Auto-Save & Encrypted Files: When auto_save: true, HalpTask will automatically save all tree state mutations in the background. If you open or create an encrypted file but haven't provided a passphrase yet, auto-save will pause until you enter your passphrase to prevent data loss or lockouts.

---

🛠️ Releases & Compilation

We use GoReleaser and GitHub Actions to automatically build and release binaries for macOS, Linux, and Windows across amd64 and arm64 architectures.

For full details on the automated release process or how to build releases locally, refer to the Release Guide.

---

📄 License

MIT License. Developed with Go & Charm Bubble Tea.

---

💡 Acknowledgments

Special thanks to the LazyVim project for inspiration.