A beautiful TUI for managing git worktrees across multiple repositories
tasktree-manager is a terminal user interface (TUI) application for managing development tasks that span multiple git repositories. Create tasks, organize worktrees, and track status across your entire codebase—all from a beautiful, keyboard-driven interface inspired by lazygit.
- 🎯 Task-Based Workflow - Group related worktrees across multiple repositories
- 🌳 Git Worktree Management - Create, delete, and manage worktrees seamlessly
- 📊 Real-Time Status - See uncommitted changes, branch info, and sync status at a glance
- 🔀 Sorting & Grouping - Sort tasks by name/date/status, group worktrees by dirty/clean
- 🎨 Beautiful Themes - lazygit-inspired default plus 20+ themes (Catppuccin, Tokyo Night, Nord, ...) via Command Palette (Ctrl+P)
- ⌨️ Keyboard-First - Navigate and control everything without touching the mouse
- 🚀 Fast & Responsive - Parallel git operations with loading indicators
- 🔧 Flexible Configuration - TOML config file, custom keybindings, environment variables
- 🤖 Headless CLI - Create, list, inspect, finish, and delete tasks from scripts and AI agents without opening the TUI
- 🛰️ Agent Dashboard - Live Claude Code session state per worktree (from
claude agents), plus one-key background-agent dispatch — the multi-repo agent view Claude Code lacks natively - 🔀 Forge-Aware Safety - MR/PR and CI state via
glab/gh; squash- and rebase-merged branches count as merged instead of blocking deletion forever - 📦 Finish Flow with Archives - Ending a task saves its combined diff (committed-but-unmerged + uncommitted) to an archive before deleting
| Indicator | Meaning |
|---|---|
● red |
Uncommitted changes |
◆ blue |
Has CLAUDE.md file |
⟳ magenta |
Claude Code session running / agent working |
! yellow |
Claude Code session waiting for input |
▣ green |
Agent session ready (idle) |
✓ green |
Clean worktree / Claude session ended |
✗ N red |
N files changed |
↑N green |
N commits ahead of remote |
↓N yellow |
N commits behind remote |
○ green / ● magenta / × red |
MR open / merged / closed |
◐ yellow / ✔ green / ✘ red |
CI running / passed / failed |
# Using pipx (recommended)
pipx install tasktree-managerSee the Installation Guide for other methods and platform-specific instructions.
tasktree-managerOn first run, you'll configure:
- Repositories Directory: Where your git repos live (e.g.,
~/repos) - Tasks Directory: Where worktrees will be created (e.g.,
~/tasks)
- Create a task - Press
n, enter task name, select repositories - Work on code - Press
efor editor,gfor lazygit, orofor a shell in a new terminal tab - Review changes - Press
hto view the diff in hunk (all repos from the task panel, one repo from the worktree panel) - Push changes - Press
pto push all worktrees - Delete task - Press
dwhen finished
For detailed workflows and examples, see the User Guide.
Running tasktree-manager with arguments skips the TUI — useful for scripts and AI-agent
workflows (e.g. a skill that creates a Jira ticket and then the matching task):
tasktree-manager create DIC-1901-argocd-tls --repos backend,frontend # --base overrides the default base branch
tasktree-manager list --json # tasks with repos and dirty state (plain text without --json)
tasktree-manager repos # available repos in REPOS_DIR
tasktree-manager add-repo DIC-1901-argocd-tls infra
tasktree-manager status # current task inferred from $PWD; also --json / --oneline / --forge
tasktree-manager finish DIC-1901-argocd-tls # safety sweep -> archive diff -> delete; --push / --no-archive / --force
tasktree-manager delete DIC-1901-argocd-tls # low-level delete; refuses on unfinished work; --force overridesExit code is 0 on success, 1 on failure with the reason on stderr. delete and finish run
the same safety check as the TUI (uncommitted, unpushed, or unmerged work blocks deletion);
with glab/gh installed, squash/rebase-merged branches are recognized as merged.
status --oneline emits a compact TASK repoA✓ repoB●2↑1 summary that slots straight into
a Claude Code statusline or shell prompt.
Complete guides:
- Installation Guide - Platform-specific setup, system requirements, troubleshooting
- User Guide - Workflows, keyboard shortcuts, tips and best practices
- Configuration Reference - All config options, keybindings, themes
- Troubleshooting Guide - Common issues and solutions
Quick Reference:
| Key | Action | Key | Action |
|---|---|---|---|
n |
New task | g |
Open lazygit |
a |
Add repo | h |
Show diff (hunk) |
d |
Delete task | e |
Open editor |
p |
Push all | o |
Open folder |
P |
Pull all | y |
Clone task |
c |
Claude (resume) | C |
Claude (new) |
b |
Dispatch agent | D |
Delete worktree |
r |
Refresh | s |
Sort tasks |
S |
Group worktrees | m |
Messages |
t |
Cycle theme | Tab |
Next panel |
R |
Rename task | ||
? |
Show help | q |
Quit |
Themes: The default tasktree theme pairs a lazygit-classic ANSI palette with layered panels, numbered title bars, green focus borders, and a keycap footer. Five more design-system palettes ship tuned to the same shape — tokyo-night, catppuccin-mocha, gruvbox, dracula, nord — and every other Textual built-in theme works too (Ctrl+P to switch); the whole UI is styled with Textual design tokens, so any theme restyles it consistently.
tasktree-manager uses git worktrees to create isolated working directories for each task. Work on multiple branches simultaneously without stashing or context switching.
Directory Structure:
~/repos/ # Your git repositories (never modified)
├── backend/
└── frontend/
~/tasks/ # Task worktrees (managed by tasktree-manager)
├── FEAT-123/
│ ├── backend/ # Worktree on branch FEAT-123
│ └── frontend/ # Worktree on branch FEAT-123
└── BUG-456/
└── backend/
Learn more in the User Guide.
See CONTRIBUTING.md for detailed development setup and guidelines.
Quick Start:
git clone https://github.com/yourusername/tasktree-manager.git
cd tasktree-manager
mise install
mise run install
mise run testCommon Commands:
mise run dev # Run with dev console
mise run test # Run tests
mise run lint:fix # Auto-fix lint issuesContributions welcome! See CONTRIBUTING.md for guidelines.
Quick contribution steps:
- Fork and create feature branch
- Make changes and add tests
- Run
mise run testandmise run lint - Submit pull request
- Python 3.10+ (3.13+ recommended)
- Git 2.0+
- 256-color terminal
- Unix-like OS (macOS, Linux, WSL2)
See Installation Guide for detailed requirements and setup.
Common issues and quick fixes:
- "No repositories found" - Check
repos_dirin config contains git repos - "Worktree creation failed" - Verify base branch exists and you have permissions
- Theme not changing - Use
Ctrl+Pto select theme, or check config file permissions - Command not found - Run
pipx ensurepathand restart terminal
For comprehensive troubleshooting, see the Troubleshooting Guide.
Recently shipped: agent dashboard (per-worktree Claude session badges + background dispatch),
forge-aware merged detection (glab/gh, squash/rebase merges), MR/CI status badges,
guided finish flow with diff archiving, status subcommand for scripts and statuslines.
Upcoming:
- v0.3.0 - Search/filter, task templates
- v0.4.0 - JIRA status column, git hooks, automation
- v1.0.0 - Stable release
See ROADMAP.md and CHANGELOG.md for details.
MIT License - see LICENSE for details.
Made with ❤️ by developers, for developers | ⭐ Star this repo