Skip to main content
LazyWorktree provides per-worktree notes with markdown rendering and a Kanban-lite taskboard for tracking checkbox tasks across worktrees.

​
Worktree Notes

Press i to open notes for the selected worktree.

​
Note Viewer

If a note already exists, LazyWorktree opens a viewer first: Navigation:
  • j / k or arrow keys - Scroll line by line
  • Ctrl+D / Ctrl+U - Half-page navigation
  • g / G - Jump to top/bottom
  • e - Edit the note
  • q / Esc - Close viewer
Worktrees with notes display a note marker icon beside the name in the worktree list.

​
Note Editor

If no note exists, LazyWorktree opens the editor directly: Controls:
  • Enter - Add a new line
  • Ctrl+S - Save note
  • Ctrl+X - Open in external editor
  • Esc - Cancel (discard changes)
The external editor is configured via the editor setting (default: $EDITOR, fallback to nvim).

​
Markdown Support

The Notes pane renders markdown formatting:
  • Headings (#, ##, ###)
  • Bold text (**bold**)
  • Inline code (`code`)
  • Lists (-, *, 1.)
  • Quotes (>)
  • Links ([text](url))
  • Fenced code blocks ( ```)

​
Uppercase Note Tags

Uppercase tags are highlighted with icons outside fenced code blocks:
  • TODO - Todo icon
  • FIXME - Fix icon
  • WARNING: - Warning icon
  • NOTE: - Note icon
# Feature Implementation

TODO: Add validation for user input
FIXME: Memory leak in connection handler
WARNING: Breaking change in API v2

## Tasks
- [ ] Draft implementation
- [x] Update changelog
- [ ] Write tests

```python
# Code blocks don't highlight TODO/FIXME
# TODO: This won't be highlighted
For GUI editors like VSCode, use the --wait flag to ensure LazyWorktree waits for the editor to close.

​
Taskboard

Press T to open the Taskboard, a Kanban-lite view of markdown checkbox tasks grouped by worktree.

​
Taskboard View

The Taskboard displays only markdown checkbox items from notes: 
- [ ] Draft release notes
- [x] Update changelog
- [ ] Test on staging
Grouped by worktree: 
┌─ feature-auth ──────────────┐
│ [ ] Add OAuth2 support      │
│ [x] Update login tests      │
└─────────────────────────────┘

┌─ bugfix-memory ─────────────┐
│ [ ] Reproduce memory leak   │
│ [ ] Add profiling           │
└─────────────────────────────┘

​
Taskboard Controls

KeyAction
j / kMove between tasks
Enter or SpaceToggle task completion
aAdd a new task
fFilter tasks
q / EscClose Taskboard
Tasks toggled in the Taskboard are immediately saved to the worktree note.

​
Add New Task

Press a in the Taskboard to add a new task:
1

Press `a`

Opens task input dialogue
2

Type task description

Enter the task text
3

Press `Enter`

Adds the task as - [ ] <description> to the current worktree’s note

​
Filter Tasks

Press f to filter tasks by worktree name or task description:
1

Press `f`

Shows filter input
2

Type filter text

Tasks matching the filter are shown
3

Press `Esc`

Clears the filter

​
Shared Note Storage

Configure worktree_notes_path to store all notes in a single JSON file for cross-system synchronisation: 
worktree_notes_path: "~/.local/share/lazyworktree/worktree-notes.json"
With shared storage:
  • Note keys are repo/worktree-relative (not absolute paths)
  • Easier to sync across machines (e.g., Dropbox, Git)
  • Single file for all repositories
Without worktree_notes_path, notes are stored per-repository in <repo>/.git/lazyworktree-notes.json.

​
Automatic Note Generation

Configure worktree_note_script to automatically generate notes when creating worktrees from PRs/MRs or issues: 
worktree_note_script: "aichat -m gemini:gemini-2.5-flash-lite 'Summarise this ticket into practical implementation notes.'"
The script receives the issue/PR title and body on stdin and outputs note text.

​
Environment Variables

  • LAZYWORKTREE_TYPE - pr or issue
  • LAZYWORKTREE_NUMBER - Issue/PR number
  • LAZYWORKTREE_TITLE - Issue/PR title
  • LAZYWORKTREE_URL - Issue/PR URL
If the script fails or outputs nothing, creation continues without a note.

​
Example Note Workflow

1

Create Worktree from Issue

Press c → “From GitHub/GitLab issue” → Select issue #42
2

Auto-generated Note

If worktree_note_script is configured, a note is created automatically with implementation context.
3

View Note

Press i to view the note in the markdown-rendered viewer.
4

Add Tasks

Press e to edit, add markdown checkboxes:
- [ ] Draft implementation
- [ ] Write tests
- [ ] Update documentation
5

Track in Taskboard

Press T to see tasks grouped by worktree.
6

Toggle Completion

Use Enter or Space in Taskboard to mark tasks complete.

​
Note Character Limit

Notes are limited to 4000 characters to prevent performance issues.
If you need longer notes, use external documentation and link from the worktree note.

​
Pane Visibility

The Notes pane (pane 5) is only visible when the selected worktree has a note.
  • Press 5 to focus Notes pane (when visible)
  • Press 5 again to toggle zoom (full screen)
  • Use h / l to navigate left/right panes
The Notes pane splits the left column in default layout, or appears as a row in top layout.

Build docs developers (and LLMs) love

Get started for freeTalk to us