github.com/chmouel/lazyworktree

This release introduces precise AI agent session tracking with lifecycle hooks, a new CLI cleanup command for stale worktrees, and customizable CI remote targeting. It also significantly reduces idle CPU consumption and hardens concurrent worktree note editing.

Features

• Agent Lifecycle Hooks: Added session tracking lifecycle hooks for Claude Code, Codex CLI, and GitHub Copilot CLI. This allows precise status monitoring (such as "thinking" vs. "waiting for input") and replaces expensive process-table scans. Run lazyworktree setup-hooks to install.
• Stale Worktree Cleanup Command: Introduced a new cleanup CLI subcommand to identify and remove merged worktrees, stale branches, and orphaned directories. Users can run this interactively or automate it non-interactively using the --all flag.
• Structured Cleanup Output: Integrated a --json flag into the cleanup command to emit machine-readable results, and updated the command's visual summary to display a bulleted list of removed worktrees.
• Configurable CI Remote: Added a ci_remote setting (with an "auto" sentinel) to target a specific remote (such as upstream) for GitHub CI and PR status queries. This ensures fork workflows query the upstream repository without changing the worktree's core local repository identity.
• Prevent Git Optional Locks: Injected GIT_OPTIONAL_LOCKS=0 into executed Git commands to prevent concurrent automated operations from performing optional index locks, eliminating index modification conflicts.

Bug Fixes

• Split Notes Concurrency: Switched split-mode worktree notes to targeted, single-file saves instead of bulk directory writes. This ensures a stale in-memory map from one process cannot accidentally erase or overwrite notes concurrently edited by another process.
• Weekly PR Merge Strategy: Changed the weekly workflow PR merge strategy from merge to rebase to maintain a linear git history.

Performance Improvements

• Reduced Idle CPU: Dropped idle tick resource consumption by skipping expensive process scans when the agent process set remains unchanged, suspending auto-refresh loops when the TUI is unfocused, and revalidating cached Git details using cheap HEAD/status probes. Added a hidden LAZYWORKTREE_PPROF CPU profiling hook.

Maintenance

• Reorganized AI agent contribution guidelines in AGENTS.md for better visibility of README.md modification constraints.
• Configured Dependabot to group GitHub Actions updates into a single weekly pull request.

Dependencies

• Upgraded Go terminal dependencies (golang.org/x/term, golang.org/x/sync, golang.org/x/sys) via weekly maintenance (PR #82)
• Upgraded charm.land Bubble Tea libraries (bubbles, bubbletea, lipgloss) and ultraviolet (PR #77, PR #83)

GitHub avatar Badges

This release introduces significant performance optimizations to eliminate idle CPU usage, adds a new clean-reset option for existing worktrees, and brings several user-experience enhancements including Kitty-compatible avatar badges and hyperlinked repository headers.

Features

• Reset Existing Worktrees: Added a new --update-on-existing (-U) flag to the create command to automatically fetch and hard-reset an existing clean worktree to its remote head instead of failing.
• Kitty-Compatible Avatar Badges: Show small, circular PR/MR author avatars in the Info pane on supported terminals (e.g., Kitty, WezTerm, Ghostty) via the new avatar_badges configuration.
• Unified Command Environment: Standardized environment variable execution across custom commands, containers, lifecycle hooks, and CLI commands. Exposes a consistent set of WORKTREE_*, REPO_*, and contextual LAZYWORKTREE_* variables.
• Hyperlinked Repository Headers: Enabled OSC 8 hyperlinking on the repository header in the TUI to quickly open remote repositories in the browser, and shortened home path directories shown in the Info pane.
• CLI Debug Logging: Added a --debug-log command-line flag to configure debug logging dynamically to a file for easier troubleshooting of interactive selectors.
• Cache Clearing & PR Fetch Shortcut: Added a dedicated cache-clear action to empty in-memory/on-disk caches and assigned the p key to fetch PR data separately without triggering full UI refreshes.

Bug Fixes

• CPU Resource Pegging: Fixed an issue where the loading spinner and file watcher consumed excessive CPU resources while idle. The spinner tick loop now self-stops when inactive and restarts only when loading operations begin.

Performance Improvements

• Agent Session Caching & Debouncing: Optimized AI agent transcript watching by caching parsed registries in-process and introducing an adjustable debounce throttle (agent_sessions.refresh_debounce_ms) to lower CPU usage when agents are actively writing.
• FZF Preview Temp Files: Switched the interactive selector's preview mechanism to write fzf preview content to temporary files, preventing command-line length limit issues and enhancing execution performance.

Maintenance

• Contributor Policy: Added an External Contributor Disclosure policy in AGENTS.md requiring AI agents to clearly disclose their involvement, toolsets, and model configurations in pull requests or issues.
• Makefile Enhancements: Silenced build output in the Makefile and added confirmation messages on successful build completion.
• Documentation Updates: Clarified that the run command (!) executes shell commands, and revised feature descriptions for clarity.
• Performed weekly maintenance updates (#74).

Dependencies

• Bumped actions/checkout from v6 to v7.
• Bumped github.com/urfave/cli/v3 from 3.10.0 to 3.10.1.

Breaking Changes

None.

This release introduces inline status chips for CI checks, dedicated PR status badges within the Info pane, and improved container execution logic for custom commands. Additionally, it features structural code refactoring, streamlined documentation, and various dependency upgrades to enhance overall stability.

screenshot of new pills

Features

• Inline CI Status: Replaced the heavy powerline-style CI summary pill with a lightweight, inline status chip next to the CI Checks heading.
• PR Status Badges: Added colored state badges (Open, Merged, Closed, Draft) directly to the Info pane for improved visibility of pull/merge request status.
• Claude Skill for Docs Review: Introduced an AI-assisted workspace skill (docs-drift-review) to systematically analyze repository documentation for implementation drift, stale examples, or clarity issues.

Bug Fixes

• Container Commands Shell Wrapping: Multi-word container commands are now wrapped in a shell execution (sh -c) to prevent execution failures in container runtimes, and environment variables are properly expanded before execution.
• Custom Commands Discovery: Fixed an issue where container-only custom commands were omitted from the command palette.
• Custom Theme Handling: Ensured custom themes load properly on startup and dynamically reconcile with delta syntax theme arguments during CLI overrides.
• CLI Override Scoping: Fixed a bug where unspecified configuration string fields were reset to default values during CLI theme overrides.

Performance Improvements

• Badge Rendering Optimization: Extracted remote host icon mapping tables to the package level to eliminate redundant memory allocations, and deferred style calculations until after validation to prevent unnecessary processing.

Maintenance

• Code Refactoring: Grouped scattered Model state fields into dedicated sub-structs (loadingState, detailsState, pendingOpState) to improve long-term codebase maintainability.
• Configuration Default Changes: Adjusted the default refresh_interval to 10 seconds, disabled ci_auto_refresh by default, mapped the manual refresh key to r, and introduced the LAZYWORKTREE_DESCRIPTION variable for notes scripts.
• Documentation Refinement: Streamlined the user guide and README by removing redundant "Refer to this page when" callouts and simplifying phrasings.
• Test & Lint Improvements: Simplified linting targets, resolved test-suite lint warnings, and disabled GPG commit signing in machine test environments to prevent test failures.
• Weekly Maintenance: Completed weekly codebase maintenance and test coverage alignments (Pull Requests #66, #67, #68).

Dependencies

• Upgraded charm.land/bubbletea/v2 to v2.0.7 (Pull Request #66)
• Upgraded charm.land/lipgloss/v2 to v2.0.4 (Pull Request #67)
• Upgraded github.com/urfave/cli/v3 to v3.10.0 (Pull Request #67)
• Upgraded golang.org/x/term to v0.44.0 (Pull Request #67)
• Upgraded github.com/charmbracelet/ultraviolet to newer maintenance snapshots (Pull Requests #66, #67, #68)

This release introduces an alternative F1 shortcut for the command palette, a complete visual redesign of the website and documentation using a modern blue color palette, and key bug fixes for path expansion.

Bug Fixes

• Path Expansion: Fixed path expansion logic to correctly preserve literal tilde paths (such as ~other/worktrees) while still expanding home directory prefixes (~/).
• Website and Docs Tweaks: Renamed the install header to "Installation", reformatted long HTML figure captions, and fixed minor typos in the README.

Maintenance

• New Keybinding: Added F1 as an alternative shortcut to open the command palette alongside the existing : and Ctrl+P bindings.
• Visual Redesign: Migrated the landing website and documentation interface from warm earthy tones to a modern blue-based design system, utilizing the Space Grotesk typeface for improved readability.
• Configuration Documentation: Enhanced the configuration reference with precise types and descriptive details for agent_sessions, layout_sizes, and worktree_note_type keys.
• CI Workflow Consolidation: Combined the nightly coverage badge generation into the weekly maintenance workflow, reducing redundant GitHub Actions runs.
• Documentation Refinement: Standardized callout phrasing across all documentation pages to use "Refer to this page when:" instead of "Use this page when:" for improved clarity.
• Script Update: Updated the internal release notes generator script to target the gemini-3.5-flash model.

Dependencies

• Updated Go dependencies, including golang.org/x/sys, github.com/mattn/go-runewidth, and github.com/charmbracelet/ultraviolet (#62).

Breaking Changes

None.

This release introduces an enhanced AI agent session tracking model with liveness classification and a suite of machine-readable CLI commands designed for stable automation and LLM integration.

Features

• Agent Session Liveness Classification: Replaced binary session tracking with a four-state liveness model (active, recent, suspect, inactive) and source attribution (e.g., exact_file, cwd_heuristic).
• Persistent Session Registry: Added a disk-based session registry that allows agent sessions to persist across refreshes even when transcript files cannot be parsed.
• Machine-Readable CLI Commands: Introduced new stable JSON-ready commands for automation:
  • doctor: Reports repository, tool, and configuration health.
  • worktrees resolve: Canonicalizes worktree names, branches, or paths.
  • worktrees context: Provides combined note and agent session data for a specific worktree.
  • notes get: Retrieves structured note metadata.
  • describe: Emits the CLI command structure as JSON for introspection.
• Enhanced UI Feedback: Added liveness badges to the agent sessions pane to indicate the confidence level and source of session data at a glance.

Bug Fixes

• Non-Interactive Execution: Background Git operations now disable interactive terminal prompts and enforce SSH batch mode to prevent the application from hanging on authentication requests.
• Worktree Renaming: Updated renaming logic to target the worktree directory name rather than the branch name, ensuring consistent filesystem state.
• Path Resolution: Tightened worktree matching to prevent sibling directories with similar prefixes (e.g., feature vs feature-2) from being misidentified.
• Filename Safety: Switched to NUL-delimited Git status parsing (-z) for untracked files and symlink helpers to correctly handle filenames containing spaces.
• Thread Safety: Added mutex protection to the global icon provider to resolve race conditions during concurrent model creation.
• Input Normalization: Fixed issues where trailing slashes on path inputs caused CLI resolution failures.
• Relative Path Handling: Improved detection of relative worktree directories to ensure they are correctly resolved as repo-local.

Maintenance

• Documentation:
  • Added detailed guides and reference tables for agent session liveness filtering.
  • Restored the root DESIGN.md architecture note.
  • Repaired broken troubleshooting and diagnostic links in the README.
  • Updated the contributor guide to reflect Go 1.25 requirements.
• CI/CD: Replaced deprecated GitHub Actions and optimized caching for setup-uv.
• Build Tooling: Updated Makefile targets to exclude temporary/scratch packages from routine test and lint runs.

Dependencies

• Updated various Go dependencies, including urfave/cli/v3, fsnotify, golang.org/x/term, and ultraviolet. (#59, #61)

This release introduces repo-local worktree placement using the new $LWT_REPO_PATH variable, adds the ability to prune merged branches without active worktrees, and improves repository path resolution with URL decoding.

Features

• Added support for repo-local worktree placement via the $LWT_REPO_PATH environment variable. This allows users to store worktrees within the repository itself (e.g., in a .worktrees folder) while automatically omitting redundant repository name segments.
• Introduced a new configuration option, prune_stale_branches, which includes merged local branches that no longer have active worktrees in the prune checklist.
• Implemented an automated workflow to streamline the merging of Dependabot pull requests.

Bug Fixes

• Resolved an issue where repository names with URL-encoded characters (such as %20) were not decoded before creating directory paths (#49).
• Improved the identification of Claude CLI processes by ignoring the exec keyword in shell command wrappers.
• Fixed CI configuration to ensure workflows are correctly triggered when dependency files (go.mod and go.sum) are updated.
• Updated the release workflow to verify successful release creation even if GoReleaser encounters non-critical failures during secondary steps like AUR pushing.

Maintenance

• Standardized Git configuration key lookups by automatically normalizing hyphens to underscores (e.g., lw.worktree-dir now correctly maps to worktree_dir).
• Replaced the default Dependabot Go configuration with a custom weekly automated dependency update and auto-merge workflow.
• Updated documentation with new guidelines for documentation reviews and agent contribution requirements.

Dependencies

• Updated project dependencies to their latest versions, including several Charm libraries (bubbletea, lipgloss, bubbles, ultraviolet) and standard Go modules (x/term, x/sys). (#43, #45, #48)
• Upgraded various GitHub Actions to their latest major versions, including actions/configure-pages, actions/deploy-pages, actions/upload-pages-artifact, and peter-evans/create-pull-request. (#42)

Breaking Changes

None.

This release introduces support for agent tool approval states and includes significant internal architectural refactoring to improve code maintainability across the Git service and application handlers.

Features

• Added support for agent tool approval states to better track when agents are waiting for tool execution results.
• Improved Claude CLI process matching and recursive session discovery for nested file structures.

Bug Fixes

• Fixed an issue where tmux session commands could target similarly named sessions by implementing exact matching for session lookups. (#33)

Maintenance / Refactoring

• Reorganized Git service logic by splitting GitHub, GitLab, CI, and worktree-specific code into dedicated modules.
• Refactored monolithic application handlers into focused files based on features such as navigation, filtering, search, and operations.
• Modularized configuration loading by separating custom commands, themes, and keybinding logic.
• Extracted release notes generation into a standalone script for better local testing and updated the underlying AI model integration.
• Restructured the test suite to match the new modular architecture, improving test navigation and coverage tracking.

Dependencies

• Updated Brew cask distribution to version 1.44.0.

This release introduces a unified worktree metadata menu, comprehensive JSON output support for CLI commands to aid automation, and improved browser integrations. It also includes an important breaking change to action IDs for keybinding configurations to prevent pane collisions and make configurations self-documenting.

🚀 Features

• Unified Metadata Menu: Added a new worktree metadata menu (press e in the worktree pane) to easily edit a worktree's description, colour, notes, icon, and tags from a single interface.
• CLI Introspection: Introduced the describe command to output the CLI command structure as machine-readable JSON, enabling coding agents and external scripts to discover available commands programmatically.
• CLI JSON Support: Added the --json flag to create, delete, rename, exec, and note show commands for structured, machine-readable output.
• Enhanced list Command: The list --json output now includes worktree notes and agent session metadata. Added a --no-agent flag to omit agent data for faster script execution.
• Configurable Execution Modes: Added an --exec-mode flag for create --exec to control shell invocation (login-shell, shell, or direct).
• Enhanced Browser Navigation: Pressing o in the logs pane now opens the selected commit in the browser. When opening a worktree in the browser without an active Pull Request, the application now smartly falls back to opening the current branch page on GitHub or GitLab.

🐛 Bug Fixes

• Worktree Creation Flow: Fixed the issue-to-worktree flow to ensure that branch name script error notifications preserve the correct context and include worktree note script execution.

⚡ Performance Improvements

• Action Registry: Replaced an O(n) inner loop with an O(1) map lookup for updating action shortcuts, improving keybinding initialization performance.

🧹 Maintenance / Refactoring

• Namespaced Action IDs: Prefixed every command-palette action ID with its section (e.g., worktree-create, git-diff, nav-filter) to eliminate cross-pane collisions.
• Code Quality: Extracted test helpers and deduplicated AST parsing logic to reduce boilerplate across the codebase.
• Documentation: Updated documentation to clearly explain pane-scoped keybindings and custom commands. Cleaned up the README by refining the features list and removing outdated development sections.
• Project Structure: Renamed the Claude skill directory from worktree-manage to worktree-manager for consistency.

📦 Dependencies

• Updated Homebrew cask to v1.43.0.
• Updated project coverage badges.

💥 Breaking Changes

• Custom Keybindings Update Required: All action IDs have been namespaced by their pane/section to prevent ambiguity. If you have configured custom keybindings in your config.yaml using the old bare action IDs (e.g., create, diff, lazygit), you must update them to use the new prefixed names (e.g., worktree-create, git-diff, git-lazygit). Please refer to the Action IDs Reference documentation for the complete list of new names.

Contributors

• @chmouel
• @github-actions
• @goreleaserbot

This release introduces a powerful new Agent Sessions pane to monitor AI assistant activity (Claude and Pi) directly within your worktrees. It also brings extensive organizational tools including worktree tagging, descriptions, curated icons, and a highly customizable pane-scoped keybinding system.

🚀 Features

• Agent Sessions Pane: Added a dedicated pane to track active and historical Claude and Pi coding assistant sessions tied to worktrees. Includes visibility into agent status (thinking, writing, etc.) and support for custom transcript discovery paths.
• Worktree Tags: Implement robust tagging capabilities. You can now assign labels via an interactive tag editor, view them as colored badges in the worktree list and Info pane, and easily browse or filter worktrees using exact exact matches (e.g., tag:<name>).
• Worktree Descriptions: Assign human-readable descriptions to worktrees. These descriptions replace raw directory names in the list view, significantly improving clarity and searchability.
• Pane-Scoped Keybindings & Commands: Rebuilt the custom command and keybinding configuration. You can now scope shortcuts to specific panes (e.g., worktrees, status, log) or apply them globally using the universal key.
• Ranked Filtering: Overhauled the search/filter logic across all screens. The new ranking system prioritizes exact word matches, prefixes, and specific fields, ensuring the most relevant items rise to the top.
• Curated Worktree Icons: Expanded the worktree icon picker with specialized icons for common task types, such as bug fixes, refactors, reviews, and releases.

🐛 Bug Fixes

• Note View Wrapping: Prevented ANSI escape sequences from leaking and causing visual artifacts when soft-wrapping styled text in the Note View.
• Tag Rendering on Selection: Fixed an issue where ANSI color codes on tag pills conflicted with table row selection styling by rendering plain text tags for the currently focused row.
• Tag Normalization: Improved tag handling to automatically trim whitespace and strip empty entries during load and save operations.
• Tag Contrast: Updated the tag pill color palette to use text foreground colors instead of dim accents, ensuring better readability.

🧹 Maintenance / Refactoring

• Automated Documentation: Added a docs-sync pre-commit check to automatically parse the command registry and keep docs/action-ids.md up to date.
• UI Component Reuse: Consolidated PR and Issue selection modals to utilize a single, abstract list selection screen, reducing code duplication.
• Code Health: Centralized default file and directory permission constants and simplified hex digit validation logic.
• Build Process: Refactored the Makefile image optimization script to overwrite files in place directly and improve verbose output.
• Documentation: Updated the project README, About page philosophy, and agent contribution guidelines.

Contributors

• @chmouel

This release introduces a powerful new interactive commit screen, extensive enhancements to worktree notes (including a new CLI command and split markdown storage), custom worktree coloring, and major improvements to the command palette's search relevance.

🚀 Features

• Interactive Commit Screen: Added a dedicated modal for staging and committing changes, accessible via Ctrl+G. It features separate fields for subject and body, support for external editors (Ctrl+X), and an option to auto-generate commit messages from staged diffs (Ctrl+O).
• Worktree Color Customization: You can now visually organize your workspace by assigning colors (hex, named, or 256-index) to worktrees via the command palette. Colors are seamlessly persisted in the worktree's YAML frontmatter.
• CLI Note Command: Introduced lazyworktree note show and note edit CLI commands, allowing you to view, pipe, or modify worktree notes directly from the terminal without opening the TUI.
• Splitted Note Storage: Added worktree_note_type: splitted configuration. Instead of a single JSON file, notes can now be stored as individual markdown files with YAML frontmatter, utilizing customizable template paths for better interoperability with external tools.
• Advanced Command Palette Search: Completely overhauled the command palette's scoring system. It now ranks results using a tiered approach (exact word, prefix, and fuzzy matching), prioritizing label matches over descriptions, ensuring faster and more accurate command discovery.
• Palette-Only Custom Commands: Custom commands can now be configured to appear exclusively in the command palette by prefixing their key with _, keeping your keyboard shortcuts and footer hints clutter-free.
• Commit Log Indicators: The log pane now features distinct visual indicators for commit states (↑ for unpushed, ★ for unmerged) and assigns deterministic, color-coded highlights to different commit authors.
• Container Execution Enhancements: Custom container command mounts now support an options field, allowing for arbitrary volume flags such as z or Z for SELinux relabeling.
• GitLab MR Improvements: Added support for GitLab Draft MR statuses and improved MR head commit resolution using native API endpoints and diff_refs.head_sha fallbacks.
• Contextual Footer Hints: The footer now intuitively displays a Ctrl+G (Commit) shortcut hint whenever the active worktree contains local changes.

🐛 Bug Fixes

• UI Pane Switching: Fixed an issue where the Git Status pane would fail to refresh and display stale content when cycling through panes using the Tab key. Restored proper focus-driven auto-resizing behavior.

🧹 Maintenance / Refactoring

• UI Simplification: Refined the command palette selection UI by removing cluttered left-accent borders and shortcut badges in favor of a cleaner, full-width background highlight.
• Documentation Overhaul: Reorganized internal project architecture documentation, refreshed AI and container execution examples, and updated the README with a clearer outline of core features and workflows.
• Development Tooling: Added a hack/sample-repo.sh script to automatically scaffold a rich Git repository with branches, commits, and worktrees to accelerate local testing.
• Asset Optimization: Integrated automated image compression (pngquant and jpegoptim) into the build pipeline to shrink website assets.

📦 Dependencies

• Added github.com/google/shlex to safely parse user-defined shell commands for the new auto-generated commit message feature.
• Incremented system dependencies for rendering and UI components.

Contributors

• @chmouel
• @github-actions
• @goreleaserbot