`README.md`

48 lines
# iterm-project-grouper

Group iTerm2 sessions by project — **each project's Claude sessions as tabs in one window**.

## The tools

### `claude-proj` — the launcher (Option B, the real solution)
Opens a Claude Code session as a **tab inside its project's dedicated iTerm2 window**,
creating that window the first time. Every later session for the same project (matched by
**git repo root**) lands as another tab in the same window. Non-destructive: it only ever
*creates* tabs/windows — it never closes or moves a live session.

```bash
claude-proj                 # group by the git root of the current directory
claude-proj ~/Projects/foo  # open a foo session in foo's window
claude-proj --list          # show the project → window registry
claude-proj --forget foo    # drop a stale registry entry
```
- Registry: `~/.claude/iterm-proj-windows.tsv` (`<project>\t<iterm-window-id>`).
- Self-healing: if a project's window was closed, the next `claude-proj` makes a fresh one.
- Override the launched command for testing: `CLAUDE_PROJ_CMD='echo hi' claude-proj ~/x`.

Put it on PATH (a symlink into `~/bin` is created by `install.sh`), then use `claude-proj`
instead of bare `claude` to keep every project's sessions grouped from the start.

### `iterm-map.sh` — accurate current grouping (read-only)
Prints which live windows belong to which project, reading each session's real shell
`path` (iTerm2 shell-integration variable — reliable, unlike the OS process cwd).
Use it as a manual-drag guide for the sessions you already have open.
```bash
./iterm-map.sh
```
Caveat: `W#` are **positional** window indices and shift as sessions come/go; use them as
an at-a-glance grouping, not stable ids.

### `iterm-regroup.py` — Option C (API), with an honest limit
Reads the authoritative grouping via the iTerm2 Python API (`--plan`). **iTerm2 exposes no
supported way to move an existing tab between windows** (AppleScript *or* Python API), so a
non-destructive *retroactive* regroup of already-open sessions is not possible — `--apply`
says so rather than killing sessions to force it. Enable the API only if you want `--plan`;
it needs an iTerm2 restart (which ends current sessions), so it isn't worth it just to
regroup — use `claude-proj` going forward instead.

## Recommendation
- **Going forward:** launch project work with `claude-proj` → automatic per-project windows.
- **Right now:** run `./iterm-map.sh` and drag same-project tabs together (manual, safe).
- Don't restart iTerm2 to enable the API purely to regroup — the move isn't supported.