Skip to content

Power-User-Guide.md

Latest commit

 

History

History
218 lines (162 loc) · 9.77 KB

Power-User-Guide.md

File metadata and controls

218 lines (162 loc) · 9.77 KB
Raw

Power User Workflow & Tips ⚡

Take your HalpTask productivity to the highest level! This guide details advanced Vim shortcuts, subtree hoisting hacks, dynamic tag mechanics, configuration fine-tuning, and terminal shell integration.

⌨️ 1. Vim Motion Combos & Lightning Navigation

HalpTask is built around authentic Vim navigation and manipulation concepts.

 Navigation          Subtree Editing            Folding & Focus
 ──────────          ───────────────            ───────────────
 j / k : Down/Up     oo : New below             zc / zo : Close/Open fold
 h / l : Parent/Child oc : New child (subtask)  za      : Toggle fold
 gg    : Jump Top    dd : Delete subtree        zM / zR : Close/Open all
 G     : Jump Bottom J/K: Move down/up          ff      : Hoist / Zoom view
 gi    : Jump to ID  u/Ctrl+r: Undo/Redo        <space>gi: Jump to ID

Motion Combos to Master:

  • gi or <space> g i: Jump directly to any task or bullet item by its permanent #ID number!
  • oo vs oc: oo creates a sibling bullet directly below; oc creates a child subtask underneath current selection.
  • i / a / e: Enter insert mode at the current node text.
  • c: Clear the node text entirely and instantly enter insert mode.
  • J / K: Shift items up or down among their siblings without losing subtree structure.
  • Tab / Shift+Tab: Demote (indent) or promote (unindent) items across hierarchical levels.
  • u / Ctrl+r: Full undo/redo stack for all structural changes, node deletions, and status toggles.

🚀 2. Speed Hacks: Single t vs Leader Keys

HalpTask features two distinct ways to interact with tasks:

Lightning 1-Key Task Toggle (t)

In Normal mode, pressing single t performs an instant status cycle:

  1. • (Bullet) ➔ [ ] (Todo)
  2. [ ] (Todo) ➔ [~] (In Progress)
  3. [~] (In Progress) ➔ [x] (Done)
  4. [x] (Done) ➔ • (Bullet)

Tip

Power Tip: Tap t rapidly while moving with j/k to update task statuses across your list without opening any menus!

Explicit Leader Shortcuts (<space> t ...)

When you need direct, non-cycling status assignment:

  • <space> t d: Mark Done ([x]) instantly.
  • <space> t p: Mark In Progress ([~]) instantly.
  • <space> t s: Mark Todo ([ ]) instantly.
  • <space> t a: Open Tag Manager (🏷️).
  • <space> n / N: Open / Edit Task Markdown Note (📝).
  • <space> t D / D: Open Set / Edit Due Date prompt (⏰).
  • <space> a g / A: Open Agenda & Schedule View modal (📅).

⏰ Due Dates, Natural Scheduling & Agenda View (D / <space> a g / A)

HalpTask transforms nested task outliners into actionable daily agendas:

  • Inline Scheduling: While typing in insert mode, type due:tomorrow, due:+3d, due:friday, due:2026-08-25, or @due(...) to automatically attach a deadline.
  • Urgency Badges: Tasks render ANSI-styled badges:
    • 🔴 [Overdue: 2d] (Bold Red alert for overdue incomplete tasks)
    • 🟡 [Due Today] (Amber warning for tasks due today)
    • 🔵 [Due: Tomorrow] / [Due: Fri] (Cyan subtle info)
    • 🏁 [Due: Aug 25] (Muted completed)
  • Agenda View Modal (A or <space> a g): Displays a full-screen schedule grouped into Overdue, Today, This Week, Upcoming, and Completed.
    • Press j/k to navigate, t/x/Space to cycle status, D to change due dates, / to filter, and Enter to jump directly to that task in your tree outliner!

📝 Task Notes & Cross-Task Linking (N or <space> n)

Attach detailed Markdown context to any task item.

  • Press N or <space> n to open the Note modal.
  • Supports rich Markdown formatting (headings #, lists -, quotes >, code blocks ```).
  • Write internal task links in flexible formats: #123, [Label](#123), [Label](123), task:123.
  • Press Tab / Shift+Tab to cycle between links in View mode.
  • Press Enter on a focused link to instantly close the note and navigate to that task in your tree view!

🔍 3. Subtree Hoisting / Zooming (ff)

When working inside deep task trees with hundreds of items, extraneous sections can cause visual distraction.

Subtree View

  • Press ff on any parent node to Hoist / Zoom into that node.
  • The screen zooms in, making the focused node the temporary root of your viewport!
  • Press ff again to un-hoist and return to full document view.

🧹 4. Task Cleanup: Hide & Purge Completed Tasks

Keep your workplace tidy with completed task management shortcuts:

  • fc (Toggle Completed Filter): Hides or shows all [x] completed tasks from your view without deleting them. Perfect for focusing strictly on active work!
  • da (Delete All Completed): Permanently purges all [x] completed tasks from the current document.

📦 5. Long-Term Task Archiving & Schema-Safe Storage (<space> a ...)

For tasks you have finished but want to retain long-term history for audit or retrieval:

  • <space> a a (Archive Selected Item): Moves the selected node (and its entire subtree) out of your active file into compressed archive storage (archive.dat).
  • <space> a c (Archive Completed Tasks): Sweeps all [x] completed tasks across the document and archives them automatically.
  • <space> a v / <space> a r (Archive Browser Modal): Launches the interactive Archive View modal to filter, view subtree details, restore entries back into your active tree (r), or permanently delete (d).

Note

Archive storage uses Gzip compression to save disk space and automatically inherits your file AES-256-GCM encryption passphrase! Schema updates in future versions automatically migrate archived items upon restoration.

🏷️ 5. Dynamic Tag Inheritance Secrets

HalpTask features a sophisticated tag hierarchy system:

  1. Direct Tags: Created with T or <space> t a and stored in plain text as #tagname.
  2. Inherited Tags: Dynamically derived from ancestor nodes. Subtasks automatically display [↖🔥 urgent].
  3. Subtask Reparenting Behavior:
    • When you press Tab to demote a task under a tagged parent, it instantly inherits the parent's tags.
    • When you press Shift+Tab to promote a subtask out of a tagged parent, the inherited parent tags are automatically removed, preserving only direct tags.

🖥️ 6. Headless CLI Quick-Capture & Status Bar Integration

HalpTask includes a first-class headless CLI pipeline (halptask add and halptask list) that eliminates context-switching friction.

Instant 1-Second Quick-Capture

Capture thoughts, bug reports, and action items directly from terminal sessions without opening the TUI:

# Capture with tags and due date
halptask add "Fix Redis connection timeout in worker #ops due:tomorrow"

# Flag modifiers
halptask add "Draft sprint review" --tag urgent --tag meeting
halptask add "Deploy hotfix" --top
halptask add "System architecture note" --bullet

list --today includes active tasks due today, overdue, or in progress, and excludes completed tasks. list --all --json includes completed tasks. --count summarizes the entire file (overdue overlaps todo/in-progress); do not combine it with --json. Piped output is free of ANSI formatting.

Capture defaults to tasks; --task and --bullet cannot be combined. To supply a Markdown status prefix, use halptask add --tag ops -- "- [~] Investigate timeout". Use --inbox Work to target a different root section. Both due:tomorrow and @due(2026-09-15) are supported.

Tmux Statusline Integration (~/.tmux.conf)

Display your live pending and in-progress task counts directly in your tmux status bar:

# Update status every 60 seconds
set -g status-interval 60

# Add halptask count to right status
set -g status-right "#(halptask list --count) | %H:%M %d-%b"

Waybar Module Integration (~/.config/waybar/config.jsonc)

For Wayland / Hyprland / Sway status bars:

"custom/halptask": {
    "format": "{}",
    "interval": 60,
    "exec": "halptask list --count",
    "on-click": "alacritty -e halptask",
    "tooltip": false
}

Polybar Module Integration (~/.config/polybar/config.ini)

For X11 / i3 / bspwm status bars:

[module/halptask]
type = custom/script
exec = halptask list --count
interval = 60
click-left = kitty -e halptask &
format-prefix = " "

Multi-File Project Vaults & Aliases

# Work-specific tasks
alias ht="halptask"
alias hta="halptask add"
alias htl="halptask list --today"
alias htp="halptask -f ~/projects/main.pb"
alias htv="HALPTASK_PASSPHRASE=\"secret\" halptask -f ~/.config/halptask/vault.pb"

Tmux Split Window Workflow

Keep HalpTask permanently open alongside your code editor inside Tmux:

# In Tmux session:
tmux split-window -h -p 35 "halptask -f .tasks.pb"

⚙️ 7. Configuration Dashboard & Editor Harmony

HalpTask provides two seamless ways to tune settings:

Interactive Config Dashboard (<space> c c)

  1. Press <space> c c to launch the interactive modal.
  2. Navigate settings with j/k or ↑/↓.
  3. Press Space or Enter to toggle booleans (e.g. auto_save, show_which_key).
  4. Press t to cycle visual color themes (default, tokyonight, catppuccin, dracula, nord).
  5. Settings persist instantly to disk!

Interactive Config Dashboard

External Editor Harmony (<space> c e)

Press <space> c e to launch your system $EDITOR (Neovim, Vim, Nano) directly on ~/.config/halptask/config.yaml. When you save and exit your editor, HalpTask automatically reloads the updated configuration without restarting!