tasktree-manager 2.18.0__tar.gz → 2.19.0__tar.gz

{tasktree_manager-2.18.0 → tasktree_manager-2.19.0}/CHANGELOG.md

@@ -15,6 +15,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Git hooks support
 - Custom task metadata
 
+## [2.19.0] - 2026-10-29
+
+### Added
+- Open zellij tabs that survive a terminal restart, and review fixes (#16)
+
+### Changed
+- Split the headless CLI and epic sections into short parts (#15)
+
+
 ## [2.18.0] - 2026-10-20
 
 ### Added

{tasktree_manager-2.18.0 → tasktree_manager-2.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tasktree-manager
-Version: 2.18.0
+Version: 2.19.0
 Summary: TUI application for managing worktree-based tasks
 License-File: LICENSE
 Requires-Python: >=3.10

{tasktree_manager-2.18.0 → tasktree_manager-2.19.0}/README.md

@@ -23,6 +23,7 @@
 - ✻ **Session Recap** - The Info panel shows each task's latest Claude Code session: title, last turn duration, and Claude's own idle recap of what was done and what comes next — read straight from the transcript, no CLI call
 - 🔀 **Forge-Aware Safety** - MR/PR and CI state via `glab`/`gh`; squash- and rebase-merged branches count as merged instead of blocking deletion forever
 - 🗂️ **Epics** - Group related tasks under an epic: a foldable row with rolled-up dirty and Claude state, `E` to attach tasks, and an epic log and `epic ask` so the Claude sessions of one epic share what they know
+- 🧷 **zellij Tabs** - Run the TUI inside zellij (or set `zellij_autostart`) and `o`/`e`/`c` open zellij tabs that keep running across a terminal restart; pressing the key again jumps to the open tab ([details](docs/user-guide.md#zellij))
 - 📦 **Finish Flow with Archives** - Ending a task saves its combined diff (committed-but-unmerged + uncommitted) and the task-folder files outside the worktrees (plans, ADRs, notes) to an archive before deleting
 
 ## 📊 Status Indicators
@@ -76,72 +77,93 @@ For detailed workflows and examples, see the [User Guide](docs/user-guide.md).
 
 ### Headless CLI
 
-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):
+Running `tasktree-manager` with arguments skips the TUI. Use it from scripts and AI agents,
+for example a skill that creates a Jira ticket and then the matching task.
+
+#### Tasks
 
 ```bash
-tasktree-manager create DIC-1901-argocd-tls --repos backend,frontend  # --base overrides the default base branch
-tasktree-manager list --json     # tasks with repos and state: clean / dirty / error (plain text without --json)
-tasktree-manager repos           # available repos in REPOS_DIR
+tasktree-manager create DIC-1901-argocd-tls --repos backend,frontend  # --base sets the base branch
 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 + task files -> delete; --push / --no-archive / --force
-tasktree-manager delete DIC-1901-argocd-tls   # archive diff + task files -> delete; refuses on unfinished work; --force overrides
+tasktree-manager list --json        # tasks, repos and state: clean / dirty / error
+tasktree-manager repos              # repos available in REPOS_DIR
+tasktree-manager status             # task of the current folder; --json, --oneline, --forge
+tasktree-manager finish DIC-1901-argocd-tls   # safety check, archive, delete; --push, --no-archive
+tasktree-manager delete DIC-1901-argocd-tls   # archive, delete; refuses unfinished work
 ```
 
-Epics group related tasks, for example a Jira epic and its child tasks. An epic is a task
-folder with a `.tasktree_kind` marker. It can hold its own notes, Claude session and
-worktrees. A child task names its epic in `.tasktree_epic`. Folders never move:
+`status --oneline` prints a compact `TASK repoA✓ repoB●2↑1` line for a Claude Code
+statusline or a shell prompt.
+
+#### Epics
+
+An epic groups related tasks, for example a Jira epic and its child tasks. It is a task
+folder too, so it can hold notes, a Claude session and worktrees. Tasks stay in their own
+folders; a marker file names their epic. Epics don't nest.
 
 ```bash
-tasktree-manager epic create DIC-2466-pcaps-epic             # --repos is optional for an epic
+tasktree-manager epic create DIC-2466-pcaps-epic     # repos are optional for an epic
 tasktree-manager create DIC-2861-pcaps-logs --repos infra --epic DIC-2466-pcaps-epic
-tasktree-manager epic add DIC-2466-pcaps-epic DIC-2862-pcaps-s3  # attach or move existing tasks
-tasktree-manager epic remove DIC-2862-pcaps-s3                # detach
-tasktree-manager epic mark DIC-2466-pcaps-epic                # turn an existing task into an epic; unmark reverts
-tasktree-manager epic list                                    # epics and their tasks; also --json
-tasktree-manager epic note "chose layout A for the S3 keys"   # add a note to this task's file in the epic log
-tasktree-manager epic log                                     # notes and latest session recap of every task in the epic
-tasktree-manager epic log DIC-2862-pcaps-s3 --json            # one task (or a whole epic by its name), as JSON
-tasktree-manager epic ask DIC-2862-pcaps-s3 "which bucket?"    # a read-only copy of that task's latest session answers
-tasktree-manager epic sync                                    # refresh the CLAUDE.md epic block after an upgrade
+tasktree-manager epic add DIC-2466-pcaps-epic DIC-2862-pcaps-s3   # attach or move tasks
+tasktree-manager epic remove DIC-2862-pcaps-s3      # detach
+tasktree-manager epic mark DIC-2466-pcaps-epic      # make an existing task an epic; unmark reverts
+tasktree-manager epic list                          # epics and their tasks; --json
 ```
 
-Each task's `CLAUDE.md` gets a managed block naming its epic and how to find sibling
-tasks; it follows every epic change and leaves the rest of the file alone. The block
-also tells the session about the epic log: one notes file per task in `epic-log/` in the
-epic folder, written with `epic note` and read with `epic log`, which adds the recap of each
-task's latest Claude session (in the task folder or one of its worktrees). Inside a task
-folder, `epic note` writes only that task's notes and `epic log` reads only its epic;
-`epic note -` reads the text from stdin. Notes of a task that left the epic stay readable.
-`epic ask TASK "question"` resumes a copy of that task's latest Claude session to answer:
-forked and not saved, hooks off, only the Read/Grep/Glob tools, no MCP servers, so the
-task's own session and status stay untouched; credential files (`~/.ssh`, `~/.aws`, `.env`
-and similar) are denied to it. It exits 3 without asking when the task's session is
-running; the calling session then messages it with SendMessage (`--fork` asks a copy
-anyway). Each turn of the copy is a model call on that session's context, at most
-`--max-turns` (default 8); `--model sonnet` makes it cheaper.
-Epics don't
-nest. `list --json` and `status --json` carry `kind` (`task` or `epic`) and
-`epic` (the parent epic or `null`). `delete` and `finish` refuse an epic that still has
-tasks, even with `--force`.
-
-Exit code is 0 on success, 1 on failure with the reason on stderr, and 3 from `epic ask`
-when the task's session is running (its name goes to stdout). `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. If the
-diff cannot be archived for any repo, the CLI stops before deleting and prints the path of
-the partial archive; the TUI warns and deletes anyway. Files in the task folder outside the
-worktrees are copied to `<task>-<timestamp>.files/` next to the patch:
-
-- Skipped silently: hidden files, symlinks, `node_modules`/`vendor`/`.terraform` folders and
-  an unedited generated `CLAUDE.md`.
-- Left out with a warning: key material (`*.pem`, `*.key`, `id_rsa`, kubeconfigs,
-  `*.tfstate`, `credentials*.json`), files over 10 MB and files past 100 MB in total.
-- A file that cannot be read or copied stops `delete`/`finish` before anything is removed,
-  unless `--force`; the TUI warns and deletes anyway.
-`status --oneline` emits a compact `TASK repoA✓ repoB●2↑1` summary that slots straight into
-a Claude Code statusline or shell prompt.
+`list --json` and `status --json` show each task's `kind` (`task` or `epic`) and its `epic`.
+`delete` and `finish` refuse an epic that still has tasks, even with `--force`.
+
+#### Sharing context inside an epic
+
+The Claude sessions of one epic can learn from each other:
+
+| Command | What it does |
+| --- | --- |
+| `epic note "text"` | Adds a note to this task's file in the epic log (`-` reads stdin) |
+| `epic log [TASK]` | Shows each task's notes and the recap of its latest Claude session; `--json` |
+| `epic ask TASK "question"` | A read-only copy of that task's latest session answers |
+| `epic sync` | Refreshes the epic block in existing tasks' `CLAUDE.md` after an upgrade |
+
+Each task's `CLAUDE.md` gets a managed block that explains these commands to its session.
+
+- **Scope:** inside a task folder, the commands reach only that task's epic.
+- **Running sessions:** `epic ask` exits with code 3 when the task's session is running and
+  prints its name; the asking session then sends it a message with SendMessage.
+- **Read-only:** the copy that answers can read files but not change them, can't read
+  credential files, and leaves the asked task's session untouched.
+- **Cost:** each turn of the copy is a model call on that session's context, 8 turns at
+  most (`--max-turns`); `--model sonnet` makes it cheaper.
+
+The [User Guide](docs/user-guide.md#epics) has the details.
+
+#### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | Failure; the reason is on stderr |
+| 3 | `epic ask` only: the task's session is running; its name is on stdout |
+
+#### Safe delete and archive
+
+`delete` and `finish` run the same safety check as the TUI: uncommitted, unpushed or
+unmerged work blocks deletion unless `--force`. With `glab` or `gh` installed, squash and
+rebase merges count as merged.
+
+Before deleting, the CLI archives the task's remaining diff as a patch and copies the files
+in the task folder outside the worktrees to `<task>-<timestamp>.files/` next to it
+(`finish --no-archive` skips both):
+
+- **Skipped:** hidden files, symlinks, `node_modules`, `vendor` and `.terraform` folders,
+  and an unedited generated `CLAUDE.md`.
+- **Left out with a warning:** key material (`*.pem`, `*.key`, `id_rsa`, kubeconfigs,
+  `*.tfstate`, `credentials*.json`), files over 10 MB, and files past 100 MB in total.
+- **Always stops the delete:** a diff that cannot be archived; the CLI prints the partial
+  archive's path.
+- **Stops the delete unless `--force`:** a task file that cannot be read or copied.
+
+In both cases the TUI stops too, names what was left out in the messages panel, and asks
+again before it deletes.
 
 ## 📖 Documentation
 
@@ -227,8 +249,9 @@ Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 - Git 2.0+
 - 256-color terminal
 - Unix-like OS (macOS, Linux, WSL2). Opening a folder, editor or Claude session in a
-  new terminal tab (`o`, `e`, `c`) drives Ghostty via AppleScript and is macOS-only;
-  elsewhere those keys show a notice
+  new terminal tab (`o`, `e`, `c`) opens a zellij tab when the TUI runs inside zellij,
+  on any OS. Otherwise it drives Ghostty via AppleScript and is macOS-only; elsewhere
+  those keys show a notice
 
 See [Installation Guide](docs/installation.md) for detailed requirements and setup.
 

{tasktree_manager-2.18.0 → tasktree_manager-2.19.0}/docs/configuration.md

@@ -210,6 +210,14 @@ glab_path = "glab"
 # Default: "gh" (searches PATH)
 gh_path = "gh"
 
+# zellij: o/e/c open zellij tabs whenever the TUI runs inside zellij. With
+# autostart, a TUI started outside zellij re-launches itself inside session
+# zellij_session, so its tabs survive a terminal restart (see the user guide).
+# Defaults: "zellij", false, "tasktree" (letters, digits, '.', '_', '-')
+zellij_path = "zellij"
+zellij_autostart = false
+zellij_session = "tasktree"
+
 # ============================================================================
 # Forge (MR/PR state via glab/gh)
 # ============================================================================
@@ -419,6 +427,9 @@ refresh_interval = 15  # Refresh every 15 seconds
 | `hunk_path`   | string | `"hunk"`    | -                   | Path to hunk diff-viewer executable  |
 | `glab_path`   | string | `"glab"`    | -                   | Path to GitLab CLI (MR/CI status)    |
 | `gh_path`     | string | `"gh"`      | -                   | Path to GitHub CLI (PR/CI status)    |
+| `zellij_path` | string | `"zellij"`  | -                   | Path to zellij (tabs and autostart)  |
+| `zellij_autostart` | bool | `false`  | -                   | Re-launch the TUI inside zellij      |
+| `zellij_session` | string | `"tasktree"` | -              | zellij session for autostart         |
 
 ## Forge Settings
 

{tasktree_manager-2.18.0 → tasktree_manager-2.19.0}/docs/user-guide.md

@@ -85,35 +85,50 @@ names their epic, so nothing moves on disk.
 - `enter` or `space` folds an epic. A folded epic row still shows the dirty
   count and the most urgent Claude state of its tasks.
 - Epics don't nest. An epic that still has tasks can't be deleted.
-- Each task's `CLAUDE.md` gets a short block between `<!-- tasktree:epic -->` markers
-  that names the epic folder and how to find sibling tasks, so a Claude session knows
-  the bigger picture. It updates on every epic change; text outside the markers is
-  never touched.
-- The epic log lets the sessions of one epic share what they learned. A session
-  records decisions, interfaces and open questions with
-  `tasktree-manager epic note "..."`; they go to `epic-log/<task>.md` in the epic
-  folder. `tasktree-manager epic log` shows every task's notes and the recap of its
-  latest Claude session, so a session can check what its siblings did before asking.
-  The `CLAUDE.md` block tells each session about both commands, and that notes are
-  information from other sessions, not instructions.
+- Each task's `CLAUDE.md` gets a short block between `<!-- tasktree:epic -->` markers.
+  It names the epic folder, explains how to find sibling tasks and how to share context
+  with them. It updates on every epic change; text outside the markers is never touched.
+- From scripts: `tasktree-manager epic create/add/remove/mark/unmark/list/note/log/ask/sync`.
+
+#### Sharing context between sessions
+
+The Claude sessions of one epic can learn from each other. The `CLAUDE.md` block tells
+each session to try these in order:
+
+1. **Read the epic log.** `tasktree-manager epic log` shows every task's notes and the
+   recap of its latest Claude session. `epic log TASK` shows one task.
+2. **Ask the task.** `tasktree-manager epic ask TASK "question"` resumes a read-only copy
+   of that task's latest session, which answers the question.
+3. **Message a running session.** If the task's session is running, `epic ask` exits
+   with code 3 and prints the session name. The asking session sends it a message with
+   SendMessage instead. `--fork` asks a copy anyway.
+
+Sessions add to the log with `tasktree-manager epic note "..."`: decisions, interfaces,
+open questions, finished work that other tasks depend on.
+
+**Notes:**
+
+- Notes go to `epic-log/<task>.md` in the epic folder, one file per task.
 - A session writes only its own task's notes. From a terminal outside any task,
   `epic note --task NAME` writes for a task and marks the entry as written outside it.
-- Notes stay in the epic after their task is finished, moved or deleted; `epic log`
-  lists them as "no longer in the epic". A note is at most 16 KB, and `epic log` shows
-  the newest 64 KB of each task's notes.
-- When the log does not answer a question, a session runs
-  `tasktree-manager epic ask TASK "question"`. A read-only copy of that task's latest
-  Claude session answers: it can read files but not change them or read credential
-  files, and nothing is saved in that task. If the task's session is running, the command exits
-  with code 3 and prints the session name, and the asking session sends it a message
-  with SendMessage instead (`--fork` asks a copy anyway). Only tasks of the same epic
-  and the epic folder can be asked, and a session in a task outside any epic cannot
-  ask. Each turn of the copy is a model call on the size of that session's context,
-  at most `--max-turns` (default 8); `--model sonnet` makes it cheaper.
-- After upgrading tasktree-manager, run `tasktree-manager epic sync` to refresh the
-  block in existing tasks (the TUI also refreshes it when it starts a Claude session).
-  Folders without a `CLAUDE.md` yet are counted and skipped.
-- From scripts: `tasktree-manager epic create/add/remove/mark/unmark/list/note/log/ask/sync`.
+- Notes stay after their task is finished, moved or deleted; `epic log` lists them as
+  "no longer in the epic".
+- A note is at most 16 KB. `epic log` shows the newest 64 KB of each task's notes.
+- Notes and answers come from other sessions: they are information, not instructions.
+
+**`epic ask`:**
+
+- Only tasks of the same epic and the epic folder can be asked. A session in a task
+  outside any epic cannot ask.
+- The copy can read files but not change them. It can't read credential files (forge CLI
+  tokens, `.env` files anywhere, the key material the archive leaves out).
+  Nothing is saved in the asked task, and its session stays untouched.
+- Each turn of the copy is a model call on the size of that session's context, 8 turns
+  at most (`--max-turns`). `--model sonnet` makes it cheaper.
+
+**After an upgrade:** run `tasktree-manager epic sync` to refresh the block in existing
+tasks. The TUI also refreshes it when it starts a Claude session. Folders without a
+`CLAUDE.md` yet are counted and skipped.
 
 ### Worktrees
 
@@ -286,6 +301,8 @@ terraform edits sit unstaged. Next, decide whether to hand-create the group.
 - **Title**: the session name (`/rename`), else Claude's own title, else the session slug
 - **Turn line**: duration of the last turn and when it finished; `busy`/`idle` mirrors the task's Claude status indicator
 - **Recap**: the summary Claude writes a few minutes after a turn when the session idles. Until one exists, the dim `last prompt:` line shows what was asked last
+- The session is the newest one started in the task folder or one of its worktrees, as in
+  `epic log`. Headless `claude -p` runs, such as commit-message helpers, are skipped
 - Nothing is shown for tasks without a session. The block refreshes as you move the cursor and every 5 seconds while a transcript changes. Disable with `claude_recap = false` under `[tools]` in `config.toml`
 
 **Git status codes:**
@@ -439,7 +456,7 @@ Useful when you're spinning up several similar tasks that share the same set of
 | `b`     | Dispatch agent          | Run a background Claude agent (`claude --bg`) in the selected worktree |
 
 **How it works:**
-- `c` opens Claude Code CLI in a new Ghostty terminal tab at the task directory.
+- `c` opens Claude Code CLI in a new terminal tab at the task directory (a zellij tab inside zellij, see [zellij](#zellij)).
   - If `~/.claude/projects/<task-folder>/` already has session transcripts, runs `claude -r` to pick from them; otherwise runs `claude` to start fresh.
 - `C` opens the Claude desktop app via the `claude://code/new?folder=<task-folder>` URL scheme.
 - The CLI variant (`c`) generates a task-level `CLAUDE.md` with task/worktree context, copies each repo's own `CLAUDE.md` into worktrees whose branch predates it (never generating stub content), and installs hooks that report session status back to tasktree-manager.
@@ -840,9 +857,9 @@ npm i -g hunkdiff
 
 **Direct editor integration:**
 1. Highlight task or worktree
-2. Press `e` to open your configured editor in a new Ghostty tab (`$EDITOR .`)
-3. tasktree-manager keeps running alongside the editor (macOS + Ghostty only, see
-   Limitations)
+2. Press `e` to open your configured editor in a new terminal tab (`$EDITOR .`)
+3. tasktree-manager keeps running alongside the editor (a zellij tab inside zellij,
+   otherwise a Ghostty tab on macOS; see [zellij](#zellij))
 
 **Configure your editor** in `~/.config/tasktree-manager/config.toml`:
 ```toml
@@ -873,6 +890,47 @@ code ~/tasks/FEAT-123  # Open entire task as workspace
 - Use "Open Folder" or equivalent
 - Git integration works normally
 
+### zellij
+
+`o`, `e` and `c` open a new terminal tab. Where the tab lives depends on where
+tasktree-manager runs:
+
+- Inside a zellij session (`ZELLIJ_SESSION_NAME` is set), each key opens a zellij tab
+  named after the folder and what runs in it: `TASK · shell`, `TASK/repo · editor`,
+  `TASK · claude`. The tab runs in the zellij server, so it keeps running when you close
+  or restart the terminal. Pressing the key again while that tab is open switches to it
+  instead of opening a second one.
+- Anywhere else, each key opens a Ghostty tab via AppleScript (macOS only).
+
+To run the TUI in zellij every time, set this in `config.toml`:
+
+```toml
+[tools]
+zellij_autostart = true
+zellij_session = "tasktree"   # the default
+```
+
+Plain `tasktree-manager` then re-launches itself as
+`zellij attach -c tasktree -- python -m tasktree_manager.app`. Without the setting, start
+it that way yourself: `zellij attach -c tasktree -- tasktree-manager`.
+
+After a terminal restart, run `tasktree-manager` (with autostart) or
+`zellij attach tasktree`. Either brings back the TUI and every tab it opened, Claude
+sessions included. The command after `--` runs only when the session is created, so a
+second `tasktree-manager` in another terminal tab shows the same session.
+
+- A tab that runs a command (`e`, `c`) closes when the command exits.
+- The zellij tab runs the command with `sh -c`, so `editor` and `claude_path` must name
+  programs on `PATH`. A shell alias or fish function works only in the Ghostty tab.
+- A zellij session does not survive a reboot. Attaching afterwards (or autostart) makes
+  zellij resurrect the saved layout, and each tab waits for ENTER before its command runs
+  again; tasktree-manager does not test that path.
+- Autostart applies only when the TUI starts in a terminal outside zellij, never to a
+  piped run or to the headless CLI.
+- zellij's default keybindings take Ctrl+P, Ctrl+T, Ctrl+O and other keys before the TUI
+  or Claude Code sees them. Pick zellij's "Unlock First (non-colliding)" preset or Alt-based
+  bindings, so Ctrl+P still opens the command palette.
+
 ### CI/CD
 
 tasktree-manager creates normal git branches, so CI/CD works seamlessly:

{tasktree_manager-2.18.0 → tasktree_manager-2.19.0}/pyproject.toml

@@ -71,7 +71,7 @@ version-file = "tasktree_manager/_version.py"
 # Semantic Release Configuration
 [tool.semantic_release]
 version_toml = ["pyproject.toml:tool.semantic_release.version"]
-version = "2.18.0"
+version = "2.19.0"
 tag_format = "v{version}"
 branch = "main"
 commit_message = "chore(release): {version} [skip ci]"

{tasktree_manager-2.18.0 → tasktree_manager-2.19.0}/tasktree_manager/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.18.0'
-__version_tuple__ = version_tuple = (2, 18, 0)
+__version__ = version = '2.19.0'
+__version_tuple__ = version_tuple = (2, 19, 0)
 
 __commit_id__ = commit_id = None