claudenator 1.0.0__tar.gz

claudenator-1.0.0/.gitignore

@@ -0,0 +1,12 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/

claudenator-1.0.0/LICENSE.md

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Marcin Orlowski <https://marcinOrlowski.com/>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
+OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

claudenator-1.0.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.5
+Name: claudenator
+Version: 1.0.0
+Summary: The only Claude Code session manager you needca
+Project-URL: Homepage, https://github.com/MarcinOrlowski/claudenator
+Project-URL: Issues, https://github.com/MarcinOrlowski/claudenator/issues
+Author-email: Marcin Orlowski <mail@marcinOrlowski.com>
+License-Expression: MIT
+License-File: LICENSE.md
+Keywords: claude,claude-code,claude-sessions,cli,session-management,sessions,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: qrcat<2,>=1
+Requires-Dist: textual<9,>=8
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: flake8; extra == 'dev'
+Requires-Dist: flake8-docstrings; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == 'release'
+Requires-Dist: twine>=6; extra == 'release'
+Description-Content-Type: text/markdown
+
+![Claudenator](https://raw.githubusercontent.com/MarcinOrlowski/claudenator/master/img/logo.webp)
+
+[![Version](https://img.shields.io/pypi/v/claudenator?style=flat)](https://pypi.org/project/claudenator/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)
+
+## The only Claude Code session manager you need
+
+Claude Code writes a lot. Every session leaves a transcript from the main session and its subagents.
+Then goes the environment, file history, jobs and todos. That's tons of disk. Additionally,
+it auto-purges all the sessions older than 30 days, but if you decide to prevent that and keep some
+old sessions for longer, it can stack up a massive pile pretty quickly.
+
+This is where Claudenator comes to the rescue. It shows all your sessions, grouped by project
+folder, sorts them by whatever column you like and shows tons of additional information that
+would help you manage them and purge only real garbage.
+
+![Claudenator in action](https://raw.githubusercontent.com/MarcinOrlowski/claudenator/master/img/claudenator.webp)
+
+## Features
+
+* Shows every session, its title, project, size, date, messages, model, git branch, tools and moar.
+* A details pane under the table, and a full-screen view for the whole story.
+* Order the table by any column and narrow it to what you look for with a filter.
+* A deleted session first goes to a Trash so it disappears but is not yet gone and can be either
+  restored or purged for good.
+* Comes with "Deep scan" feature, that process the full transcript to give you more stats for nerds.
+* Configurable TUI with themes, layout, time formats and more.
+
+## Installation
+
+The [pipx](https://pypi.org/project/pipx/) is the recommended way to install it:
+
+```bash
+# Install pipx if not present
+sudo apt install -y pipx
+
+# Install the tool
+pipx install claudenator
+
+# Upgrade existing installation
+pipx upgrade claudenator
+```
+
+To get the latest code, install straight from the repository:
+
+```bash
+# Install the current "master" branch
+pipx install --force git+https://github.com/MarcinOrlowski/claudenator.git
+
+# Install the "dev" branch or any other branch, tag or commit
+pipx install --force git+https://github.com/MarcinOrlowski/claudenator.git@dev
+```
+
+The `--force` option is only needed if there's already existing Claudenator installation present.
+
+## License
+
+* Written and copyrighted &copy;2026 by Marcin Orlowski <mail (#) marcinorlowski (.) com>
+* This is open-source software licensed under the [MIT license](http://opensource.org/licenses/MIT)

claudenator-1.0.0/README.md

@@ -0,0 +1,60 @@
+![Claudenator](https://raw.githubusercontent.com/MarcinOrlowski/claudenator/master/img/logo.webp)
+
+[![Version](https://img.shields.io/pypi/v/claudenator?style=flat)](https://pypi.org/project/claudenator/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)
+
+## The only Claude Code session manager you need
+
+Claude Code writes a lot. Every session leaves a transcript from the main session and its subagents.
+Then goes the environment, file history, jobs and todos. That's tons of disk. Additionally,
+it auto-purges all the sessions older than 30 days, but if you decide to prevent that and keep some
+old sessions for longer, it can stack up a massive pile pretty quickly.
+
+This is where Claudenator comes to the rescue. It shows all your sessions, grouped by project
+folder, sorts them by whatever column you like and shows tons of additional information that
+would help you manage them and purge only real garbage.
+
+![Claudenator in action](https://raw.githubusercontent.com/MarcinOrlowski/claudenator/master/img/claudenator.webp)
+
+## Features
+
+* Shows every session, its title, project, size, date, messages, model, git branch, tools and moar.
+* A details pane under the table, and a full-screen view for the whole story.
+* Order the table by any column and narrow it to what you look for with a filter.
+* A deleted session first goes to a Trash so it disappears but is not yet gone and can be either
+  restored or purged for good.
+* Comes with "Deep scan" feature, that process the full transcript to give you more stats for nerds.
+* Configurable TUI with themes, layout, time formats and more.
+
+## Installation
+
+The [pipx](https://pypi.org/project/pipx/) is the recommended way to install it:
+
+```bash
+# Install pipx if not present
+sudo apt install -y pipx
+
+# Install the tool
+pipx install claudenator
+
+# Upgrade existing installation
+pipx upgrade claudenator
+```
+
+To get the latest code, install straight from the repository:
+
+```bash
+# Install the current "master" branch
+pipx install --force git+https://github.com/MarcinOrlowski/claudenator.git
+
+# Install the "dev" branch or any other branch, tag or commit
+pipx install --force git+https://github.com/MarcinOrlowski/claudenator.git@dev
+```
+
+The `--force` option is only needed if there's already existing Claudenator installation present.
+
+## License
+
+* Written and copyrighted &copy;2026 by Marcin Orlowski <mail (#) marcinorlowski (.) com>
+* This is open-source software licensed under the [MIT license](http://opensource.org/licenses/MIT)

claudenator-1.0.0/claudenator/__init__.py

@@ -0,0 +1,18 @@
+"""
+##################################################################################
+#
+# Claudenator by Marcin Orlowski
+# The only Claude Code session manager you need.
+#
+# @author    Marcin Orlowski <mail@marcinOrlowski.com>
+# Copyright  ©2026 Marcin Orlowski <MarcinOrlowski.com>
+# @link      https://github.com/MarcinOrlowski/claudenator
+#
+##################################################################################
+"""
+
+__title__ = "claudenator"
+__version__ = "1.0.0"
+__description__ = "The only Claude Code session manager you need"
+__author__ = "Marcin Orlowski"
+__url__ = "https://github.com/MarcinOrlowski/claudenator"

claudenator-1.0.0/claudenator/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for ``python -m claudenator``."""
+
+from claudenator.cli.main import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

claudenator-1.0.0/claudenator/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI"""

claudenator-1.0.0/claudenator/cli/main.py

@@ -0,0 +1,205 @@
+"""
+##################################################################################
+#
+# Claudenator by Marcin Orlowski
+# The only Claude Code session manager you need.
+#
+# @author    Marcin Orlowski <mail@marcinOrlowski.com>
+# Copyright  ©2026 Marcin Orlowski <MarcinOrlowski.com>
+# @link      https://github.com/MarcinOrlowski/claudenator
+#
+##################################################################################
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from claudenator import __version__
+from claudenator.core.config import apply_file
+from claudenator.core.errors import ClaudenatorError
+from claudenator.core.format import Formatter, plural_of
+from claudenator.core.model import Session
+from claudenator.core.settings import Settings
+from claudenator.core.store import SessionStore
+
+TITLE_WIDTH = 48
+
+
+def short_title(session: Session) -> str:
+    """The title in truncated form."""
+    text = session.title
+    if len(text) > TITLE_WIDTH:
+        text = text[: TITLE_WIDTH - 3].rstrip() + "…"
+    return text
+
+
+def open_screen(settings: Settings, notes: list[str]) -> int:
+    """Run the TUI."""
+    from claudenator.tui.app import run
+
+    return run(settings, notes)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """The argument parser for the ``claudenator`` command."""
+    defaults = Settings()
+    parser = argparse.ArgumentParser(
+        prog="claudenator",
+        description="Look at Claude Code sessions and remove the ones you do not want.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    parser.add_argument(
+        "--claude-dir",
+        type=Path,
+        metavar="DIR",
+        help=f"Claude Code's data folder (default: {defaults.claude_dir})",
+    )
+    parser.add_argument(
+        "--data-dir",
+        type=Path,
+        metavar="DIR",
+        help=f"claudenator's own folder for the Trash and the cache (default: {defaults.data_dir})",
+    )
+    # The process table. Only a test points this anywhere but /proc.
+    parser.add_argument("--proc-dir", type=Path, metavar="DIR", help=argparse.SUPPRESS)
+    commands = parser.add_subparsers(dest="command", metavar="COMMAND")
+
+    list_parser = commands.add_parser("list", help="list every session")
+    list_parser.add_argument("--json", action="store_true", help="print JSON")
+
+    info_parser = commands.add_parser("info", help="show one session in full")
+    info_parser.add_argument(
+        "session_id", metavar="ID", help="a session id, or a unique prefix of one"
+    )
+    info_parser.add_argument("--json", action="store_true", help="print JSON")
+
+    scan_parser = commands.add_parser(
+        "scan", help="read every transcript in full and cache its figures"
+    )
+    scan_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="read a transcript again even when its cached figures are fresh",
+    )
+    return parser
+
+
+def settings_from(args: argparse.Namespace) -> tuple[Settings, list[str]]:
+    """A settings object, and a note for every fault in the settings file."""
+    settings = Settings()
+    notes = apply_file(settings)
+    if args.claude_dir is not None:
+        settings.claude_dir = args.claude_dir.expanduser()
+    if args.data_dir is not None:
+        settings.data_dir = args.data_dir.expanduser()
+    if args.proc_dir is not None:
+        settings.proc_dir = args.proc_dir.expanduser()
+    return settings, notes
+
+
+def cmd_list(store: SessionStore, args: argparse.Namespace, fmt: Formatter) -> int:
+    """Print every session, one per line."""
+    sessions = store.list_sessions()
+    if args.json:
+        print(json.dumps([session.to_dict() for session in sessions], indent=2))
+        return 0
+    if not sessions:
+        print(f"No sessions found under {store.settings.claude_dir}")
+        return 0
+    rows = [
+        (
+            session.id[:8],
+            fmt.marks(session),
+            fmt.list_timestamp(session.last_used),
+            fmt.size(session.size),
+            short_title(session),
+            session.project_path,
+        )
+        for session in sessions
+    ]
+    header = ("ID", "STS", "LAST USED", "SIZE", "TITLE", "PROJECT")
+    widths = [max(len(row[i]) for row in (header, *rows)) for i in range(5)]
+    for row in (header, *rows):
+        cells = [row[i].ljust(widths[i]) for i in range(5)]
+        print("  ".join(cells + [row[5]]).rstrip())
+    total = sum(session.size for session in sessions)
+    noun = "session" if len(sessions) == 1 else "sessions"
+    print()
+    print(f"{len(sessions)} {noun}, {fmt.size(total)} on disk")
+    return 0
+
+
+def cmd_info(store: SessionStore, args: argparse.Namespace, fmt: Formatter) -> int:
+    """Print one session in full."""
+    details = store.details(args.session_id)
+    if args.json:
+        print(json.dumps(details.to_dict(), indent=2))
+        return 0
+    lines = fmt.describe(details)
+    width = max(len(label) for label, _ in lines) + 1
+    for label, value in lines:
+        print(f"{(label + ':').ljust(width)} {value}")
+    return 0
+
+
+def cmd_scan(store: SessionStore, args: argparse.Namespace, fmt: Formatter) -> int:
+    """Deep-scan every session and cache the figures. One line per session."""
+    sessions = store.list_sessions()
+    if not sessions:
+        print(f"No sessions found under {store.settings.claude_dir}")
+        return 0
+    read = kept = failed = 0
+    for result in store.scan_many(sessions, force=args.force):
+        short = result.session.id[:8]
+        if result.error is not None or result.figures is None:
+            failed += 1
+            print(f"{short}  {result.error}", file=sys.stderr)
+            continue
+        figures = result.figures
+        if result.fresh:
+            kept += 1
+        else:
+            read += 1
+        turns = f"{fmt.count(figures.turns)} {plural_of('turn', figures.turns)}"
+        tokens = f"{fmt.count(figures.tokens)} {plural_of('token', figures.tokens)}"
+        length = fmt.duration(figures.duration)
+        state = "cached" if result.fresh else "scanned"
+        print(f"{short}  {turns}  {tokens}  {length}  {state}")
+    dropped = store.cache.forget_missing()
+    print()
+    print(
+        f"{fmt.scan_summary(read, kept, failed)}, "
+        f"{dropped} gone from the disk and forgotten"
+    )
+    print(f"Cache: {store.settings.cache_file}")
+    return 1 if failed else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the command line. Returns the exit code."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    settings, notes = settings_from(args)
+    if args.command is None:
+        return open_screen(settings, notes)
+    for note in notes:
+        print(f"claudenator: {note}", file=sys.stderr)
+    store = SessionStore(settings)
+    fmt = Formatter(settings)
+    try:
+        if args.command == "list":
+            return cmd_list(store, args, fmt)
+        if args.command == "info":
+            return cmd_info(store, args, fmt)
+        if args.command == "scan":
+            return cmd_scan(store, args, fmt)
+    except ClaudenatorError as error:
+        print(f"claudenator: {error}", file=sys.stderr)
+        return 1
+    parser.error(f"unknown command {args.command}")

claudenator-1.0.0/claudenator/core/__init__.py

@@ -0,0 +1 @@
+"""Core: CC session data handling"""

claudenator-1.0.0/claudenator/core/cache.py

@@ -0,0 +1,198 @@
+"""
+##################################################################################
+#
+# Claudenator by Marcin Orlowski
+# The only Claude Code session manager you need.
+#
+# @author    Marcin Orlowski <mail@marcinOrlowski.com>
+# Copyright  ©2026 Marcin Orlowski <MarcinOrlowski.com>
+# @link      https://github.com/MarcinOrlowski/claudenator
+#
+##################################################################################
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from claudenator.core.errors import CacheDamaged
+from claudenator.core.model import Figures
+from claudenator.core.settings import Settings
+
+# One row per transcript, found by its path. The size and change time say
+# which copy of the file the row describes. The row holds our own numbers
+# and nothing the user wrote. A time is stored whole, so what comes back
+# is what went in.
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS figures (
+    path TEXT PRIMARY KEY,
+    size INTEGER NOT NULL,
+    mtime_ns INTEGER NOT NULL,
+    scanned_at TEXT NOT NULL,
+    turns INTEGER NOT NULL,
+    input_tokens INTEGER NOT NULL,
+    output_tokens INTEGER NOT NULL,
+    cache_read_tokens INTEGER NOT NULL,
+    cache_write_tokens INTEGER NOT NULL,
+    models TEXT NOT NULL,
+    tools TEXT NOT NULL,
+    first_at TEXT,
+    last_at TEXT
+)
+"""
+COLUMNS = (
+    "path",
+    "size",
+    "mtime_ns",
+    "scanned_at",
+    "turns",
+    "input_tokens",
+    "output_tokens",
+    "cache_read_tokens",
+    "cache_write_tokens",
+    "models",
+    "tools",
+    "first_at",
+    "last_at",
+)
+# How long a write waits for another copy of the tool to finish its own.
+LOCK_WAIT_SECONDS = 5.0
+
+
+def _moment(value: Any) -> datetime | None:
+    return datetime.fromisoformat(value) if isinstance(value, str) else None
+
+
+def _pairs(value: Any) -> tuple[tuple[str, int], ...]:
+    """The name and count pairs stored as one JSON list, in their stored order."""
+    return tuple((str(name), int(count)) for name, count in json.loads(value))
+
+
+def _row_of(figures: Figures) -> tuple[Any, ...]:
+    return (
+        str(figures.transcript_path),
+        figures.transcript_size,
+        figures.transcript_mtime_ns,
+        figures.scanned_at.isoformat(),
+        figures.turns,
+        figures.input_tokens,
+        figures.output_tokens,
+        figures.cache_read_tokens,
+        figures.cache_write_tokens,
+        json.dumps(figures.models),
+        json.dumps(figures.tools),
+        figures.first_at.isoformat() if figures.first_at else None,
+        figures.last_at.isoformat() if figures.last_at else None,
+    )
+
+
+def _is_stale(transcript: Path, row: tuple[Any, ...]) -> bool:
+    """True when the file's size or change time differ from the row's, or it is gone."""
+    try:
+        stat = transcript.stat()
+    except OSError:
+        return True
+    return stat.st_size != row[1] or stat.st_mtime_ns != row[2]
+
+
+def _figures_of(row: tuple[Any, ...], stale: bool) -> Figures:
+    return Figures(
+        transcript_path=Path(row[0]),
+        transcript_size=row[1],
+        transcript_mtime_ns=row[2],
+        scanned_at=datetime.fromisoformat(row[3]),
+        turns=row[4],
+        input_tokens=row[5],
+        output_tokens=row[6],
+        cache_read_tokens=row[7],
+        cache_write_tokens=row[8],
+        models=_pairs(row[9]),
+        tools=_pairs(row[10]),
+        first_at=_moment(row[11]),
+        last_at=_moment(row[12]),
+        stale=stale,
+    )
+
+
+class Cache:
+    """The numbers a deep scan found, kept in one SQLite file in the tool's own folder.
+
+    A row is found by the transcript's path. A transcript that changed since
+    its scan still gives its row back, marked stale, so the old numbers stay
+    on view until a new scan replaces them.
+    """
+
+    def __init__(self, settings: Settings) -> None:
+        self.path = settings.cache_file
+
+    def _connect(self) -> sqlite3.Connection:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        connection = sqlite3.connect(self.path, timeout=LOCK_WAIT_SECONDS)
+        try:
+            connection.execute(SCHEMA)
+        except sqlite3.DatabaseError as error:
+            connection.close()
+            raise CacheDamaged(self.path, error) from error
+        return connection
+
+    def get(self, transcript: Path) -> Figures | None:
+        """The figures of one transcript, or None when it was never scanned.
+
+        The figures are stale when the file's size or change time differ from
+        the ones the scan saw, or when the file is gone. A damaged cache reads
+        as an empty one, so a list or a details pane still works. The next
+        ``put`` names the damage.
+        """
+        if not self.path.exists():
+            return None
+        names = ", ".join(COLUMNS)
+        try:
+            with self._connect() as connection:
+                row = connection.execute(
+                    f"SELECT {names} FROM figures WHERE path = ?", (str(transcript),)
+                ).fetchone()
+        except CacheDamaged:
+            return None
+        return _figures_of(row, _is_stale(transcript, row)) if row else None
+
+    def get_all(self) -> dict[Path, Figures]:
+        """The figures of every transcript ever scanned, by path, in one read.
+
+        Each is marked stale the same way ``get`` marks it. A missing or a
+        damaged cache gives an empty dict.
+        """
+        if not self.path.exists():
+            return {}
+        names = ", ".join(COLUMNS)
+        try:
+            with self._connect() as connection:
+                rows = connection.execute(f"SELECT {names} FROM figures").fetchall()
+        except CacheDamaged:
+            return {}
+        return {
+            Path(row[0]): _figures_of(row, _is_stale(Path(row[0]), row)) for row in rows
+        }
+
+    def put(self, figures: Figures) -> None:
+        """Remember the figures of one transcript, in place of any older ones."""
+        marks = ", ".join("?" for _ in COLUMNS)
+        names = ", ".join(COLUMNS)
+        with self._connect() as connection:
+            connection.execute(
+                f"INSERT OR REPLACE INTO figures ({names}) VALUES ({marks})",
+                _row_of(figures),
+            )
+
+    def forget_missing(self) -> int:
+        """Drop the rows of transcripts that are no longer on the disk. Returns how many."""
+        if not self.path.exists():
+            return 0
+        with self._connect() as connection:
+            paths = [row[0] for row in connection.execute("SELECT path FROM figures")]
+            gone = [(path,) for path in paths if not Path(path).exists()]
+            connection.executemany("DELETE FROM figures WHERE path = ?", gone)
+        return len(gone)