agent-chat-reader 0.1.3__tar.gz → 0.1.4__tar.gz

{agent_chat_reader-0.1.3 → agent_chat_reader-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-chat-reader
-Version: 0.1.3
+Version: 0.1.4
 Summary: Read and search Codex CLI and Claude Code chat history from the terminal.
 Project-URL: Homepage, https://github.com/alik-git/agent-chat-reader
 Project-URL: Repository, https://github.com/alik-git/agent-chat-reader
@@ -68,6 +68,8 @@ agent-chat-reader --find "policy_interface" --source codex
 agent-chat-reader 019eaecb
 agent-chat-reader 1bfc739b --verbose     # include tool call summaries
 agent-chat-reader 019eaecb --tail 5      # last 5 user turns only
+agent-chat-reader 019eaecb --hide-timestamps
+agent-chat-reader 019eaecb --format json
 ```
 
 ## What it filters out
@@ -89,8 +91,18 @@ Use `--include-subagents` to see everything.
 | `--verbose` / `-v` | Include brief tool call summaries (Claude sessions) |
 | `--tail N` / `-n N` | Show only the last N user turns of a session |
 | `--include-subagents` | Include guardian/subagent sessions |
+| `--format text\|json` | Output format for session reads |
+| `--hide-timestamps` | Hide message timestamps and elapsed-gap labels |
 | `--limit N` | Max sessions shown by `--list` (default: 40) |
 
+Session reads show timestamps by default. Elapsed labels use the current
+speaker's role, such as `(agent took 8s)` or `(user took 4m)`, and only report
+the time since the previous visible message.
+
+Use `--format json` when another agent or script needs stable structured
+fields instead of terminal separators. JSON turns include `timestamp`,
+`local_time`, `elapsed_seconds`, `role`, and `text`.
+
 ## Session storage locations
 
 | Agent | Path |

{agent_chat_reader-0.1.3 → agent_chat_reader-0.1.4}/README.md

@@ -40,6 +40,8 @@ agent-chat-reader --find "policy_interface" --source codex
 agent-chat-reader 019eaecb
 agent-chat-reader 1bfc739b --verbose     # include tool call summaries
 agent-chat-reader 019eaecb --tail 5      # last 5 user turns only
+agent-chat-reader 019eaecb --hide-timestamps
+agent-chat-reader 019eaecb --format json
 ```
 
 ## What it filters out
@@ -61,8 +63,18 @@ Use `--include-subagents` to see everything.
 | `--verbose` / `-v` | Include brief tool call summaries (Claude sessions) |
 | `--tail N` / `-n N` | Show only the last N user turns of a session |
 | `--include-subagents` | Include guardian/subagent sessions |
+| `--format text\|json` | Output format for session reads |
+| `--hide-timestamps` | Hide message timestamps and elapsed-gap labels |
 | `--limit N` | Max sessions shown by `--list` (default: 40) |
 
+Session reads show timestamps by default. Elapsed labels use the current
+speaker's role, such as `(agent took 8s)` or `(user took 4m)`, and only report
+the time since the previous visible message.
+
+Use `--format json` when another agent or script needs stable structured
+fields instead of terminal separators. JSON turns include `timestamp`,
+`local_time`, `elapsed_seconds`, `role`, and `text`.
+
 ## Session storage locations
 
 | Agent | Path |

{agent_chat_reader-0.1.3 → agent_chat_reader-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-chat-reader"
-version = "0.1.3"
+version = "0.1.4"
 description = "Read and search Codex CLI and Claude Code chat history from the terminal."
 readme = "README.md"
 requires-python = ">=3.11"

{agent_chat_reader-0.1.3 → agent_chat_reader-0.1.4}/src/agent_chat_reader/__init__.py

@@ -2,6 +2,6 @@
 
 from __future__ import annotations
 
-__version__ = "0.1.3"
+__version__ = "0.1.4"
 
 __all__ = ["__version__"]

{agent_chat_reader-0.1.3 → agent_chat_reader-0.1.4}/src/agent_chat_reader/cli.py

@@ -3,13 +3,16 @@
 from __future__ import annotations
 
 import argparse
+import json
 import sys
 from pathlib import Path
 
 from agent_chat_reader import __version__, claude, codex
-from agent_chat_reader.models import SessionMeta
+from agent_chat_reader.models import SessionMeta, Turn
 from agent_chat_reader.output import (
     FindHit,
+    elapsed_seconds_between,
+    fmt_ts,
     print_find_result,
     print_session_list,
     print_turn,
@@ -124,6 +127,8 @@ def cmd_read(
     verbose: bool,
     include_subagents: bool,
     tail: int | None,
+    show_timestamps: bool,
+    output_format: str,
 ) -> int:
     """Read a specific session as clean conversation."""
     result = _find_session(session_id)
@@ -133,7 +138,6 @@ def cmd_read(
 
     path, source = result
     size_kb = path.stat().st_size // 1024
-    print(f"Source: {source.upper()}  |  {path.name}  |  {size_kb}KB")
 
     if source == "codex":
         turns = codex.read_turns(path, tail=tail)
@@ -142,18 +146,69 @@ def cmd_read(
             path, verbose=verbose, include_subagents=include_subagents, tail=tail
         )
 
+    if output_format == "json":
+        print(_json_session(source=source, path=path, size_kb=size_kb, turns=turns))
+        return 0
+
+    print(f"Source: {source.upper()}  |  {path.name}  |  {size_kb}KB")
+
     if not turns:
         print("(no conversation turns found)")
         return 0
 
+    previous_turn = None
     for turn in turns:
-        print_turn(turn)
+        print_turn(
+            turn,
+            show_timestamps=show_timestamps,
+            previous_turn=previous_turn,
+        )
+        previous_turn = turn
 
     print(f"\n{'─' * 60}")
     print(f"Total turns: {len(turns)}")
     return 0
 
 
+def _json_session(*, source: str, path: Path, size_kb: int, turns: list[Turn]) -> str:
+    """Serialize a read session as structured JSON."""
+    previous_turn = None
+    turn_records: list[dict[str, object]] = []
+    for turn in turns:
+        elapsed_seconds: int | None = (
+            None
+            if previous_turn is None
+            else elapsed_seconds_between(previous_turn, turn)
+        )
+        turn_records.append(
+            {
+                "role": turn.role,
+                "timestamp": turn.timestamp or None,
+                "local_time": fmt_ts(turn.timestamp) or None,
+                "elapsed_seconds": elapsed_seconds,
+                "text": turn.text,
+            }
+        )
+        previous_turn = turn
+
+    payload = {
+        "source": source,
+        "session_id": _session_id_for_path(path, source),
+        "path": str(path),
+        "size_kb": size_kb,
+        "total_turns": len(turns),
+        "turns": turn_records,
+    }
+    return json.dumps(payload, indent=2)
+
+
+def _session_id_for_path(path: Path, source: str) -> str:
+    """Return the source-specific session id for a session file."""
+    if source == "codex":
+        return codex._session_id_from_path(path)
+    return path.stem
+
+
 def main(argv: list[str] | None = None) -> int:
     """Run the agent-chat-reader command-line interface."""
     p = argparse.ArgumentParser(
@@ -193,6 +248,25 @@ def main(argv: list[str] | None = None) -> int:
         action="store_true",
         help="Include guardian/subagent sessions",
     )
+    p.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format for session reads (default: text)",
+    )
+    p.add_argument(
+        "--show-timestamps",
+        action="store_true",
+        dest="show_timestamps",
+        default=True,
+        help="Show message timestamps and elapsed gaps in session reads",
+    )
+    p.add_argument(
+        "--hide-timestamps",
+        action="store_false",
+        dest="show_timestamps",
+        help="Hide message timestamps and elapsed gaps in session reads",
+    )
     p.add_argument(
         "--limit",
         type=int,
@@ -220,6 +294,8 @@ def main(argv: list[str] | None = None) -> int:
             verbose=args.verbose,
             include_subagents=args.include_subagents,
             tail=args.tail,
+            show_timestamps=args.show_timestamps,
+            output_format=args.format,
         )
 
     p.print_help()

{agent_chat_reader-0.1.3 → agent_chat_reader-0.1.4}/src/agent_chat_reader/output.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import textwrap
-from datetime import datetime
+from datetime import datetime, timedelta
 
 from agent_chat_reader.models import SessionMeta, Turn
 
@@ -18,11 +18,62 @@ def fmt_ts(ts_str: str) -> str:
     """Format an ISO timestamp to a short local time string."""
     if not ts_str:
         return ""
-    try:
-        dt = datetime.fromisoformat(ts_str.replace("Z", "+00:00"))
+    dt = _parse_ts(ts_str)
+    if dt is not None:
         return dt.astimezone().strftime("%Y-%m-%d %H:%M")
+    return ts_str[:16]
+
+
+def _parse_ts(ts_str: str) -> datetime | None:
+    """Parse an ISO timestamp, returning None for non-ISO placeholders."""
+    try:
+        return datetime.fromisoformat(ts_str.replace("Z", "+00:00"))
     except ValueError:
-        return ts_str[:16]
+        return None
+
+
+def fmt_elapsed(delta: timedelta) -> str:
+    """Format an elapsed duration compactly."""
+    seconds = max(0, int(delta.total_seconds()))
+    if seconds < 60:
+        return f"{seconds}s"
+    minutes = seconds // 60
+    if minutes < 60:
+        return f"{minutes}m"
+    hours = minutes // 60
+    minutes %= 60
+    if hours < 24:
+        return f"{hours}h {minutes}m" if minutes else f"{hours}h"
+    days = hours // 24
+    hours %= 24
+    return f"{days}d {hours}h" if hours else f"{days}d"
+
+
+def elapsed_seconds_between(previous_turn: Turn, turn: Turn) -> int | None:
+    """Return elapsed seconds between two turns, if both timestamps parse."""
+    current_dt = _parse_ts(turn.timestamp)
+    previous_dt = _parse_ts(previous_turn.timestamp)
+    if current_dt is None or previous_dt is None:
+        return None
+    return max(0, int((current_dt - previous_dt).total_seconds()))
+
+
+def _timestamp_suffix(turn: Turn, previous_turn: Turn | None) -> str:
+    """Return the optional timestamp/gap suffix for a turn header."""
+    timestamp = fmt_ts(turn.timestamp)
+    if not timestamp:
+        return ""
+
+    if previous_turn is None:
+        return f"  {timestamp}"
+
+    elapsed_seconds = elapsed_seconds_between(previous_turn, turn)
+    if elapsed_seconds is None:
+        return f"  {timestamp}"
+
+    elapsed = fmt_elapsed(timedelta(seconds=elapsed_seconds))
+    role = turn.role.lower()
+    return f"  {timestamp}  ({role} took {elapsed})"
 
 
 def fmt_mtime(mtime: float) -> str:
@@ -30,9 +81,14 @@ def fmt_mtime(mtime: float) -> str:
     return datetime.fromtimestamp(mtime).strftime("%Y-%m-%d %H:%M")  # noqa: DTZ006
 
 
-def print_turn(turn: Turn) -> None:
+def print_turn(
+    turn: Turn,
+    *,
+    show_timestamps: bool = True,
+    previous_turn: Turn | None = None,
+) -> None:
     """Print a single conversation turn with a header rule."""
-    ts_str = f"  {fmt_ts(turn.timestamp)}" if turn.timestamp else ""
+    ts_str = _timestamp_suffix(turn, previous_turn) if show_timestamps else ""
     print(f"\n{'─' * 60}")
     print(f"[{turn.role}]{ts_str}")
     print("─" * 60)

{agent_chat_reader-0.1.3 → agent_chat_reader-0.1.4}/tests/test_package.py

@@ -9,9 +9,10 @@ import pytest
 
 import agent_chat_reader
 from agent_chat_reader.claude import _extract_user_text
-from agent_chat_reader.cli import main
+from agent_chat_reader.cli import _json_session, main
 from agent_chat_reader.codex import _apply_tail, _session_id_from_path, read_turns
 from agent_chat_reader.models import Turn
+from agent_chat_reader.output import elapsed_seconds_between, fmt_elapsed, print_turn
 
 # ── Version ───────────────────────────────────────────────────────────────────
 
@@ -154,6 +155,92 @@ def test_apply_tail_none_returns_all() -> None:
     assert _apply_tail(turns, tail=None) == turns
 
 
+# ── Output formatting ────────────────────────────────────────────────────────
+
+
+def test_print_turn_shows_timestamp_by_default(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """The default transcript view includes timing context."""
+    print_turn(Turn("USER", "hello", "2026-01-01T12:00:00Z"))
+    out = capsys.readouterr().out
+    assert "[USER]" in out
+    assert "2026-01" in out
+
+
+def test_print_turn_can_hide_timestamp(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Timestamp display can be disabled for quieter transcript reads."""
+    print_turn(
+        Turn("USER", "hello", "2026-01-01T00:00:00Z"),
+        show_timestamps=False,
+    )
+    out = capsys.readouterr().out
+    assert "[USER]" in out
+    assert "2026-01" not in out
+
+
+def test_print_turn_can_show_agent_elapsed_time(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Timestamp mode shows elapsed time for the current speaker."""
+    previous_turn = Turn("USER", "hello", "2026-01-01T00:00:00Z")
+    print_turn(
+        Turn("AGENT", "hi", "2026-01-01T00:02:05Z"),
+        show_timestamps=True,
+        previous_turn=previous_turn,
+    )
+    out = capsys.readouterr().out
+    assert "[AGENT]" in out
+    assert "(agent took 2m)" in out
+
+
+def test_print_turn_can_show_user_elapsed_time(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """User messages show elapsed time without inferring idle state."""
+    previous_turn = Turn("AGENT", "question?", "2026-01-01T00:00:00Z")
+    print_turn(
+        Turn("USER", "answer", "2026-01-01T00:30:00Z"),
+        show_timestamps=True,
+        previous_turn=previous_turn,
+    )
+    assert "(user took 30m)" in capsys.readouterr().out
+
+
+def test_fmt_elapsed_handles_long_gaps() -> None:
+    """Elapsed durations stay compact for long sessions."""
+    from datetime import timedelta
+
+    assert fmt_elapsed(timedelta(days=1, hours=2, minutes=3)) == "1d 2h"
+
+
+def test_elapsed_seconds_between_returns_machine_readable_gap() -> None:
+    """Elapsed gap calculations are available without parsing display text."""
+    previous_turn = Turn("USER", "hello", "2026-01-01T00:00:00Z")
+    turn = Turn("AGENT", "hi", "2026-01-01T00:02:05Z")
+    assert elapsed_seconds_between(previous_turn, turn) == 125
+
+
+def test_json_session_includes_structured_timing_fields(tmp_path: Path) -> None:
+    """JSON output exposes stable fields for agents and scripts."""
+    session = tmp_path / _SESSION_FILE
+    turns = [
+        Turn("USER", "hello", "2026-01-01T00:00:00Z"),
+        Turn("AGENT", "hi", "2026-01-01T00:02:05Z"),
+    ]
+    payload = json.loads(
+        _json_session(source="codex", path=session, size_kb=12, turns=turns)
+    )
+    assert payload["source"] == "codex"
+    assert payload["size_kb"] == 12
+    assert payload["total_turns"] == 2
+    assert payload["turns"][0]["elapsed_seconds"] is None
+    assert payload["turns"][1]["elapsed_seconds"] == 125
+    assert payload["turns"][1]["text"] == "hi"
+
+
 # ── Claude parsing ────────────────────────────────────────────────────────────
 
 

{agent_chat_reader-0.1.3 → agent_chat_reader-0.1.4}/uv.lock

@@ -8,7 +8,7 @@ resolution-markers = [
 
 [[package]]
 name = "agent-chat-reader"
-version = "0.1.3"
+version = "0.1.4"
 source = { editable = "." }
 
 [package.optional-dependencies]