hades-cli 0.1.0__tar.gz → 0.1.2__tar.gz

hades_cli-0.1.2/.github/workflows/pylint.yml

@@ -0,0 +1,20 @@
+name: Pylint
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Install uv
+      uses: astral-sh/setup-uv@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      run: uv python install ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: uv sync --python ${{ matrix.python-version }} --group dev
+    - name: Analysing the code with pylint
+      run: uv run --python ${{ matrix.python-version }} pylint $(git ls-files '*.py')

hades_cli-0.1.2/.github/workflows/python-publish.yml

@@ -0,0 +1,73 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          # NOTE: put your own distribution build steps here.
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    # Dedicated environments with protections for publishing are strongly recommended.
+    # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
+    environment:
+      name: pypi
+      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
+      # url: https://pypi.org/p/YOURPROJECT
+      #
+      # ALTERNATIVE: if your GitHub Release name is the PyPI project version string
+      # ALTERNATIVE: exactly, uncomment the following line instead:
+      # url: https://pypi.org/project/YOURPROJECT/${{ github.event.release.name }}
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

{hades_cli-0.1.0 → hades_cli-0.1.2}/.gitignore

@@ -7,3 +7,6 @@ build/
 .env
 *.db
 .DS_Store
+src/hades/_version.py
+.claude/
+.vscode/

hades_cli-0.1.2/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: hades-cli
+Version: 0.1.2
+Summary: A local CLI for viewing, searching, and managing AI coding sessions across Claude Code, Codex, Gemini, and Cowork.
+Project-URL: Homepage, https://github.com/mnghn07/hades
+Project-URL: Repository, https://github.com/mnghn07/hades
+Author-email: mnghn07 <ngh.nhatminh0712@gmail.com>
+Requires-Python: >=3.11
+Requires-Dist: ijson>=3
+Requires-Dist: pendulum>=3
+Requires-Dist: platformdirs>=4
+Requires-Dist: psutil>=6
+Requires-Dist: rich>=13
+Requires-Dist: sqlite-utils>=3
+Requires-Dist: typer>=0.15
+Description-Content-Type: text/markdown
+
+# hades
+
+> *The dead or the living will be seen by Hades. No AI session escapes.*
+
+A CLI for viewing, searching, and managing your AI coding sessions across Claude Code, Codex CLI, Gemini CLI, and Cowork — all from one terminal.
+
+[![PyPI](https://img.shields.io/pypi/v/hades-cli)](https://pypi.org/project/hades-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/hades-cli)](https://pypi.org/project/hades-cli/)
+
+## Why
+
+Each AI tool keeps its own session store, so there's no single view across them — and it's easy to miss a session that's been waiting on you. `hades` gives you one place to see what's running, what's waiting, and what happened.
+
+## Install
+
+```bash
+pipx install hades-cli       # recommended
+uv tool install hades-cli    # or with uv
+pip install hades-cli        # or plain pip
+```
+
+## Usage
+
+```bash
+hades list                                    # sessions from the last 3 days (default)
+hades list --tool claude --active             # filter by tool or status
+hades list --day 1 --hour 12                  # sessions active within the last 1d 12h
+hades list --all                              # every session ever indexed
+hades show <session-id>                       # pretty-print a transcript
+hades show <session-id> --full                # expand tool calls too
+hades attention                               # what's been waiting on you
+hades stats                                   # summary + per-tool breakdown
+hades stats --day 1                           # scoped to the last 24h
+hades search "some query"                     # full-text search across transcripts
+hades search "some query" --tool claude -n 5  # filter by tool, cap results
+hades export <session-id>                     # dump transcript as JSON
+hades export <session-id> --format markdown -o out.md
+hades archive <session-id>                    # move transcript to the archive, hide it from list/search
+hades purge <session-id>                      # permanently delete a transcript (asks to confirm)
+hades watch                                   # live view + macOS notifications
+hades watch --no-notify                       # live view only
+```
+
+## How it works
+
+On every command, `hades` scans your local session files, indexes them into a SQLite database, and checks running processes to show live status. Only changed files are re-parsed, so runs stay fast. Everything stays on your machine — nothing is sent anywhere.
+
+## Commands
+
+**`hades list`** shows all sessions across tools, sorted by most recently active. Background sessions spawned by other tooling (observers, hooks, ...) are grouped into a single summary row per tool, instead of flooding the table:
+
+```
+TOOL      PROJECT              TYPE      LAST ACTIVE    MSGS  STATUS
+claude    hades                human     2m ago          47   ● running
+claude    claude-mem           agent     2m ago         512   ● running
+claude    dotfiles             human     3h ago          12   ○ idle
+gemini    api-server           human     1d ago           8   ○ idle
+codex     ml-pipeline          human     3d ago          31   ✕ ended
+```
+
+**`hades show`** pretty-prints a single transcript, tool calls collapsed by default (`--full` to expand).
+
+**`hades attention`** lists sessions that have been waiting on you for 3+ minutes, longest wait first.
+
+**`hades stats`** summarizes total sessions/messages, a per-tool breakdown, and how many sessions are currently waiting on you.
+
+**`hades search`** does a full-text search across every transcript's human and assistant messages, with a highlighted snippet for each match.
+
+**`hades export`** dumps a session's transcript to a JSON or Markdown file, for sharing or archiving outside `hades`.
+
+**`hades archive`** relocates a session's raw file into `hades`'s own archive directory and hides it from `list`/`search` by default (pass `--show-archived` to see it again). The file isn't deleted — `hades purge` is the destructive one.
+
+**`hades purge`** permanently deletes a session's transcript file and its index entry. Prompts for confirmation unless you pass `--yes`.
+
+**`hades watch`** keeps a live view open and fires a macOS notification when a session starts waiting.
+
+## Sources
+
+| Tool | Default path | Format |
+|---|---|---|
+| Claude Code | `~/.claude/projects/` | JSONL |
+| Codex CLI | `~/.codex/sessions/` | JSONL |
+| Gemini CLI | `~/.gemini/tmp/` | JSON |
+| Cowork | `~/Library/Application Support/Claude/local-agent-mode-sessions/` | JSON |
+
+Paths are auto-discovered — no config needed. Override any with env vars:
+
+```bash
+HADES_CLAUDE_PATH=~/custom/path hades list
+```
+
+## Development
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/mnghn07/hades.git
+cd hades
+uv sync --group dev     # install project + dev dependencies into .venv
+```
+
+```bash
+uv run hades list       # run the CLI from source
+uv run pytest           # run the test suite
+uv run pylint $(git ls-files '*.py')   # lint
+uv build                 # build sdist + wheel into dist/
+```
+
+Versioning is derived from git tags (via `hatch-vcs`) — there's nothing to bump by hand. Pushing a tag like `v0.1.1` builds and publishes that version to PyPI automatically:
+
+```bash
+git tag v0.1.1
+git push origin v0.1.1
+```
+
+## License
+
+MIT

hades_cli-0.1.2/README.md

@@ -0,0 +1,118 @@
+# hades
+
+> *The dead or the living will be seen by Hades. No AI session escapes.*
+
+A CLI for viewing, searching, and managing your AI coding sessions across Claude Code, Codex CLI, Gemini CLI, and Cowork — all from one terminal.
+
+[![PyPI](https://img.shields.io/pypi/v/hades-cli)](https://pypi.org/project/hades-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/hades-cli)](https://pypi.org/project/hades-cli/)
+
+## Why
+
+Each AI tool keeps its own session store, so there's no single view across them — and it's easy to miss a session that's been waiting on you. `hades` gives you one place to see what's running, what's waiting, and what happened.
+
+## Install
+
+```bash
+pipx install hades-cli       # recommended
+uv tool install hades-cli    # or with uv
+pip install hades-cli        # or plain pip
+```
+
+## Usage
+
+```bash
+hades list                                    # sessions from the last 3 days (default)
+hades list --tool claude --active             # filter by tool or status
+hades list --day 1 --hour 12                  # sessions active within the last 1d 12h
+hades list --all                              # every session ever indexed
+hades show <session-id>                       # pretty-print a transcript
+hades show <session-id> --full                # expand tool calls too
+hades attention                               # what's been waiting on you
+hades stats                                   # summary + per-tool breakdown
+hades stats --day 1                           # scoped to the last 24h
+hades search "some query"                     # full-text search across transcripts
+hades search "some query" --tool claude -n 5  # filter by tool, cap results
+hades export <session-id>                     # dump transcript as JSON
+hades export <session-id> --format markdown -o out.md
+hades archive <session-id>                    # move transcript to the archive, hide it from list/search
+hades purge <session-id>                      # permanently delete a transcript (asks to confirm)
+hades watch                                   # live view + macOS notifications
+hades watch --no-notify                       # live view only
+```
+
+## How it works
+
+On every command, `hades` scans your local session files, indexes them into a SQLite database, and checks running processes to show live status. Only changed files are re-parsed, so runs stay fast. Everything stays on your machine — nothing is sent anywhere.
+
+## Commands
+
+**`hades list`** shows all sessions across tools, sorted by most recently active. Background sessions spawned by other tooling (observers, hooks, ...) are grouped into a single summary row per tool, instead of flooding the table:
+
+```
+TOOL      PROJECT              TYPE      LAST ACTIVE    MSGS  STATUS
+claude    hades                human     2m ago          47   ● running
+claude    claude-mem           agent     2m ago         512   ● running
+claude    dotfiles             human     3h ago          12   ○ idle
+gemini    api-server           human     1d ago           8   ○ idle
+codex     ml-pipeline          human     3d ago          31   ✕ ended
+```
+
+**`hades show`** pretty-prints a single transcript, tool calls collapsed by default (`--full` to expand).
+
+**`hades attention`** lists sessions that have been waiting on you for 3+ minutes, longest wait first.
+
+**`hades stats`** summarizes total sessions/messages, a per-tool breakdown, and how many sessions are currently waiting on you.
+
+**`hades search`** does a full-text search across every transcript's human and assistant messages, with a highlighted snippet for each match.
+
+**`hades export`** dumps a session's transcript to a JSON or Markdown file, for sharing or archiving outside `hades`.
+
+**`hades archive`** relocates a session's raw file into `hades`'s own archive directory and hides it from `list`/`search` by default (pass `--show-archived` to see it again). The file isn't deleted — `hades purge` is the destructive one.
+
+**`hades purge`** permanently deletes a session's transcript file and its index entry. Prompts for confirmation unless you pass `--yes`.
+
+**`hades watch`** keeps a live view open and fires a macOS notification when a session starts waiting.
+
+## Sources
+
+| Tool | Default path | Format |
+|---|---|---|
+| Claude Code | `~/.claude/projects/` | JSONL |
+| Codex CLI | `~/.codex/sessions/` | JSONL |
+| Gemini CLI | `~/.gemini/tmp/` | JSON |
+| Cowork | `~/Library/Application Support/Claude/local-agent-mode-sessions/` | JSON |
+
+Paths are auto-discovered — no config needed. Override any with env vars:
+
+```bash
+HADES_CLAUDE_PATH=~/custom/path hades list
+```
+
+## Development
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/mnghn07/hades.git
+cd hades
+uv sync --group dev     # install project + dev dependencies into .venv
+```
+
+```bash
+uv run hades list       # run the CLI from source
+uv run pytest           # run the test suite
+uv run pylint $(git ls-files '*.py')   # lint
+uv build                 # build sdist + wheel into dist/
+```
+
+Versioning is derived from git tags (via `hatch-vcs`) — there's nothing to bump by hand. Pushing a tag like `v0.1.1` builds and publishes that version to PyPI automatically:
+
+```bash
+git tag v0.1.1
+git push origin v0.1.1
+```
+
+## License
+
+MIT

hades_cli-0.1.2/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported Versions
+
+Use this section to tell people about which versions of your project are
+currently being supported with security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 5.1.x   | :white_check_mark: |
+| 5.0.x   | :x:                |
+| 4.0.x   | :white_check_mark: |
+| < 4.0   | :x:                |
+
+## Reporting a Vulnerability
+
+Use this section to tell people how to report a vulnerability.
+
+Tell them where to go, how often they can expect to get an update on a
+reported vulnerability, what to expect if the vulnerability is accepted or
+declined, etc.

hades_cli-0.1.2/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "hades-cli"
+dynamic = ["version"]
+description = "A local CLI for viewing, searching, and managing AI coding sessions across Claude Code, Codex, Gemini, and Cowork."
+readme = "README.md"
+authors = [{ name = "mnghn07", email = "ngh.nhatminh0712@gmail.com" }]
+requires-python = ">=3.11"
+dependencies = [
+    "typer>=0.15",
+    "rich>=13",
+    "ijson>=3",
+    "psutil>=6",
+    "platformdirs>=4",
+    "pendulum>=3",
+    "sqlite-utils>=3",
+]
+
+[project.urls]
+Homepage = "https://github.com/mnghn07/hades"
+Repository = "https://github.com/mnghn07/hades"
+
+[project.scripts]
+hades = "hades.cli:app"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/hades/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hades"]
+
+[dependency-groups]
+dev = [
+    "pylint>=4.0.6",
+    "pytest>=8",
+    "pytest-mock>=3",
+    "typer>=0.15",
+]
+
+[tool.pylint.main]
+disable = [
+    "missing-module-docstring",
+    "missing-function-docstring",
+    "missing-class-docstring",
+    "import-outside-toplevel",
+    "duplicate-code",
+    "broad-exception-caught",
+    "too-many-locals",
+    "too-many-instance-attributes",
+    "too-many-arguments",
+    "too-many-positional-arguments",
+    "redefined-outer-name",
+]
+
+[tool.pylint.format]
+max-line-length = 120

hades_cli-0.1.2/src/hades/__init__.py

@@ -0,0 +1 @@
+from hades._version import __version__

hades_cli-0.1.2/src/hades/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.2'
+__version_tuple__ = version_tuple = (0, 1, 2)
+
+__commit_id__ = commit_id = None

hades_cli-0.1.2/src/hades/classify.py

@@ -0,0 +1,15 @@
+AGENT_PATH_MARKERS: dict[str, str] = {
+    ".claude-mem": "claude-mem",
+}
+
+
+def classify_project(project_path: str) -> tuple[str, str]:
+    """Return (display_name, session_type) for a session's project path.
+
+    session_type is "agent" for known background tooling (observers, hooks, ...),
+    "human" for regular interactive project sessions.
+    """
+    for marker, label in AGENT_PATH_MARKERS.items():
+        if marker in project_path:
+            return label, "agent"
+    return project_path.split("/")[-1] or project_path, "human"

hades_cli-0.1.2/src/hades/cli.py

@@ -0,0 +1,124 @@
+from typing import Optional
+import typer
+from hades import __version__
+
+app = typer.Typer(
+    name="hades",
+    help="View, search, and manage AI coding sessions across Claude, Codex, Gemini, and Cowork.",
+    no_args_is_help=True,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"hades {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    _version: Optional[bool] = typer.Option(
+        None, "--version", "-v", callback=_version_callback, is_eager=True, help="Show version and exit"
+    ),
+):
+    from hades.db import get_db
+    from hades.indexer import refresh_index
+    from hades.process_checker import update_statuses
+    db = get_db()
+    refresh_index(db)
+    update_statuses(db)
+
+
+@app.command("list", help="List sessions across all tools.")
+def list_cmd(
+    tool: Optional[str] = typer.Option(None, "--tool", "-t", help="Filter by tool: claude, codex, gemini, cowork"),
+    active: bool = typer.Option(False, "--active", help="Show only running/idle sessions"),
+    day: int = typer.Option(0, "--day", help="Show sessions active within the last N days"),
+    hour: int = typer.Option(0, "--hour", help="Show sessions active within the last N hours"),
+    minute: int = typer.Option(0, "--min", help="Show sessions active within the last N minutes"),
+    show_all: bool = typer.Option(False, "--all", help="Show every session, ignoring recency"),
+    show_archived: bool = typer.Option(False, "--show-archived", help="Include archived sessions"),
+):
+    from hades.commands.list import cmd_list
+    cmd_list(
+        tool=tool, active=active, day=day, hour=hour, minute=minute,
+        show_all=show_all, show_archived=show_archived,
+    )
+
+
+@app.command("show", help="Pretty-print a session transcript.")
+def show_cmd(
+    session_id: str = typer.Argument(..., help="Session ID (from hades list)"),
+    full: bool = typer.Option(False, "--full", help="Expand tool calls"),
+):
+    from hades.commands.show import cmd_show
+    cmd_show(session_id=session_id, full=full)
+
+
+@app.command("attention", help="Surface sessions waiting on you.")
+def attention_cmd():
+    from hades.commands.attention import cmd_attention
+    cmd_attention()
+
+
+@app.command("stats", help="Summary stats across all sessions.")
+def stats_cmd(
+    day: int = typer.Option(0, "--day", help="Only include sessions active within the last N days"),
+    hour: int = typer.Option(0, "--hour", help="Only include sessions active within the last N hours"),
+    minute: int = typer.Option(0, "--min", help="Only include sessions active within the last N minutes"),
+):
+    from hades.commands.stats import cmd_stats
+    cmd_stats(day=day, hour=hour, minute=minute)
+
+
+@app.command("search", help="Full-text search across session transcripts.")
+def search_cmd(
+    query: str = typer.Argument(..., help="Full-text search query"),
+    tool: Optional[str] = typer.Option(None, "--tool", "-t", help="Filter by tool: claude, codex, gemini, cowork"),
+    limit: int = typer.Option(20, "--limit", "-n", help="Max results to show"),
+    show_archived: bool = typer.Option(False, "--show-archived", help="Include archived sessions"),
+):
+    from hades.commands.search import cmd_search
+    cmd_search(query=query, tool=tool, limit=limit, show_archived=show_archived)
+
+
+@app.command("export", help="Export a session transcript to json or markdown.")
+def export_cmd(
+    session_id: str = typer.Argument(..., help="Session ID (from hades list)"),
+    export_format: str = typer.Option("json", "--format", "-f", help="Output format: json or markdown"),
+    output: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
+    full: bool = typer.Option(False, "--full", help="Include tool calls and thinking blocks"),
+):
+    from pathlib import Path
+    from hades.commands.export import cmd_export
+    cmd_export(
+        session_id=session_id, export_format=export_format,
+        output=Path(output) if output else None, full=full,
+    )
+
+
+@app.command("archive", help="Move a session's transcript to the archive and hide it from list/search.")
+def archive_cmd(
+    session_id: str = typer.Argument(..., help="Session ID (from hades list)"),
+):
+    from hades.commands.archive import cmd_archive
+    cmd_archive(session_id=session_id)
+
+
+@app.command("purge", help="Permanently delete a session's transcript and index entry.")
+def purge_cmd(
+    session_id: str = typer.Argument(..., help="Session ID (from hades list)"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+):
+    from hades.commands.purge import cmd_purge
+    cmd_purge(session_id=session_id, yes=yes)
+
+
+@app.command("watch", help="Live view of sessions needing attention (fires macOS notifications by default).")
+def watch_cmd(
+    notify: bool = typer.Option(
+        True, "--notify/--no-notify", help="Fire macOS notifications for newly-waiting sessions"
+    ),
+):
+    from hades.commands.watch import cmd_watch
+    cmd_watch(notify=notify)

hades_cli-0.1.2/src/hades/commands/archive.py

@@ -0,0 +1,64 @@
+import shutil
+from pathlib import Path
+
+import typer
+from platformdirs import user_data_dir
+from rich.console import Console
+
+from hades.db import get_db
+
+console = Console()
+
+ARCHIVE_ROOT = Path(user_data_dir("hades")) / "archive"
+
+
+def cmd_archive(
+    session_id: str = typer.Argument(..., help="Session ID (from hades list)"),
+):
+    db = get_db()
+    row = db.execute(
+        "SELECT tool, raw_path, is_archived FROM sessions WHERE id = ?", [session_id]
+    ).fetchone()
+    if not row:
+        console.print(f"[red]Session not found:[/red] {session_id}")
+        raise typer.Exit(1)
+
+    tool, raw_path_str, is_archived = row
+    if is_archived:
+        console.print(f"[yellow]Already archived:[/yellow] {session_id}")
+        return
+
+    raw_path = Path(raw_path_str)
+    if not raw_path.exists():
+        console.print(f"[red]Session file no longer exists:[/red] {raw_path}")
+        raise typer.Exit(1)
+
+    dest_dir = ARCHIVE_ROOT / tool
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest_path = _unique_dest(dest_dir, raw_path.name)
+
+    shutil.move(str(raw_path), str(dest_path))
+
+    db.execute(
+        "UPDATE sessions SET raw_path = ?, is_archived = 1 WHERE id = ?",
+        [str(dest_path), session_id],
+    )
+    db.conn.commit()
+
+    console.print(f"[green]Archived[/green] {session_id} → {dest_path}")
+
+
+def _unique_dest(dest_dir: Path, name: str) -> Path:
+    """Never overwrite an existing archived file — suffix a counter instead.
+
+    Same-named session files from different projects (e.g. Gemini's
+    chats/session-1.json) would otherwise clobber each other.
+    """
+    dest = dest_dir / name
+    if not dest.exists():
+        return dest
+    stem, suffix = dest.stem, dest.suffix
+    counter = 1
+    while (dest := dest_dir / f"{stem}.{counter}{suffix}").exists():
+        counter += 1
+    return dest