gitdirector 1.5.2__tar.gz → 1.6.0__tar.gz

{gitdirector-1.5.2 → gitdirector-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: gitdirector
-Version: 1.5.2
+Version: 1.6.0
 Summary: A terminal based control plane for developers working across multiple repositories. Launch multiple AI coding agents, multiple tmux sessions and track changes across all your repos in one place.
 Keywords: git,repository,manager,cli,synchronization,batch
 Author: Anito Anto
@@ -24,7 +24,6 @@ Requires-Dist: rich>=12.0
 Requires-Dist: textual>=8.2.1
 Requires-Dist: tiktoken>=0.5.0
 Requires-Dist: pyte>=0.8.2
-Requires-Dist: black>=23.0 ; extra == 'dev'
 Requires-Dist: pytest>=7.0 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0 ; extra == 'dev'
@@ -49,7 +48,7 @@ A terminal based control plane for developers working across multiple repositori
 
 If you work across more than a handful of repositories, the overhead adds up fast. Jumping between terminals to check states, pull changes, and babysit agents is friction you don't need.
 
-GitDirector gives you a single cockpit for all of it. See every repo's status, Drop into any of them. Run AI agents in parallel, each isolated in its own tmux session, while you monitor everything from the dashboard. Less tab-switching, more shipping.
+GitDirector gives you a single cockpit for all of it. See every repo's status, drop into any of them. Run AI agents in parallel, each isolated in its own tmux session, while you monitor everything from the dashboard. Less tab-switching, more shipping.
 
 ## Installation
 
@@ -65,19 +64,22 @@ If you find GitDirector useful, please star this repository on GitHub, we need m
 
 ## Usage
 
-| Command                                      | Description                                            |
-| -------------------------------------------- | ------------------------------------------------------ |
-| `gitdirector console`                        | Open the interactive TUI dashboard                     |
-| `gitdirector link PATH [--discover]`         | Link a repository or discover all under a path         |
-| `gitdirector unlink PATH\|NAME [--discover]` | Unlink a repository by path, name, or all under a path |
-| `gitdirector list`                           | List all tracked repositories with live status         |
-| `gitdirector status`                         | Show repositories with staged/unstaged files           |
-| `gitdirector pull`                           | Pull latest changes for all tracked repositories       |
-| `gitdirector cd NAME`                        | Open or switch to a tmux session for a repository      |
-| `gitdirector autoclean`                      | Remove broken repository links from tracking           |
-| `gitdirector info PATH\|NAME [--full]`       | Show file statistics for a repository                  |
-| `gitdirector gd-tmux PATH\|NAME "command"`   | Create a gd tmux session and run a command in it       |
-| `gitdirector help`                           | Show help                                              |
+| Command                                                    | Description                                            |
+| ---------------------------------------------------------- | ------------------------------------------------------ |
+| `gitdirector console`                                      | Open the interactive TUI dashboard                     |
+| `gitdirector link PATH [--discover]`                       | Link a repository or discover all under a path         |
+| `gitdirector unlink PATH\|NAME [--discover]`               | Unlink a repository by path, name, or all under a path |
+| `gitdirector list`                                         | List all tracked repositories with live status         |
+| `gitdirector status`                                       | Show repositories with staged/unstaged files           |
+| `gitdirector pull [--yes]`                                 | Pull latest changes for all tracked repositories       |
+| `gitdirector cd NAME`                                      | Open or switch to a tmux session for a repository      |
+| `gitdirector autoclean`                                    | Remove broken repository links from tracking           |
+| `gitdirector info PATH\|NAME [--full]`                     | Show file statistics for a repository                  |
+| `gitdirector gd-tmux PATH\|NAME "command" [--description TEXT]` | Create a gd tmux session and run a command in it       |
+| `gitdirector gd-capture SESSION [--lines N] [--full]`      | Print the scrollback of a live gd tmux session         |
+| `gitdirector gd-send SESSION [TEXT] [--enter\|--key C-c]` | Send text or Ctrl-C to a live gd tmux session          |
+| `gitdirector completion SHELL`                             | Print shell completion setup for bash, zsh, or fish    |
+| `gitdirector help`                                         | Show help                                              |
 
 ### link
 
@@ -97,10 +99,12 @@ Opens a full interactive TUI dashboard.
 Features:
 
 - Live table with sync state, branch, changes, last commit, and active tmux sessions
+- Tabs for `[1] Repositories`, `[2] Sessions`, and `[3] Panels`
 - `j`/`k` or arrow keys to navigate
-- `/` to filter repositories by name or path
-- `s` to cycle sort by any column
+- `/` to filter the active tab
+- `s` to sort the active table
 - `i` to show repository info (file count, lines, tokens, max depth, top file types)
+- `g` on the Repositories tab to open Git operations: status, timeline, branches, remotes, pull, and push
 - `r` to refresh all statuses
 - Press `enter` on any repository to open an action menu:
     - **New tmux session** — create and attach a session for the repository
@@ -108,6 +112,9 @@ Features:
     - **Attach existing session** — switch to any already-running tmux session
     - **Launch AI agent** — open OpenCode, Claude Code, GitHub Copilot, Codex, or Pi in a new tmux session
     - **Remove session** — kill a running tmux session
+- **Repository groups** appear directly in the Repositories tab when linked repositories share the same parent directory. Group rows can be expanded/collapsed with `space`; press `enter` on a group to start, attach, remove, or launch AI-agent sessions rooted at that parent directory.
+- **Sessions tab** (press `2`) lists every active `gd/*` tmux session with its status, purpose, repository, **description**, and full session name. The description column is free-form text stored on the session (default `"-"`), with a width that scales to your terminal and wraps long text. Highlight a row and press `d` to edit its description.
+- **Panels tab** (press `3`) manages reusable tmux panel layouts. Press `n` to create a panel, or `enter` on a panel to open, reconfigure, rename, or delete it.
 
 ### unlink
 
@@ -157,8 +164,16 @@ Shows repositories with uncommitted changes (staged and/or unstaged files). Prin
 
 ### pull
 
+```bash
+gitdirector pull          # prompts before pulling
+gitdirector pull --yes    # skip confirmation
+gitdirector pull -y       # short form
+```
+
 Pulls all tracked repositories concurrently using fast-forward only on each repository's current branch (`git pull --ff-only origin <current-branch>`). Reports success or failure per repository.
 
+By default, `pull` asks for confirmation after listing the repositories it will update. Use `--yes` / `-y` for non-interactive runs.
+
 ### cd
 
 ```bash
@@ -182,14 +197,23 @@ Opens a [tmux](https://github.com/tmux/tmux) session rooted at the repository di
 gitdirector gd-tmux my-repo "npm test"
 gitdirector gd-tmux /path/to/my-repo "make build"
 gitdirector gd-tmux my-repo 'echo "hello world"'
+gitdirector gd-tmux my-repo "opencode" --description "OpenCode: refactor auth middleware"
 ```
 
-Creates a new gd tmux session rooted at the given repository, runs the supplied command inside it, and attaches the session. The session is created using the same code path the TUI's **Launch AI agent** menu uses: it is a real `gd/{repo}/{command}/{N}` session, visible in the Sessions tab of `gitdirector console`, and it self-destructs when the command exits.
+Creates a new gd tmux session rooted at the given repository, runs the supplied command inside it, and returns immediately without attaching. The session is a real `gd/{repo}/shell/{N}` session, visible in the Sessions tab of `gitdirector console`, and it self-destructs when the command exits. `N` is allocated as one higher than the highest currently running matching shell session number.
 
 - `PATH|NAME` — accept either an absolute path to a tracked repository or its basename, with the same disambiguation rules as `gitdirector unlink`.
 - `"command"` — the shell command to run inside the new session. Pass it quoted so the shell hands the whole string to gitdirector; quotes and arguments are preserved verbatim.
+- `--description` / `-d` — optional. Free-text description stored on the session and shown in the Sessions tab. Accepts both `--description "text"` and `--description=text` forms. When omitted, the column displays `"-"`.
+
+The full session name (e.g. `gd/myrepo/shell/1`) is printed to stdout right after the background session is created, so scripts and agents can capture it for later use with `gd-capture`:
+
+```bash
+SESSION=$(gitdirector gd-tmux /path/to/repo opencode --description "OpenCode: refactor auth")
+gitdirector gd-capture "$SESSION" --lines 100
+```
 
-The command is the same as opening the repo in the console, picking **Launch AI agent** from the action menu, and entering the command — but you can do it from any shell without entering the TUI first. The new session shows up in the Sessions tab immediately.
+Use this from any shell to start a background command without entering the TUI first. The new session shows up in the Sessions tab immediately. Inside the TUI, highlight any session row and press `d` to edit its description.
 
 ### autoclean
 
@@ -199,44 +223,43 @@ gitdirector autoclean
 
 Scans the tracked repositories in `~/.gitdirector/config.yaml` for paths that no longer exist on disk and removes them from the config. Lists any broken links for review and asks for confirmation before deleting them.
 
-## Note for AI coding agents
-
-If you are an AI coding agent reading this project: when the user asks you to run a long-lived process inside a tracked repository — a dev server, a frontend bundler, a backend API, a watcher, a database, a test runner with a long timeout, or anything else that does not exit on its own — **do not run it in the foreground**. A foreground process will block your shell for the rest of the session and the user will not be able to interact with you.
+### gd-capture
 
-Use `gitdirector gd-tmux` to launch the process in a detached gd tmux session that the user can monitor and tear down themselves. The session shows up in the Sessions tab of `gitdirector console`, auto-cleans up when the process exits, and supports path-or-name lookup the same way every other gitdirector command does.
+```bash
+gitdirector gd-capture gd/myrepo/shell/1                # last 200 lines
+gitdirector gd-capture gd/myrepo/shell/1 --lines 50    # last 50 lines
+gitdirector gd-capture gd/myrepo/shell/1 --full        # entire scrollback
+```
 
-**Always prefer the absolute path over the repo name.** The by-name lookup matches the *directory name on disk* verbatim (via `Path.name`) — case-sensitive, dots and spaces included — and is ambiguous if two tracked repos share the same basename. When in doubt, look up the path with `gitdirector list` and use the absolute path. Quoting a path is fine; an absolute path is never ambiguous.
+Prints the current scrollback of a live `gd/*` tmux session to stdout (plain text, pipeable into `grep`/`less`/etc.). The argument is the full session name as shown in the TUI Sessions tab. It must match the `gd/<repo>/<purpose>/<N>` shape; sessions created by `gd-tmux` use `gd/<repo>/shell/<N>`.
 
-Examples:
+**Only running sessions can be captured.** `gd-tmux` sessions self-destruct when their command exits (success or failure), so for any *finished* session you have to have redirected the command's own output to a file:
 
 ```bash
-# Frontend dev server in the user's web repo — use the absolute path
-gitdirector gd-tmux /Users/me/projects/webapp "npm run dev"
-
-# Backend API in the api repo
-gitdirector gd-tmux /Users/me/projects/api "uvicorn app.main:app --reload --port 8000"
+gitdirector gd-tmux myrepo "make test 2>&1 | tee /tmp/run.log"
+```
 
-# A long-running integration test with output captured to a log
-gitdirector gd-tmux /Users/me/projects/myrepo "pytest -x -v 2>&1 | tee /tmp/test.log"
+The session is gone the moment the command exits; the scrollback lives on only as the bytes the process actually wrote.
 
-# A watcher or build loop
-gitdirector gd-tmux /Users/me/projects/myrepo "npm run watch"
+### gd-send
 
-# A repo whose directory name contains a space — quote both the path and the command
-gitdirector gd-tmux "/Users/me/projects/My Repo" "npm run dev"
+```bash
+gitdirector gd-send gd/myrepo/opencode/1 "continue and run the tests"
+gitdirector gd-send gd/myrepo/shell/1 "npm test" --enter
+gitdirector gd-send gd/myrepo/shell/1 --key C-c
 ```
 
-The by-name form is supported for ergonomic use by humans in interactive shells, but agents should default to the absolute path to avoid any chance of matching the wrong repo.
+Sends input to a live `gd/*` tmux session. The session argument must be the full session name shown in the TUI Sessions tab, for example `gd/myrepo/shell/1`.
+
+- `TEXT` is pasted into the active pane. It does not press Enter unless `--enter` is provided.
+- `--enter` presses Enter after pasting `TEXT`, useful for running shell commands.
+- `--key C-c` sends Ctrl-C to the active pane, useful for stopping a running foreground process without killing the tmux session.
 
-Rules of thumb:
+Accepted `--key` values: `C-c`.
 
-- **Use the absolute path.** It is unambiguous and survives the user renaming or moving the directory. The by-name form is convenient shorthand, not a slug — it is the raw directory name, case-sensitive.
-- **Repo names with spaces, dots, or punctuation are matched verbatim** when you do use the by-name form. A repo at `/Users/me/My Repo` is matched by `"My Repo"`, not by `My` or `Repo`. Quote the name to keep the shell from splitting it.
-- **Quoting the command matters.** The command string is handed to `sh -lc` inside the new session, so write it as a single quoted string. `'echo "hi"'` (single-quote outer, double-quote inner) is the safest pattern for embedded double quotes.
-- **Path separators in the command are fine.** Commands like `python /path/to/script.py` or `find . -name foo/bar` work; the command is embedded verbatim into the inner shell, while the session-name label is auto-sanitized.
-- **The session self-destructs** when the command exits (success or failure), so you do not need to clean it up.
-- **If you need to capture output**, redirect it to a file in the command itself (`> /tmp/out 2>&1`) and read the file later — the session is gone once the command exits.
-- **If the user asks you to stop a running process**, kill the matching session: `gitdirector console` → Sessions tab, or directly with `tmux kill-session -t =<session-name>`.
+## For AI coding agents
+
+If you are an AI coding agent (Claude Code, OpenCode, GitHub Copilot, Codex, Pi, or any other tool that drives a shell on the user's behalf), the rules for integrating with the user's GitDirector workflow — including `gd-tmux` background sessions, `gd-capture`, and the mandatory `--description` flag — live in [`LLMS.md`](./LLMS.md). Read that file end-to-end before running any commands.
 
 ## Configuration
 
@@ -248,8 +271,19 @@ repositories:
     - /path/to/repo2
 max_workers: 10 # optional, valid range 1-32, default 10
 theme: rose-pine # optional, default rose-pine
+github_username: your-github-username # optional
+github_PAT: github_pat_or_classic_pat # optional
 ```
 
+### GitHub PAT fallback
+
+GitDirector first runs git commands using your normal local git credentials. If a git command fails with an authentication error and both `github_username` and `github_PAT` are configured, GitDirector retries the command with a temporary Git credential helper for `https://github.com` remotes.
+
+- This only applies to HTTPS GitHub remotes.
+- SSH remotes still use your normal SSH key/agent setup.
+- The PAT is stored in plaintext in `~/.gitdirector/config.yaml`; use an appropriately scoped token and protect that file.
+- The PAT is not passed on the command line or shown in TUI command output.
+
 ### Available Themes
 
 `textual-dark`, `textual-light`, `nord`, `gruvbox`, `catppuccin-mocha`, `textual-ansi`, `dracula`, `tokyo-night`, `monokai`, `flexoki`, `catppuccin-latte`, `catppuccin-frappe`, `catppuccin-macchiato`, `solarized-light`, `solarized-dark`, `rose-pine`, `rose-pine-moon`, `rose-pine-dawn`, `atom-one-dark`, `atom-one-light`
@@ -258,7 +292,17 @@ theme: rose-pine # optional, default rose-pine
 
 - Python 3.10+
 - Git
-- [tmux](https://github.com/tmux/tmux) ≥ 3.2a (for `gitdirector cd`)
+- [tmux](https://github.com/tmux/tmux) ≥ 3.2a (for `gitdirector cd`, `gitdirector console` sessions, `gitdirector gd-tmux`, `gitdirector gd-capture`, and `gitdirector gd-send`)
+
+## Shell completion
+
+Generate shell completions for `bash`, `zsh`, or `fish`. Completion includes subcommands, options, and linked repository names for repo-target commands.
+
+```bash
+eval "$(gitdirector completion bash)"
+eval "$(gitdirector completion zsh)"
+gitdirector completion fish | source
+```
 
 ## License
 

gitdirector-1.6.0/README.md

@@ -0,0 +1,267 @@
+# GitDirector
+
+A terminal based control plane for developers working across multiple repositories. Launch multiple AI coding agents, multiple tmux sessions and track changes across all your repos in one place.
+
+## Why GitDirector?
+
+If you work across more than a handful of repositories, the overhead adds up fast. Jumping between terminals to check states, pull changes, and babysit agents is friction you don't need.
+
+GitDirector gives you a single cockpit for all of it. See every repo's status, drop into any of them. Run AI agents in parallel, each isolated in its own tmux session, while you monitor everything from the dashboard. Less tab-switching, more shipping.
+
+## Installation
+
+```bash
+pip install gitdirector
+```
+
+Requires Python 3.10+.
+
+## Support
+
+If you find GitDirector useful, please star this repository on GitHub, we need more stars to qualify for inclusion in Homebrew. Your support helps a lot, thank you!
+
+## Usage
+
+| Command                                                    | Description                                            |
+| ---------------------------------------------------------- | ------------------------------------------------------ |
+| `gitdirector console`                                      | Open the interactive TUI dashboard                     |
+| `gitdirector link PATH [--discover]`                       | Link a repository or discover all under a path         |
+| `gitdirector unlink PATH\|NAME [--discover]`               | Unlink a repository by path, name, or all under a path |
+| `gitdirector list`                                         | List all tracked repositories with live status         |
+| `gitdirector status`                                       | Show repositories with staged/unstaged files           |
+| `gitdirector pull [--yes]`                                 | Pull latest changes for all tracked repositories       |
+| `gitdirector cd NAME`                                      | Open or switch to a tmux session for a repository      |
+| `gitdirector autoclean`                                    | Remove broken repository links from tracking           |
+| `gitdirector info PATH\|NAME [--full]`                     | Show file statistics for a repository                  |
+| `gitdirector gd-tmux PATH\|NAME "command" [--description TEXT]` | Create a gd tmux session and run a command in it       |
+| `gitdirector gd-capture SESSION [--lines N] [--full]`      | Print the scrollback of a live gd tmux session         |
+| `gitdirector gd-send SESSION [TEXT] [--enter\|--key C-c]` | Send text or Ctrl-C to a live gd tmux session          |
+| `gitdirector completion SHELL`                             | Print shell completion setup for bash, zsh, or fish    |
+| `gitdirector help`                                         | Show help                                              |
+
+### link
+
+```bash
+gitdirector link /path/to/repo
+gitdirector link /path/to/folder --discover   # recursively find and link all repos
+```
+
+### console
+
+```bash
+gitdirector console
+```
+
+Opens a full interactive TUI dashboard.
+
+Features:
+
+- Live table with sync state, branch, changes, last commit, and active tmux sessions
+- Tabs for `[1] Repositories`, `[2] Sessions`, and `[3] Panels`
+- `j`/`k` or arrow keys to navigate
+- `/` to filter the active tab
+- `s` to sort the active table
+- `i` to show repository info (file count, lines, tokens, max depth, top file types)
+- `g` on the Repositories tab to open Git operations: status, timeline, branches, remotes, pull, and push
+- `r` to refresh all statuses
+- Press `enter` on any repository to open an action menu:
+    - **New tmux session** — create and attach a session for the repository
+    - **Review Diff** — open a two-pane viewer for uncommitted changes (left: file list with GitHub-style status pills and +/- counts; right: per-file unified diff with GitHub-dark syntax highlighting, line numbers, and green/red backgrounds for added/removed lines). Navigate files with `j`/`k`, `n`/`p`, `g`/`G`, or `]`/`[`. Switch the focused panel with `tab`. `r` refreshes, `esc` closes.
+    - **Attach existing session** — switch to any already-running tmux session
+    - **Launch AI agent** — open OpenCode, Claude Code, GitHub Copilot, Codex, or Pi in a new tmux session
+    - **Remove session** — kill a running tmux session
+- **Repository groups** appear directly in the Repositories tab when linked repositories share the same parent directory. Group rows can be expanded/collapsed with `space`; press `enter` on a group to start, attach, remove, or launch AI-agent sessions rooted at that parent directory.
+- **Sessions tab** (press `2`) lists every active `gd/*` tmux session with its status, purpose, repository, **description**, and full session name. The description column is free-form text stored on the session (default `"-"`), with a width that scales to your terminal and wraps long text. Highlight a row and press `d` to edit its description.
+- **Panels tab** (press `3`) manages reusable tmux panel layouts. Press `n` to create a panel, or `enter` on a panel to open, reconfigure, rename, or delete it.
+
+### unlink
+
+```bash
+gitdirector unlink /path/to/repo         # unlink by full path
+gitdirector unlink my-repo               # unlink by repository name
+gitdirector unlink /path/to/folder --discover  # unlink all repos under a path
+```
+
+If multiple tracked repositories share the same name, `gitdirector` will refuse and list the conflicting paths so you can use the full path instead.
+
+### info
+
+```bash
+gitdirector info /path/to/repo        # by path
+gitdirector info my-repo               # by name
+gitdirector info my-repo --full        # show all file extensions
+```
+
+Shows file statistics for a repository:
+
+- Total file count, line count, token count, and max directory depth
+- Top 10 file types by count with line and token breakdowns (use `--full` to show all)
+- Files without extensions grouped as `(no ext)`
+- Remaining types grouped as `others`
+- Binary files show `-` for lines and tokens
+- All operations respect `.gitignore` at every level
+
+Also available in the TUI console by pressing `i` on a selected repository.
+
+### list
+
+Displays a live table of all tracked repositories with:
+
+- Sync state: `up to date`, `ahead`, `behind`, `diverged`, or `unknown`
+- Current branch
+- Staged/unstaged changes
+- Last commit (relative time)
+- Tracked file size
+- Path
+
+Checks run concurrently (default: 10 workers, configurable from 1 to 32).
+
+### status
+
+Shows repositories with uncommitted changes (staged and/or unstaged files). Prints a summary of total, clean, and changed repo counts.
+
+### pull
+
+```bash
+gitdirector pull          # prompts before pulling
+gitdirector pull --yes    # skip confirmation
+gitdirector pull -y       # short form
+```
+
+Pulls all tracked repositories concurrently using fast-forward only on each repository's current branch (`git pull --ff-only origin <current-branch>`). Reports success or failure per repository.
+
+By default, `pull` asks for confirmation after listing the repositories it will update. Use `--yes` / `-y` for non-interactive runs.
+
+### cd
+
+```bash
+gitdirector cd my-repo
+```
+
+Opens a [tmux](https://github.com/tmux/tmux) session rooted at the repository directory, or switches to it if a session for that repo already exists.
+
+- **Inside tmux** — switches the current client to the target session.
+- **Outside tmux** — replaces the current process with `tmux attach-session`, handing the terminal over to tmux.
+
+> **Requires tmux to be installed on your system.**
+>
+> macOS: `brew install tmux`  
+> Debian/Ubuntu: `sudo apt install tmux`  
+> Arch: `sudo pacman -S tmux`
+
+### gd-tmux
+
+```bash
+gitdirector gd-tmux my-repo "npm test"
+gitdirector gd-tmux /path/to/my-repo "make build"
+gitdirector gd-tmux my-repo 'echo "hello world"'
+gitdirector gd-tmux my-repo "opencode" --description "OpenCode: refactor auth middleware"
+```
+
+Creates a new gd tmux session rooted at the given repository, runs the supplied command inside it, and returns immediately without attaching. The session is a real `gd/{repo}/shell/{N}` session, visible in the Sessions tab of `gitdirector console`, and it self-destructs when the command exits. `N` is allocated as one higher than the highest currently running matching shell session number.
+
+- `PATH|NAME` — accept either an absolute path to a tracked repository or its basename, with the same disambiguation rules as `gitdirector unlink`.
+- `"command"` — the shell command to run inside the new session. Pass it quoted so the shell hands the whole string to gitdirector; quotes and arguments are preserved verbatim.
+- `--description` / `-d` — optional. Free-text description stored on the session and shown in the Sessions tab. Accepts both `--description "text"` and `--description=text` forms. When omitted, the column displays `"-"`.
+
+The full session name (e.g. `gd/myrepo/shell/1`) is printed to stdout right after the background session is created, so scripts and agents can capture it for later use with `gd-capture`:
+
+```bash
+SESSION=$(gitdirector gd-tmux /path/to/repo opencode --description "OpenCode: refactor auth")
+gitdirector gd-capture "$SESSION" --lines 100
+```
+
+Use this from any shell to start a background command without entering the TUI first. The new session shows up in the Sessions tab immediately. Inside the TUI, highlight any session row and press `d` to edit its description.
+
+### autoclean
+
+```bash
+gitdirector autoclean
+```
+
+Scans the tracked repositories in `~/.gitdirector/config.yaml` for paths that no longer exist on disk and removes them from the config. Lists any broken links for review and asks for confirmation before deleting them.
+
+### gd-capture
+
+```bash
+gitdirector gd-capture gd/myrepo/shell/1                # last 200 lines
+gitdirector gd-capture gd/myrepo/shell/1 --lines 50    # last 50 lines
+gitdirector gd-capture gd/myrepo/shell/1 --full        # entire scrollback
+```
+
+Prints the current scrollback of a live `gd/*` tmux session to stdout (plain text, pipeable into `grep`/`less`/etc.). The argument is the full session name as shown in the TUI Sessions tab. It must match the `gd/<repo>/<purpose>/<N>` shape; sessions created by `gd-tmux` use `gd/<repo>/shell/<N>`.
+
+**Only running sessions can be captured.** `gd-tmux` sessions self-destruct when their command exits (success or failure), so for any *finished* session you have to have redirected the command's own output to a file:
+
+```bash
+gitdirector gd-tmux myrepo "make test 2>&1 | tee /tmp/run.log"
+```
+
+The session is gone the moment the command exits; the scrollback lives on only as the bytes the process actually wrote.
+
+### gd-send
+
+```bash
+gitdirector gd-send gd/myrepo/opencode/1 "continue and run the tests"
+gitdirector gd-send gd/myrepo/shell/1 "npm test" --enter
+gitdirector gd-send gd/myrepo/shell/1 --key C-c
+```
+
+Sends input to a live `gd/*` tmux session. The session argument must be the full session name shown in the TUI Sessions tab, for example `gd/myrepo/shell/1`.
+
+- `TEXT` is pasted into the active pane. It does not press Enter unless `--enter` is provided.
+- `--enter` presses Enter after pasting `TEXT`, useful for running shell commands.
+- `--key C-c` sends Ctrl-C to the active pane, useful for stopping a running foreground process without killing the tmux session.
+
+Accepted `--key` values: `C-c`.
+
+## For AI coding agents
+
+If you are an AI coding agent (Claude Code, OpenCode, GitHub Copilot, Codex, Pi, or any other tool that drives a shell on the user's behalf), the rules for integrating with the user's GitDirector workflow — including `gd-tmux` background sessions, `gd-capture`, and the mandatory `--description` flag — live in [`LLMS.md`](./LLMS.md). Read that file end-to-end before running any commands.
+
+## Configuration
+
+Config is stored at `~/.gitdirector/config.yaml`.
+
+```yaml
+repositories:
+    - /path/to/repo1
+    - /path/to/repo2
+max_workers: 10 # optional, valid range 1-32, default 10
+theme: rose-pine # optional, default rose-pine
+github_username: your-github-username # optional
+github_PAT: github_pat_or_classic_pat # optional
+```
+
+### GitHub PAT fallback
+
+GitDirector first runs git commands using your normal local git credentials. If a git command fails with an authentication error and both `github_username` and `github_PAT` are configured, GitDirector retries the command with a temporary Git credential helper for `https://github.com` remotes.
+
+- This only applies to HTTPS GitHub remotes.
+- SSH remotes still use your normal SSH key/agent setup.
+- The PAT is stored in plaintext in `~/.gitdirector/config.yaml`; use an appropriately scoped token and protect that file.
+- The PAT is not passed on the command line or shown in TUI command output.
+
+### Available Themes
+
+`textual-dark`, `textual-light`, `nord`, `gruvbox`, `catppuccin-mocha`, `textual-ansi`, `dracula`, `tokyo-night`, `monokai`, `flexoki`, `catppuccin-latte`, `catppuccin-frappe`, `catppuccin-macchiato`, `solarized-light`, `solarized-dark`, `rose-pine`, `rose-pine-moon`, `rose-pine-dawn`, `atom-one-dark`, `atom-one-light`
+
+## Requirements
+
+- Python 3.10+
+- Git
+- [tmux](https://github.com/tmux/tmux) ≥ 3.2a (for `gitdirector cd`, `gitdirector console` sessions, `gitdirector gd-tmux`, `gitdirector gd-capture`, and `gitdirector gd-send`)
+
+## Shell completion
+
+Generate shell completions for `bash`, `zsh`, or `fish`. Completion includes subcommands, options, and linked repository names for repo-target commands.
+
+```bash
+eval "$(gitdirector completion bash)"
+eval "$(gitdirector completion zsh)"
+gitdirector completion fish | source
+```
+
+## License
+
+MIT

{gitdirector-1.5.2 → gitdirector-1.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "gitdirector"
-version = "1.5.2"
+version = "1.6.0"
 description = "A terminal based control plane for developers working across multiple repositories. Launch multiple AI coding agents, multiple tmux sessions and track changes across all your repos in one place."
 readme = "README.md"
 license = { text = "MIT" }
@@ -41,7 +41,6 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = [
-    "black>=23.0",
     "pytest>=7.0",
     "pytest-asyncio>=0.23",
     "pytest-cov>=4.0",
@@ -64,7 +63,6 @@ managed = true
 
 [dependency-groups]
 dev = [
-    "black>=23.0",
     "pytest>=7.0",
     "pytest-asyncio>=0.23",
     "pytest-cov>=4.0",
@@ -73,10 +71,6 @@ dev = [
     "ruff>=0.1.0",
 ]
 
-[tool.black]
-line-length = 100
-target-version = ["py310", "py311", "py312"]
-
 [tool.ruff]
 line-length = 100
 target-version = "py310"

{gitdirector-1.5.2 → gitdirector-1.6.0}/src/gitdirector/cli.py

@@ -8,8 +8,11 @@ from .commands import (
     _path_text,
     _status_text,
     autoclean,
+    capture,
     cd,
+    completion,
     console,
+    gd_send,
     gd_tmux,
     help,
     info,
@@ -41,7 +44,8 @@ class _HelpGroup(click.Group):
 @click.group(cls=_HelpGroup, invoke_without_command=True)
 @click.pass_context
 def cli(ctx):
-    print_update_notice()
+    if not ctx.resilient_parsing and ctx.invoked_subcommand != "completion":
+        print_update_notice()
     if ctx.invoked_subcommand is None:
         show_help()
 
@@ -57,6 +61,9 @@ tui.register(cli)
 autoclean.register(cli)
 info.register(cli)
 gd_tmux.register(cli)
+capture.register(cli)
+gd_send.register(cli)
+completion.register(cli)
 
 
 def main():