arvre 0.1.0__py3-none-any.whl

arvre/__init__.py

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

arvre/__main__.py

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

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/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/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}"

arvre/flowchart.py

@@ -0,0 +1,176 @@
+"""Left-to-right flowchart rendering of a session tree."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+from rich.text import Text
+
+from arvre.layout import Row, format_age
+from arvre.scanner import Session
+from arvre.themes import Theme
+
+BOX_W = 28
+BOX_H = 4
+GAP_X = 6
+GAP_Y = 1
+
+UP, DOWN, LEFT, RIGHT = 1, 2, 4, 8
+LINE_CHARS = {
+    UP | DOWN: "│",
+    LEFT | RIGHT: "─",
+    DOWN | RIGHT: "┌",
+    DOWN | LEFT: "┐",
+    UP | RIGHT: "└",
+    UP | LEFT: "┘",
+    UP | DOWN | RIGHT: "├",
+    UP | DOWN | LEFT: "┤",
+    DOWN | LEFT | RIGHT: "┬",
+    UP | LEFT | RIGHT: "┴",
+    UP | DOWN | LEFT | RIGHT: "┼",
+    UP: "│",
+    DOWN: "│",
+    LEFT: "─",
+    RIGHT: "─",
+}
+
+
+@dataclass(frozen=True)
+class Box:
+    sid: str
+    x: int
+    y: int
+
+
+@dataclass
+class FlowLayout:
+    boxes: dict[str, Box]
+    masks: list[list[int]]  # direction bits per cell, turned into line chars when drawn
+    width: int
+    height: int
+
+
+def flow_layout(rows: list[Row]) -> FlowLayout:
+    """Columns are tree depths; each parent is centred on its children."""
+    kids: dict[str, list[str]] = {}
+    for row in rows:
+        if row.session.parent_id:
+            kids.setdefault(row.session.parent_id, []).append(row.session.id)
+    depth = {row.session.id: row.depth for row in rows}
+
+    ys: dict[str, int] = {}
+    slot = 0
+
+    def place(sid: str) -> int:
+        nonlocal slot
+        children = kids.get(sid, [])
+        if children:
+            child_ys = [place(child) for child in children]
+            ys[sid] = (child_ys[0] + child_ys[-1]) // 2
+        else:
+            ys[sid] = slot * (BOX_H + GAP_Y)
+            slot += 1
+        return ys[sid]
+
+    for row in rows:
+        if row.depth == 0:
+            place(row.session.id)
+
+    boxes = {sid: Box(sid, depth[sid] * (BOX_W + GAP_X), y) for sid, y in ys.items()}
+    if not boxes:
+        return FlowLayout({}, [], 0, 0)
+
+    width = max(box.x for box in boxes.values()) + BOX_W
+    height = max(box.y for box in boxes.values()) + BOX_H
+    masks = [[0] * width for _ in range(height)]
+
+    for parent_id, child_ids in kids.items():
+        parent = boxes[parent_id]
+        exit_x = parent.x + BOX_W
+        exit_y = parent.y + 1
+        bend_x = exit_x + GAP_X // 2
+        for child_id in child_ids:
+            child = boxes[child_id]
+            enter_y = child.y + 1
+            enter_x = child.x - 1
+            _horizontal(masks, exit_y, exit_x, bend_x)
+            _vertical(masks, bend_x, exit_y, enter_y)
+            _horizontal(masks, enter_y, bend_x, enter_x)
+
+    return FlowLayout(boxes, masks, width, height)
+
+
+def _horizontal(masks: list[list[int]], y: int, x1: int, x2: int) -> None:
+    masks[y][x1] |= RIGHT
+    masks[y][x2] |= LEFT
+    for x in range(x1 + 1, x2):
+        masks[y][x] |= LEFT | RIGHT
+
+
+def _vertical(masks: list[list[int]], x: int, y1: int, y2: int) -> None:
+    if y1 == y2:
+        return
+    top, bottom = sorted((y1, y2))
+    masks[top][x] |= DOWN
+    masks[bottom][x] |= UP
+    for y in range(top + 1, bottom):
+        masks[y][x] |= UP | DOWN
+
+
+def flow_text(
+    layout: FlowLayout,
+    sessions: dict[str, Session],
+    now: datetime,
+    selected: str | None,
+    theme: Theme,
+) -> Text:
+    grid: list[list[tuple[str, str]]] = [
+        [(LINE_CHARS.get(mask, "┼") if mask else " ", theme.style("connector") if mask else "") for mask in row]
+        for row in layout.masks
+    ]
+    for box in layout.boxes.values():
+        _draw_box(grid, box, sessions[box.sid], now, theme, box.sid == selected)
+
+    text = Text(no_wrap=True)
+    for y, row in enumerate(grid):
+        for char, style in row:
+            text.append(char, style=style)
+        if y < len(grid) - 1:
+            text.append("\n")
+    return text
+
+
+def _draw_box(
+    grid: list[list[tuple[str, str]]],
+    box: Box,
+    session: Session,
+    now: datetime,
+    theme: Theme,
+    selected: bool,
+) -> None:
+    inner = BOX_W - 2
+    name = _fit(session.name, inner - 2)
+    stats = _fit(f"{format_age(now, session.last_ts)} · {_children(session)}", inner - 2)
+    lines = [
+        ("┌" + "─" * inner + "┐", "border"),
+        ("│ " + name.ljust(inner - 2) + " │", "name"),
+        ("│ " + stats.ljust(inner - 2) + " │", "meta"),
+        ("└" + "─" * inner + "┘", "border"),
+    ]
+    for dy, (line, role) in enumerate(lines):
+        for dx, char in enumerate(line):
+            frame = dy in (0, 3) or dx in (0, BOX_W - 1) or char == " "
+            cell_role = "border" if frame else role
+            grid[box.y + dy][box.x + dx] = (char, theme.style(cell_role, selected))
+
+
+def _children(session: Session) -> str:
+    count = len(session.child_ids)
+    if count == 0:
+        return "no children"
+    return "1 child" if count == 1 else f"{count} children"
+
+
+def _fit(text: str, width: int) -> str:
+    return text if len(text) <= width else text[: width - 1] + "…"

arvre/forks.py

@@ -0,0 +1,37 @@
+"""Infer parent/child links between sessions. See docs/forks.md."""
+
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+
+from arvre.scanner import Session
+
+
+def link_forks(sessions: dict[str, Session]) -> None:
+    """Set parent_id and child_ids on every session.
+
+    A fork is a copy of its parent's records with the same uuids, so the parent
+    of a session is the earlier session sharing the most uuids with it.
+    """
+    order = sorted(sessions.values(), key=lambda s: (s.first_ts, s.created))
+    rank = {s.id: i for i, s in enumerate(order)}
+
+    by_uuid: dict[str, list[str]] = defaultdict(list)
+    for session in sessions.values():
+        session.parent_id = None
+        session.child_ids = []
+        for uuid in session.uuids:
+            by_uuid[uuid].append(session.id)
+
+    for session in sessions.values():
+        shared: Counter[str] = Counter()
+        for uuid in session.uuids:
+            for other_id in by_uuid[uuid]:
+                if other_id != session.id and rank[other_id] < rank[session.id]:
+                    shared[other_id] += 1
+        if shared:
+            session.parent_id = max(shared, key=lambda oid: (shared[oid], -rank[oid]))
+
+    for session in sessions.values():
+        if session.parent_id:
+            sessions[session.parent_id].child_ids.append(session.id)

arvre/graph_view.py

@@ -0,0 +1,184 @@
+"""Clickable, keyboard-navigable widget that draws the session graph."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from rich.cells import cell_len
+from rich.text import Text
+from textual import events
+from textual.binding import Binding
+from textual.geometry import Region
+from textual.message import Message
+from textual.widget import Widget
+
+from arvre.flowchart import BOX_H, BOX_W, FlowLayout, flow_layout, flow_text
+from arvre.layout import Row, row_label, row_segments
+from arvre.scanner import Session
+from arvre.themes import THEMES, Theme
+
+
+class GraphView(Widget, can_focus=True):
+    BINDINGS = [
+        Binding("up,k", "move(-1)", "Up", show=False),
+        Binding("down,j", "move(1)", "Down", show=False),
+        Binding("left,h", "parent", "Parent"),
+        Binding("right,l", "child", "Child"),
+        Binding("enter", "activate", "Open"),
+    ]
+
+    class Highlighted(Message):
+        def __init__(self, session_id: str | None) -> None:
+            super().__init__()
+            self.session_id = session_id
+
+    class Activated(Message):
+        def __init__(self, session_id: str | None) -> None:
+            super().__init__()
+            self.session_id = session_id
+
+    def __init__(self, id: str | None = None) -> None:
+        super().__init__(id=id)
+        self.sessions: dict[str, Session] = {}
+        self.rows: list[Row] = []
+        self.now = datetime.now().astimezone()
+        self.style_name = "compact"
+        self.theme: Theme = THEMES["classic"]
+        self._index = 0
+        self._flow: FlowLayout | None = None
+
+    # --- data ---------------------------------------------------------------
+
+    def set_data(
+        self,
+        sessions: dict[str, Session],
+        rows: list[Row],
+        now: datetime,
+        style_name: str,
+        theme: Theme,
+    ) -> None:
+        selected = self.selected_id
+        self.sessions = sessions
+        self.rows = rows
+        self.now = now
+        self.style_name = style_name
+        self.theme = theme
+        self._index = next((i for i, r in enumerate(rows) if r.session.id == selected), 0)
+
+        if style_name == "flow":
+            self._flow = flow_layout(rows)
+            width, height = self._flow.width, self._flow.height
+        else:
+            self._flow = None
+            labels = [row_label(row, sessions, now) for row in rows]
+            width = max((cell_len(label) for label in labels), default=0)
+            height = len(labels)
+        self.styles.width = max(width, 1)
+        self.styles.height = max(height, 1)
+        self.refresh(layout=True)
+        self.post_message(self.Highlighted(self.selected_id))
+
+    @property
+    def selected_id(self) -> str | None:
+        if not self.rows:
+            return None
+        return self.rows[self._index].session.id
+
+    def select_id(self, session_id: str) -> bool:
+        for i, row in enumerate(self.rows):
+            if row.session.id == session_id:
+                self._select(i)
+                return True
+        return False
+
+    def _select(self, index: int) -> None:
+        if not self.rows:
+            return
+        self._index = max(0, min(index, len(self.rows) - 1))
+        self.refresh()
+        self._reveal()
+        self.post_message(self.Highlighted(self.selected_id))
+
+    def _reveal(self) -> None:
+        if self._flow:
+            box = self._flow.boxes[self.selected_id]
+            region = Region(box.x, box.y, BOX_W, BOX_H)
+        else:
+            region = Region(0, self._index, 1, 1)
+        self.scroll_to_region(region, animate=False)
+
+    def _index_at(self, x: int, y: int) -> int | None:
+        if self._flow:
+            for i, row in enumerate(self.rows):
+                box = self._flow.boxes[row.session.id]
+                if box.x <= x < box.x + BOX_W and box.y <= y < box.y + BOX_H:
+                    return i
+            return None
+        return y if 0 <= y < len(self.rows) else None
+
+    # --- rendering ----------------------------------------------------------
+
+    def render(self) -> Text:
+        if not self.rows:
+            return Text("")
+        if self._flow:
+            return flow_text(self._flow, self.sessions, self.now, self.selected_id, self.theme)
+        lines = []
+        for i, row in enumerate(self.rows):
+            selected = i == self._index
+            line = Text(no_wrap=True)
+            for segment, role in row_segments(row, self.sessions, self.now):
+                line.append(segment, style=self.theme.style(role, selected))
+            lines.append(line)
+        return Text("\n").join(lines)
+
+    # --- keyboard -----------------------------------------------------------
+
+    def action_move(self, step: int) -> None:
+        if self._flow:
+            self._move_same_level(step)
+        else:
+            self._select(self._index + step)
+
+    def _move_same_level(self, step: int) -> None:
+        """Flowchart: up/down step through sessions in the same column (same depth)."""
+        depth = self.rows[self._index].depth
+        level = [i for i, row in enumerate(self.rows) if row.depth == depth]
+        level.sort(key=lambda i: self._flow.boxes[self.rows[i].session.id].y)
+        target = level.index(self._index) + step
+        if 0 <= target < len(level):
+            self._select(level[target])
+
+    def action_parent(self) -> None:
+        if self.selected_id is None:
+            return
+        parent = self.sessions[self.selected_id].parent_id
+        if parent:
+            self.select_id(parent)
+
+    def action_child(self) -> None:
+        if self.selected_id is None:
+            return
+        child = next(
+            (i for i, row in enumerate(self.rows) if row.session.parent_id == self.selected_id),
+            None,
+        )
+        if child is not None:
+            self._select(child)
+
+    def action_activate(self) -> None:
+        self.post_message(self.Activated(self.selected_id))
+
+    # --- mouse --------------------------------------------------------------
+
+    def on_click(self, event: events.Click) -> None:
+        offset = event.get_content_offset(self)
+        if offset is None:
+            return
+        index = self._index_at(offset.x, offset.y)
+        if index is None:
+            return
+        if index == self._index:
+            self.post_message(self.Activated(self.selected_id))
+        else:
+            self._select(index)

arvre/layout.py

@@ -0,0 +1,117 @@
+"""Filtering and tree layout for the session graph."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+
+from arvre.scanner import Session
+
+WINDOW = timedelta(hours=24)
+
+
+@dataclass(frozen=True)
+class Row:
+    session: Session
+    prefix: str
+    depth: int
+
+
+def visible_ids(
+    sessions: dict[str, Session],
+    now: datetime,
+    window_24h: bool,
+    all_projects: bool,
+    cwd: str,
+) -> set[str]:
+    cutoff = now - WINDOW
+    return {
+        s.id
+        for s in sessions.values()
+        if (not window_24h or s.last_ts >= cutoff)
+        and (all_projects or s.cwd == cwd)
+    }
+
+
+def tree_members(sessions: dict[str, Session], visible: set[str]) -> set[str]:
+    """Every session in the family tree of any matching session."""
+    roots = set()
+    for sid in visible:
+        current = sid
+        while sessions[current].parent_id:
+            current = sessions[current].parent_id
+        roots.add(current)
+
+    members: set[str] = set()
+    stack = list(roots)
+    while stack:
+        sid = stack.pop()
+        members.add(sid)
+        stack.extend(sessions[sid].child_ids)
+    return members
+
+
+def build_rows(sessions: dict[str, Session], shown: set[str]) -> list[Row]:
+    children: dict[str, list[str]] = defaultdict(list)
+    roots: list[str] = []
+    for sid in shown:
+        parent = sessions[sid].parent_id
+        if parent in shown:
+            children[parent].append(sid)
+        else:
+            roots.append(sid)
+
+    def newest_first(ids: list[str]) -> list[str]:
+        return sorted(ids, key=lambda sid: sessions[sid].last_ts, reverse=True)
+
+    rows: list[Row] = []
+
+    def walk(sid: str, prefix: str, child_base: str, depth: int) -> None:
+        rows.append(Row(sessions[sid], prefix, depth))
+        kids = newest_first(children[sid])
+        for i, kid in enumerate(kids):
+            last = i == len(kids) - 1
+            walk(
+                kid,
+                child_base + ("└─ " if last else "├─ "),
+                child_base + ("   " if last else "│  "),
+                depth + 1,
+            )
+
+    for root in newest_first(roots):
+        walk(root, "", "", 0)
+    return rows
+
+
+def format_age(now: datetime, then: datetime) -> str:
+    seconds = int((now - then).total_seconds())
+    if seconds < 60:
+        return "just now"
+    if seconds < 3600:
+        return f"{seconds // 60}m ago"
+    if seconds < 86400:
+        return f"{seconds // 3600}h ago"
+    return f"{seconds // 86400}d ago"
+
+
+def row_segments(row: Row, sessions: dict[str, Session], now: datetime) -> list[tuple[str, str]]:
+    """The compact row as (text, role) pairs; roles are styled by the theme."""
+    s = row.session
+    local = s.last_ts.astimezone().strftime("%Y-%m-%d %H:%M")
+    meta = [f"{format_age(now, s.last_ts)} ({local})"]
+    if s.parent_id:
+        meta.append(f"↑ {sessions[s.parent_id].name}")
+    if s.child_ids:
+        count = len(s.child_ids)
+        meta.append(f"{count} {'child' if count == 1 else 'children'}")
+
+    segments = [(row.prefix, "connector"), ("● ", "bullet"), (s.name, "name")]
+    for text in meta:
+        segments.append(("  · ", "meta"))
+        segments.append((text, "meta"))
+    return segments
+
+
+def row_label(row: Row, sessions: dict[str, Session], now: datetime) -> str:
+    return "".join(text for text, _ in row_segments(row, sessions, now))

arvre/scanner.py

@@ -0,0 +1,113 @@
+"""Read Claude Code session files from ~/.claude/projects."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+
+DEFAULT_ROOT = Path.home() / ".claude" / "projects"
+MESSAGE_TYPES = {"user", "assistant"}
+
+
+@dataclass
+class Session:
+    id: str
+    path: Path
+    cwd: str
+    name: str
+    first_ts: datetime
+    last_ts: datetime
+    branch: str
+    created: float
+    uuids: frozenset[str] = field(repr=False)
+    parent_id: str | None = None
+    child_ids: list[str] = field(default_factory=list)
+
+
+def parse_ts(value: str) -> datetime:
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def last_field(records: list[dict], key: str, record_type: str | None = None) -> str:
+    for record in reversed(records):
+        if record_type and record.get("type") != record_type:
+            continue
+        if record.get(key):
+            return str(record[key])
+    return ""
+
+
+def display_name(records: list[dict], session_id: str) -> str:
+    """Same priority as /resume: custom title, AI title, last prompt, short id."""
+    custom = last_field(records, "customTitle", "custom-title")
+    if custom:
+        return custom
+    ai = last_field(records, "aiTitle", "ai-title")
+    if ai:
+        return ai
+    prompt = last_field(records, "lastPrompt", "last-prompt").strip()
+    if prompt:
+        return prompt.splitlines()[0][:60]
+    return session_id[:8]
+
+
+def parse_session(path: Path) -> Session | None:
+    records: list[dict] = []
+    with path.open(encoding="utf-8", errors="replace") as handle:
+        for line in handle:
+            try:
+                records.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+
+    messages = [
+        r
+        for r in records
+        if r.get("type") in MESSAGE_TYPES and not r.get("isSidechain") and r.get("timestamp")
+    ]
+    if not messages:
+        return None
+
+    stamps = [parse_ts(r["timestamp"]) for r in messages]
+    stat = path.stat()
+    session_id = path.stem
+    return Session(
+        id=session_id,
+        path=path,
+        cwd=next((r["cwd"] for r in records if r.get("cwd")), ""),
+        name=display_name(records, session_id),
+        first_ts=min(stamps),
+        last_ts=max(stamps),
+        branch=last_field(messages, "gitBranch"),
+        created=getattr(stat, "st_birthtime", stat.st_ctime),
+        uuids=frozenset(r["uuid"] for r in messages if r.get("uuid")),
+    )
+
+
+def discover(root: Path = DEFAULT_ROOT, cache: dict | None = None) -> dict[str, Session]:
+    """Parse every session under root. `cache` maps path -> (mtime, size, Session)."""
+    sessions: dict[str, Session] = {}
+    if not root.is_dir():
+        return sessions
+    cache = {} if cache is None else cache
+    for path in root.glob("*/*.jsonl"):
+        try:
+            stat = path.stat()
+        except OSError:
+            continue
+        key = (stat.st_mtime_ns, stat.st_size)
+        cached = cache.get(path)
+        if cached and cached[0] == key:
+            session = cached[1]
+        else:
+            try:
+                session = parse_session(path)
+            except OSError:
+                session = None
+            cache[path] = (key, session)
+        if session:
+            sessions[session.id] = session
+    return sessions

arvre/themes.py

@@ -0,0 +1,76 @@
+"""Colour palettes for the session graph."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Theme:
+    name: str
+    connector: str  # tree and flowchart lines
+    bullet: str
+    name_style: str  # session names
+    meta: str  # age, counts, parent arrow
+    border: str  # flowchart box frames
+    selected: str  # the highlighted row or box
+    accent: str  # key letters in the status line
+
+    def style(self, role: str, selected: bool = False) -> str:
+        if selected:
+            return self.selected
+        return {
+            "connector": self.connector,
+            "bullet": self.bullet,
+            "name": self.name_style,
+            "meta": self.meta,
+            "border": self.border,
+        }.get(role, "")
+
+
+THEMES: dict[str, Theme] = {
+    theme.name: theme
+    for theme in [
+        Theme(
+            name="classic",
+            connector="dim",
+            bullet="",
+            name_style="bold",
+            meta="dim",
+            border="",
+            selected="reverse",
+            accent="bold",
+        ),
+        Theme(
+            name="ocean",
+            connector="#4a86b8",
+            bullet="#5fd7ff",
+            name_style="bold #e6f1ff",
+            meta="#7f98b5",
+            border="#4a86b8",
+            selected="bold #0b1d2e on #5fd7ff",
+            accent="bold #5fd7ff",
+        ),
+        Theme(
+            name="forest",
+            connector="#5f8f5f",
+            bullet="#a6e3a1",
+            name_style="bold #d8f3dc",
+            meta="#8aa58a",
+            border="#5f8f5f",
+            selected="bold #0d2b1a on #a6e3a1",
+            accent="bold #a6e3a1",
+        ),
+        Theme(
+            name="sunset",
+            connector="#c26a5a",
+            bullet="#ffb86c",
+            name_style="bold #ffe6cc",
+            meta="#c9a38f",
+            border="#e07a5f",
+            selected="bold #2b1420 on #ffb86c",
+            accent="bold #ffb86c",
+        ),
+    ]
+}
+THEME_ORDER = list(THEMES)

arvre-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,17 @@
+arvre/__init__.py,sha256=ryMDtJzlnMHjAX55Ig_irn7vpor1dKjVHNZmp3y7v8M,85
+arvre/__main__.py,sha256=-LJMp_IM7ZHZn3dwyVop0bRH1s39OKfoc2UNdRW-EuI,35
+arvre/app.py,sha256=mRBYx5lvhjKbzDhcKB9okc029tQv5EZ4EuDeLgh56p0,8583
+arvre/cli.py,sha256=kLyPaPNBsZ9fqIQ-AAZzxdUfba2JdRm-xTytKxr1umM,2114
+arvre/commands.py,sha256=a_VG4vx28riRwaB-qSzAryODkXbrti4RsKzozQJEKk0,317
+arvre/flowchart.py,sha256=QyzEeLdxFQkbQtMA8C3rdBSOSgxcrYUyloAKaR-QdB0,4949
+arvre/forks.py,sha256=1I24NzeC1uyYNwtfDf_IlLThyfsjiZc5r2tcyyHiyIw,1344
+arvre/graph_view.py,sha256=ygkcjfaP9pYsTsjK1rOQsclSH19ft595PYGM2ezkCew,6384
+arvre/layout.py,sha256=vzT6pZnoEOevVcVadhkcMwNWcsgjiKKpfAwCfUYa1ow,3437
+arvre/scanner.py,sha256=wZk2jFerNiIswTmOBoozp5WC_UDS08lXXmg8WCVj36E,3363
+arvre/themes.py,sha256=7DgW0lA4Dx8ccxDRpPRS-14hmNjdF7q3TmlBOfJfrBM,2025
+arvre-0.1.0.dist-info/licenses/LICENSE,sha256=UbT2l7z_OBJqur-yYSOEgZRDLRNMG_wul-b6Y1vrFa4,1071
+arvre-0.1.0.dist-info/METADATA,sha256=2QEXLZmsVY_dzjq9PiuT0GaiKg8aiN6ZE5UT4Nh5CoA,3379
+arvre-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+arvre-0.1.0.dist-info/entry_points.txt,sha256=KmXSwuNS-xEG7QSYbhNN47TcPG7O38cr0bHlcl5hODY,41
+arvre-0.1.0.dist-info/top_level.txt,sha256=oZ7d9aSN6h4pScYSGgWCpKFtGQupGIkIQGxE9g0nsGA,6
+arvre-0.1.0.dist-info/RECORD,,

arvre-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

arvre-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+arvre = arvre.cli:main

arvre-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+arvre