arvre 0.1.0__tar.gz

arvre-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Victor Carrico
+
+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.

arvre-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: arvre
+Version: 0.1.0
+Summary: Terminal graph of Claude Code sessions and their forks
+Author: Victor Carrico
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/victorcarrico/arvre
+Project-URL: Issues, https://github.com/victorcarrico/arvre/issues
+Keywords: claude,claude-code,tui,sessions,fork
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: textual<9,>=8.2.8
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Dynamic: license-file
+
+# arvre
+
+A terminal graph of your Claude Code sessions and their forks.
+
+`/resume` shows sessions as a flat list. `arvre` shows them as a tree, so you can see which session was forked from which, when each one was last used, and jump between parents and children.
+
+Example output (sample names):
+
+```
+● Auth refactor  · 3h ago (2026-10-30 19:12)  · 2 children
+├─ ● try the other approach  · 1h ago (2026-10-30 21:02)  · ↑ Auth refactor
+└─ ● spike rename test  · 2m ago (2026-10-30 22:08)  · ↑ Auth refactor
+```
+
+## Install
+
+With pipx (macOS and Linux, Python 3.11+):
+
+```sh
+pipx install git+https://github.com/victorcarrico/arvre
+```
+
+You need Claude Code installed, with `claude` on your `PATH`, for the "open in this terminal" action.
+
+## Usage
+
+```sh
+arvre                      # sessions from the current directory, last 24 hours
+arvre --all-time           # all sessions, not just the last 24 hours
+arvre --all-projects       # sessions from every project
+arvre --style flow         # start with the left-to-right flowchart
+arvre --theme ocean        # start with a colour theme
+arvre --print              # print the tree as text and exit
+```
+
+Run `arvre --help` for all options.
+
+### Keys
+
+| Key | Action |
+| --- | --- |
+| `↑` / `↓` (`k` / `j`) | Move. In compact style, through the tree. In flowchart style, to the next session at the same depth. |
+| `←` / `→` (`h` / `l`) | Go to the parent / first child |
+| `Enter` | Open the action menu for the selected session (or click it twice) |
+| `a` | Toggle last 24 hours / all time |
+| `p` | Toggle this directory / all projects |
+| `v` | Toggle compact / flowchart style |
+| `t` | Cycle colour themes (`classic`, `ocean`, `forest`, `sunset`) |
+| `r` | Reload |
+| `q` | Quit |
+
+The action menu offers:
+
+- **Open in this terminal**: runs `claude --resume <id>` in the session's directory, and returns to arvre when Claude exits.
+- **Copy command**: copies `cd '<dir>' && claude --resume <id>` to the clipboard, for pasting into another terminal.
+
+## How forks are detected
+
+Claude Code doesn't record a parent link when you fork a session. A fork is a copy of its parent's messages, so arvre links each session to the earlier session that shares the most message IDs with it. The details are in [docs/forks.md](docs/forks.md).
+
+Session data is read from `~/.claude/projects`. This is an undocumented format, so a future Claude Code release could change it.
+
+## Development
+
+```sh
+python3 -m venv .venv
+.venv/bin/pip install -e ".[test]"
+.venv/bin/python -m pytest
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

arvre-0.1.0/README.md

@@ -0,0 +1,73 @@
+# arvre
+
+A terminal graph of your Claude Code sessions and their forks.
+
+`/resume` shows sessions as a flat list. `arvre` shows them as a tree, so you can see which session was forked from which, when each one was last used, and jump between parents and children.
+
+Example output (sample names):
+
+```
+● Auth refactor  · 3h ago (2026-10-30 19:12)  · 2 children
+├─ ● try the other approach  · 1h ago (2026-10-30 21:02)  · ↑ Auth refactor
+└─ ● spike rename test  · 2m ago (2026-10-30 22:08)  · ↑ Auth refactor
+```
+
+## Install
+
+With pipx (macOS and Linux, Python 3.11+):
+
+```sh
+pipx install git+https://github.com/victorcarrico/arvre
+```
+
+You need Claude Code installed, with `claude` on your `PATH`, for the "open in this terminal" action.
+
+## Usage
+
+```sh
+arvre                      # sessions from the current directory, last 24 hours
+arvre --all-time           # all sessions, not just the last 24 hours
+arvre --all-projects       # sessions from every project
+arvre --style flow         # start with the left-to-right flowchart
+arvre --theme ocean        # start with a colour theme
+arvre --print              # print the tree as text and exit
+```
+
+Run `arvre --help` for all options.
+
+### Keys
+
+| Key | Action |
+| --- | --- |
+| `↑` / `↓` (`k` / `j`) | Move. In compact style, through the tree. In flowchart style, to the next session at the same depth. |
+| `←` / `→` (`h` / `l`) | Go to the parent / first child |
+| `Enter` | Open the action menu for the selected session (or click it twice) |
+| `a` | Toggle last 24 hours / all time |
+| `p` | Toggle this directory / all projects |
+| `v` | Toggle compact / flowchart style |
+| `t` | Cycle colour themes (`classic`, `ocean`, `forest`, `sunset`) |
+| `r` | Reload |
+| `q` | Quit |
+
+The action menu offers:
+
+- **Open in this terminal**: runs `claude --resume <id>` in the session's directory, and returns to arvre when Claude exits.
+- **Copy command**: copies `cd '<dir>' && claude --resume <id>` to the clipboard, for pasting into another terminal.
+
+## How forks are detected
+
+Claude Code doesn't record a parent link when you fork a session. A fork is a copy of its parent's messages, so arvre links each session to the earlier session that shares the most message IDs with it. The details are in [docs/forks.md](docs/forks.md).
+
+Session data is read from `~/.claude/projects`. This is an undocumented format, so a future Claude Code release could change it.
+
+## Development
+
+```sh
+python3 -m venv .venv
+.venv/bin/pip install -e ".[test]"
+.venv/bin/python -m pytest
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

arvre-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "arvre"
+version = "0.1.0"
+description = "Terminal graph of Claude Code sessions and their forks"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "Victor Carrico" }]
+keywords = ["claude", "claude-code", "tui", "sessions", "fork"]
+classifiers = [
+    "Environment :: Console",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Topic :: Utilities",
+]
+dependencies = ["textual>=8.2.8,<9"]
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-asyncio"]
+
+[project.urls]
+Homepage = "https://github.com/victorcarrico/arvre"
+Issues = "https://github.com/victorcarrico/arvre/issues"
+
+[project.scripts]
+arvre = "arvre.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_default_fixture_loop_scope = "function"

arvre-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

arvre-0.1.0/src/arvre/__init__.py

@@ -0,0 +1,3 @@
+"""Terminal graph of Claude Code sessions and their forks."""
+
+__version__ = "0.1.0"

arvre-0.1.0/src/arvre/__main__.py

@@ -0,0 +1,3 @@
+from arvre.cli import main
+
+main()

arvre-0.1.0/src/arvre/app.py

@@ -0,0 +1,236 @@
+"""Textual interface: session graph, filters, and the action modal."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from datetime import datetime, timezone
+from functools import partial
+from pathlib import Path
+
+from rich.text import Text
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import ScrollableContainer, Vertical
+from textual.screen import ModalScreen
+from textual.widgets import Label, OptionList, Static
+from textual.widgets.option_list import Option
+
+from arvre.commands import resume_command
+from arvre.forks import link_forks
+from arvre.graph_view import GraphView
+from arvre.layout import build_rows, tree_members, visible_ids
+from arvre.scanner import DEFAULT_ROOT, Session, discover
+from arvre.themes import THEME_ORDER, THEMES, Theme
+
+
+class ActionModal(ModalScreen[str | None]):
+    """Choose what to do with a session. Dismisses with "open", "copy" or None."""
+
+    BINDINGS = [Binding("escape", "close", "Close")]
+
+    def __init__(self, session: Session) -> None:
+        super().__init__()
+        self.session = session
+
+    def compose(self) -> ComposeResult:
+        with Vertical(id="modal"):
+            yield Label(Text(self.session.name, style="bold"), id="modal-title")
+            yield Static(f"{self.session.id}\n{self.session.cwd}", id="modal-meta")
+            yield OptionList(
+                Option("Open in this terminal", id="open"),
+                Option("Copy command", id="copy"),
+                id="modal-actions",
+            )
+            yield Static(resume_command(self.session), id="modal-command")
+
+    def on_mount(self) -> None:
+        self.query_one(OptionList).focus()
+
+    def on_option_list_option_selected(self, event: OptionList.OptionSelected) -> None:
+        self.dismiss(event.option.id)
+
+    def action_close(self) -> None:
+        self.dismiss(None)
+
+
+class ArvreApp(App):
+    TITLE = "arvre"
+    CSS = """
+    #scroll { height: 1fr; }
+    #detail { height: auto; max-height: 8; padding: 0 1; border-top: solid $accent; }
+    #status { height: 1; padding: 0 1; }
+    ActionModal { align: center middle; }
+    #modal { width: 70; height: auto; border: thick $accent; background: $surface; padding: 1 2; }
+    #modal-actions { height: auto; margin: 1 0; }
+    #modal-meta, #modal-command { color: $text-muted; }
+    """
+    BINDINGS = [
+        Binding("q", "quit", "Quit"),
+        Binding("r", "reload", "Reload"),
+        Binding("a", "toggle_window", "24h / all"),
+        Binding("p", "toggle_scope", "this dir / all"),
+        Binding("v", "toggle_style", "compact / flow"),
+        Binding("t", "toggle_theme", "theme"),
+    ]
+
+    def __init__(
+        self,
+        cwd: str,
+        root: Path = DEFAULT_ROOT,
+        window_24h: bool = True,
+        all_projects: bool = False,
+        style: str = "compact",
+        theme: str = "classic",
+    ) -> None:
+        super().__init__()
+        self.cwd = cwd
+        self.root = root
+        self.window_24h = window_24h
+        self.all_projects = all_projects
+        self.style_name = style
+        self.theme_name = theme
+        self.sessions: dict[str, Session] = {}
+        self._cache: dict = {}
+
+    @property
+    def palette(self) -> Theme:
+        return THEMES[self.theme_name]
+
+    def compose(self) -> ComposeResult:
+        with ScrollableContainer(id="scroll"):
+            yield GraphView(id="graph")
+        yield Static(id="detail")
+        yield Static(id="status")
+
+    def on_mount(self) -> None:
+        self.load()
+        self.query_one(GraphView).focus()
+
+    # --- data -------------------------------------------------------------
+
+    def load(self) -> None:
+        self.sessions = discover(self.root, self._cache)
+        link_forks(self.sessions)
+        self.refresh_rows()
+
+    def refresh_rows(self) -> None:
+        now = datetime.now(timezone.utc)
+        visible = visible_ids(self.sessions, now, self.window_24h, self.all_projects, self.cwd)
+        rows = build_rows(self.sessions, tree_members(self.sessions, visible))
+        self.query_one(GraphView).set_data(self.sessions, rows, now, self.style_name, self.palette)
+        self.update_status(len(visible))
+
+    def update_status(self, count: int) -> None:
+        accent = self.palette.accent
+        scope = "all projects" if self.all_projects else "this dir"
+        window = "24h" if self.window_24h else "all time"
+        line = Text()
+        for key, label in [
+            ("a", window),
+            ("p", scope),
+            ("v", self.style_name),
+            ("t", f"theme {self.theme_name}"),
+        ]:
+            line.append(f"{key} ", style=accent)
+            line.append(f"{label}  ")
+        line.append("r ", style=accent)
+        line.append("reload  ")
+        line.append("q ", style=accent)
+        line.append("quit  ")
+        line.append(f"· {count} sessions")
+        self.query_one("#status", Static).update(line)
+        self.update_detail(self.query_one(GraphView).selected_id)
+
+    def update_detail(self, sid: str | None) -> None:
+        detail = self.query_one("#detail", Static)
+        if sid is None:
+            detail.update(Text("No sessions match the filters. Press a / p to widen them."))
+            return
+        theme = self.palette
+        s = self.sessions[sid]
+        parent = self.sessions[s.parent_id].name if s.parent_id else "none"
+        children = ", ".join(self.sessions[c].name for c in s.child_ids) or "none"
+        text = Text()
+        text.append(s.name, style=theme.style("name"))
+        text.append(f"\nid {s.id}  ·  branch {s.branch or '-'}  ·  {s.cwd}", style=theme.style("meta"))
+        text.append("\nparent: ", style=theme.style("meta"))
+        text.append(parent)
+        text.append("\nchildren: ", style=theme.style("meta"))
+        text.append(children)
+        detail.update(text)
+
+    # --- events -------------------------------------------------------------
+
+    def on_graph_view_highlighted(self, event: GraphView.Highlighted) -> None:
+        self.update_detail(event.session_id)
+
+    def on_graph_view_activated(self, event: GraphView.Activated) -> None:
+        if event.session_id is None:
+            return
+        session = self.sessions[event.session_id]
+        self.push_screen(ActionModal(session), callback=partial(self.run_choice, session))
+
+    # --- actions ------------------------------------------------------------
+
+    def action_reload(self) -> None:
+        self.load()
+
+    def action_toggle_window(self) -> None:
+        self.window_24h = not self.window_24h
+        self.refresh_rows()
+
+    def action_toggle_scope(self) -> None:
+        self.all_projects = not self.all_projects
+        self.refresh_rows()
+
+    def action_toggle_style(self) -> None:
+        self.style_name = "flow" if self.style_name == "compact" else "compact"
+        self.refresh_rows()
+
+    def action_toggle_theme(self) -> None:
+        self.theme_name = THEME_ORDER[(THEME_ORDER.index(self.theme_name) + 1) % len(THEME_ORDER)]
+        self.refresh_rows()
+
+    def run_choice(self, session: Session, choice: str | None) -> None:
+        if choice == "open":
+            self.open_here(session)
+        elif choice == "copy":
+            self.copy_command(session)
+
+    def open_here(self, session: Session) -> None:
+        if not os.path.isdir(session.cwd):
+            self.notify(f"Directory no longer exists: {session.cwd}", severity="error")
+            return
+        try:
+            with self.suspend():
+                subprocess.run(["claude", "--resume", session.id], cwd=session.cwd, check=False)
+        except FileNotFoundError:
+            self.notify("`claude` was not found on PATH.", severity="error")
+            return
+        self.load()
+
+    def copy_command(self, session: Session) -> None:
+        command = resume_command(session)
+        self.copy_to_clipboard(command)  # OSC 52: works over SSH and in most modern terminals
+        clipboard = system_clipboard_command()
+        if clipboard:
+            subprocess.run(clipboard, input=command, text=True, check=False)
+        self.notify(f"Copied: {command}")
+
+
+def system_clipboard_command() -> list[str] | None:
+    """A native clipboard tool for this platform, if one is installed."""
+    if sys.platform == "darwin":
+        return ["pbcopy"]
+    candidates = [
+        ["wl-copy"],
+        ["xclip", "-selection", "clipboard"],
+        ["xsel", "--clipboard", "--input"],
+    ]
+    for command in candidates:
+        if shutil.which(command[0]):
+            return command
+    return None

arvre-0.1.0/src/arvre/cli.py

@@ -0,0 +1,63 @@
+"""Command-line entry point for arvre."""
+
+from __future__ import annotations
+
+import argparse
+import os
+from datetime import datetime, timezone
+
+from arvre.app import ArvreApp
+from arvre.forks import link_forks
+from arvre.layout import build_rows, row_label, tree_members, visible_ids
+from arvre.scanner import DEFAULT_ROOT, discover
+from arvre.themes import THEMES
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="arvre",
+        description="Show Claude Code sessions and their forks as a graph.",
+    )
+    parser.add_argument("--dir", default=os.getcwd(), help="project directory to show (default: current)")
+    parser.add_argument("--all-projects", action="store_true", help="start with sessions from every project")
+    parser.add_argument("--all-time", action="store_true", help="start with all sessions, not only the last 24h")
+    parser.add_argument(
+        "--style",
+        choices=["compact", "flow"],
+        default="compact",
+        help="tree style to start with (default: compact)",
+    )
+    parser.add_argument(
+        "--theme",
+        choices=list(THEMES),
+        default="classic",
+        help="colour theme to start with (default: classic); press t to cycle",
+    )
+    parser.add_argument("--print", dest="print_only", action="store_true", help="print the graph as text and exit")
+    args = parser.parse_args(argv)
+
+    cwd = os.path.realpath(args.dir)
+    if args.print_only:
+        print_graph(cwd, args)
+        return
+    ArvreApp(
+        cwd=cwd,
+        root=DEFAULT_ROOT,
+        window_24h=not args.all_time,
+        all_projects=args.all_projects,
+        style=args.style,
+        theme=args.theme,
+    ).run()
+
+
+def print_graph(cwd: str, args: argparse.Namespace) -> None:
+    now = datetime.now(timezone.utc)
+    sessions = discover(DEFAULT_ROOT)
+    link_forks(sessions)
+    visible = visible_ids(sessions, now, not args.all_time, args.all_projects, cwd)
+    for row in build_rows(sessions, tree_members(sessions, visible)):
+        print(row_label(row, sessions, now))
+
+
+if __name__ == "__main__":
+    main()

arvre-0.1.0/src/arvre/commands.py

@@ -0,0 +1,12 @@
+"""Commands for resuming a session."""
+
+from __future__ import annotations
+
+import shlex
+
+from arvre.scanner import Session
+
+
+def resume_command(session: Session) -> str:
+    # --resume is scoped to the project directory, so cd there first.
+    return f"cd {shlex.quote(session.cwd)} && claude --resume {session.id}"