session-saloon 0.1.0__tar.gz

session_saloon-0.1.0/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Session Saloon contributors
+
+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.
+
+The bundled fonts (Press Start 2P, VT323) are licensed under the SIL Open Font
+License 1.1; see src/session_saloon/static/fonts/OFL-*.txt.

session_saloon-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: session-saloon
+Version: 0.1.0
+Summary: A local, live dashboard that shows your Claude Code sessions as customers at a saloon bar.
+License: MIT
+Keywords: claude,claude-code,dashboard,sessions
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Environment :: Console
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# Session Saloon
+
+A local, live dashboard for people who run many Claude Code (and Codex CLI) sessions at once. Every session is a
+pixel-art customer at a saloon bar. Customers whose turn is running stand near the door, drinking.
+Customers waiting for **you** walk down the bar toward the barman (that is you), and the longer they
+wait, the closer they get. Below the bar, **The Tab** lists the same sessions with numbers and a
+copy-to-clipboard resume command.
+
+It answers one question at a glance: **which of my Claude sessions is waiting on me, and for how long?**
+
+![Session Saloon running on the built-in demo data](docs/screenshots/demo.jpg)
+
+*The screenshot is `saloon --demo`: synthetic sessions, nothing real.*
+
+## Install and run
+
+```
+pipx install session-saloon      # or: uvx session-saloon
+saloon                           # serves on http://127.0.0.1:7317 and opens your browser
+```
+
+Python 3.9 or newer, no runtime dependencies. Running `saloon` a second time just opens the browser on
+the instance that is already running.
+
+```
+saloon --hours 24               # time window (default 72, 0 = no limit)
+saloon --port 7400
+saloon --no-open
+saloon --dump                   # print the snapshot as JSON and exit
+saloon --projects-dir PATH      # Claude Code: default ~/.claude/projects (or $CLAUDE_CONFIG_DIR/projects)
+saloon --codex-dir PATH         # Codex CLI home: default $CODEX_HOME or ~/.codex (reads its sessions/ folder)
+saloon --only claude            # or --only codex: show one agent's sessions only
+saloon --demo                   # synthetic, animated data that shows every state
+saloon --version
+```
+
+**Double-click launchers.** Windows: `launchers/saloon.cmd` (put a shortcut to it in
+`%APPDATA%\Microsoft\Windows\Start Menu\Programs`, or pin it to the taskbar). macOS: run
+`pipx install session-saloon`, then drag a small Automator "Run Shell Script" app that runs `saloon`
+into the Dock. Linux: add a `.desktop` file whose `Exec=` is `saloon`.
+
+**Start at login.** Windows: put a shortcut to `saloon.cmd` (or to `saloon --no-open`) in
+`shell:startup`. macOS: add a Login Item that runs `saloon --no-open`, or a LaunchAgent with
+`ProgramArguments = [saloon, --no-open]`. Linux: a systemd user service with
+`ExecStart=%h/.local/bin/saloon --no-open`. Then pin `http://127.0.0.1:7317/` as a browser tab; the tab
+title shows `(3) Session Saloon` when three sessions wait on you.
+
+## Reading the bar
+
+| You see | It means |
+|---|---|
+| Near the door, drinking | Claude is working on that turn |
+| Walking toward the barman | The turn ended and the session waits on you; the closer, the longer |
+| Red `!` bubble, frown | Waiting 20 minutes or more (*late*) |
+| `z z z`, dimmed | Waiting more than 2 hours (*dozing*); not counted in "waiting on you" |
+| Head on the bar, `...18m` | Mid-turn but no transcript writes for 15 minutes (*stalled*): process gone, or stuck on a permission prompt |
+| Top hat / crown / cap / beanie | Opus / Fable / Sonnet / Haiku |
+| Robot | A headless (`sdk-cli`) session; it never waits on a human |
+| Gold coins on the counter | Pull requests the session opened |
+| Small mates | Its subagents (bright and bouncing while live) |
+
+Hover a customer for details; click to pin it (its row in The Tab lights up); **double-click to serve**
+it, which closes the session on the bar until you prompt it again. The same actions are in The Tab
+(`SERVE` / `REOPEN`, `COPY`), reachable by keyboard.
+
+## Claude Code and Codex
+
+Both agents drink at the same bar. Codex sessions are tagged `codex` on The Tab, show the agent in the
+hover card, and `COPY` gives `codex resume <id>` instead of `claude --resume <id>`.
+
+| | Claude Code | Codex CLI |
+|---|---|---|
+| Transcripts | `~/.claude/projects/<project>/<id>.jsonl` | `~/.codex/sessions/YYYY/MM/DD/rollout-<time>-<id>.jsonl` |
+| Turn finished | `turn_duration` marker (sometimes late, so a quiet text-only reply also counts) | `task_complete` (explicit, no quiet rule needed) |
+| Interrupted | `[Request interrupted` text | `turn_aborted` |
+| Your prompt | `user` line, minus injected reminders | completed `UserMessage` item |
+| Subagents | files under `<id>/subagents/` | separate rollouts naming their parent; shown as small mates of the parent |
+| Headless | `entrypoint: sdk-cli` | `codex exec`, MCP server and internal reviewers (the guardian) |
+
+If a source folder does not exist it is skipped silently, so having only one of the two is fine.
+`sources = ["claude"]` in the config file turns one off permanently.
+
+## Configuration
+
+Click the gear in the page, or edit the file:
+
+* Linux/macOS: `~/.config/session-saloon/config.toml`
+* Windows: `%APPDATA%\session-saloon\config.toml`
+
+On Python 3.11+ this file is TOML, read with the standard library's `tomllib`. On Python 3.9
+or 3.10 (no `tomllib`), write the same settings as JSON instead — the keys and nesting are
+identical, just JSON syntax (`{"hours": 72, "thresholds": {...}, ...}`); a TOML-formatted file
+is silently ignored on those versions rather than applied. The settings panel writes whichever
+format your interpreter can read, so this only matters if you edit the file by hand.
+
+```toml
+hours = 72
+shell = "auto"                # resume command flavour: auto | powershell | posix
+sources = ["claude", "codex"]
+
+[thresholds]                   # seconds
+quiet_end = 180                # text-only reply + this much quiet = waiting
+stall_after = 900              # mid-turn + this much quiet = stalled
+late_after = 1200
+doze_after = 7200
+subagent_live = 120
+
+[projects.alias]
+"pillar2-main" = "Pillar2"     # rename, or map several folders to one lane
+```
+
+Command-line flags override the file. Served marks live in your data directory
+(`%LOCALAPPDATA%\session-saloon\served.json`, `~/.local/share/session-saloon/served.json`,
+`~/Library/Application Support/session-saloon/served.json`).
+
+## How states are decided
+
+| State | Rule |
+|---|---|
+| `waiting` | The last event is a finished turn or an interrupt, or it is a text-only reply and the transcript has been quiet for more than `quiet_end` |
+| `working` | Otherwise |
+| `stalled` | Mid-turn and quiet for more than `stall_after` (a live subagent counts as activity) |
+| `done` | Served by you and not prompted since; or a headless session that finished or went quiet |
+
+The transcript formats are not public contracts. All knowledge of them lives in
+`src/session_saloon/transcript.py` (Claude Code) and `codex.py` (Codex); unknown fields and malformed
+lines are tolerated. The page also has a size setting (small by default, or normal) in the gear panel.
+
+## Themes
+
+The stage is skinnable: **Saloon** (default) and **Tiki Isle**, picked in the gear panel. A theme is
+one self-contained object in `static/index.html` (palette + copy + a handful of drawing hooks) — see
+`docs/decisions.md` for the interface and, notably, the reasoning for why "Tiki Isle" is its own
+original design rather than a licensed-character reskin. See
+[docs/decisions.md](docs/decisions.md) for the interpretations made along the way.
+
+## Privacy
+
+* Runs on your machine only. The server binds to `127.0.0.1`, never sends anything off the machine,
+  and has no telemetry. The page loads no third-party resources (fonts are bundled).
+* Read-only toward Claude Code: it reads the transcripts Claude Code already writes and never modifies
+  them. The only thing it writes is the list of sessions you marked as served.
+* `POST` endpoints only accept `application/json` (so browsers must preflight, which the server never
+  answers), a loopback `Host` header (DNS-rebinding protection), a 4 KB body and strict ids.
+* Session titles and prompts are rendered with `textContent`, never `innerHTML`.
+
+## Development
+
+```
+pip install -e .[dev]
+pytest
+python tests/fixture_builders.py     # regenerate tests/fixtures (synthetic transcripts)
+saloon --dump --projects-dir tests/fixtures/projects --hours 0 --now 1790596800
+```
+
+MIT licensed. Fonts: Press Start 2P and VT323, SIL Open Font License.
+
+### Releasing (maintainers)
+
+Publishing to PyPI uses [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC) —
+no API token is stored as a repo secret. One-time setup on the PyPI project's *Publishing* page:
+add a GitHub publisher for `wasigh/session-saloon`, workflow `release.yml`, environment `pypi`.
+
+To ship a release: bump `version` in `pyproject.toml`, then
+
+```
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+`.github/workflows/release.yml` builds the package, runs the test matrix, and publishes on a
+green run. `.github/workflows/ci.yml` runs the same tests on every push and pull request.

session_saloon-0.1.0/README.md

@@ -0,0 +1,172 @@
+# Session Saloon
+
+A local, live dashboard for people who run many Claude Code (and Codex CLI) sessions at once. Every session is a
+pixel-art customer at a saloon bar. Customers whose turn is running stand near the door, drinking.
+Customers waiting for **you** walk down the bar toward the barman (that is you), and the longer they
+wait, the closer they get. Below the bar, **The Tab** lists the same sessions with numbers and a
+copy-to-clipboard resume command.
+
+It answers one question at a glance: **which of my Claude sessions is waiting on me, and for how long?**
+
+![Session Saloon running on the built-in demo data](docs/screenshots/demo.jpg)
+
+*The screenshot is `saloon --demo`: synthetic sessions, nothing real.*
+
+## Install and run
+
+```
+pipx install session-saloon      # or: uvx session-saloon
+saloon                           # serves on http://127.0.0.1:7317 and opens your browser
+```
+
+Python 3.9 or newer, no runtime dependencies. Running `saloon` a second time just opens the browser on
+the instance that is already running.
+
+```
+saloon --hours 24               # time window (default 72, 0 = no limit)
+saloon --port 7400
+saloon --no-open
+saloon --dump                   # print the snapshot as JSON and exit
+saloon --projects-dir PATH      # Claude Code: default ~/.claude/projects (or $CLAUDE_CONFIG_DIR/projects)
+saloon --codex-dir PATH         # Codex CLI home: default $CODEX_HOME or ~/.codex (reads its sessions/ folder)
+saloon --only claude            # or --only codex: show one agent's sessions only
+saloon --demo                   # synthetic, animated data that shows every state
+saloon --version
+```
+
+**Double-click launchers.** Windows: `launchers/saloon.cmd` (put a shortcut to it in
+`%APPDATA%\Microsoft\Windows\Start Menu\Programs`, or pin it to the taskbar). macOS: run
+`pipx install session-saloon`, then drag a small Automator "Run Shell Script" app that runs `saloon`
+into the Dock. Linux: add a `.desktop` file whose `Exec=` is `saloon`.
+
+**Start at login.** Windows: put a shortcut to `saloon.cmd` (or to `saloon --no-open`) in
+`shell:startup`. macOS: add a Login Item that runs `saloon --no-open`, or a LaunchAgent with
+`ProgramArguments = [saloon, --no-open]`. Linux: a systemd user service with
+`ExecStart=%h/.local/bin/saloon --no-open`. Then pin `http://127.0.0.1:7317/` as a browser tab; the tab
+title shows `(3) Session Saloon` when three sessions wait on you.
+
+## Reading the bar
+
+| You see | It means |
+|---|---|
+| Near the door, drinking | Claude is working on that turn |
+| Walking toward the barman | The turn ended and the session waits on you; the closer, the longer |
+| Red `!` bubble, frown | Waiting 20 minutes or more (*late*) |
+| `z z z`, dimmed | Waiting more than 2 hours (*dozing*); not counted in "waiting on you" |
+| Head on the bar, `...18m` | Mid-turn but no transcript writes for 15 minutes (*stalled*): process gone, or stuck on a permission prompt |
+| Top hat / crown / cap / beanie | Opus / Fable / Sonnet / Haiku |
+| Robot | A headless (`sdk-cli`) session; it never waits on a human |
+| Gold coins on the counter | Pull requests the session opened |
+| Small mates | Its subagents (bright and bouncing while live) |
+
+Hover a customer for details; click to pin it (its row in The Tab lights up); **double-click to serve**
+it, which closes the session on the bar until you prompt it again. The same actions are in The Tab
+(`SERVE` / `REOPEN`, `COPY`), reachable by keyboard.
+
+## Claude Code and Codex
+
+Both agents drink at the same bar. Codex sessions are tagged `codex` on The Tab, show the agent in the
+hover card, and `COPY` gives `codex resume <id>` instead of `claude --resume <id>`.
+
+| | Claude Code | Codex CLI |
+|---|---|---|
+| Transcripts | `~/.claude/projects/<project>/<id>.jsonl` | `~/.codex/sessions/YYYY/MM/DD/rollout-<time>-<id>.jsonl` |
+| Turn finished | `turn_duration` marker (sometimes late, so a quiet text-only reply also counts) | `task_complete` (explicit, no quiet rule needed) |
+| Interrupted | `[Request interrupted` text | `turn_aborted` |
+| Your prompt | `user` line, minus injected reminders | completed `UserMessage` item |
+| Subagents | files under `<id>/subagents/` | separate rollouts naming their parent; shown as small mates of the parent |
+| Headless | `entrypoint: sdk-cli` | `codex exec`, MCP server and internal reviewers (the guardian) |
+
+If a source folder does not exist it is skipped silently, so having only one of the two is fine.
+`sources = ["claude"]` in the config file turns one off permanently.
+
+## Configuration
+
+Click the gear in the page, or edit the file:
+
+* Linux/macOS: `~/.config/session-saloon/config.toml`
+* Windows: `%APPDATA%\session-saloon\config.toml`
+
+On Python 3.11+ this file is TOML, read with the standard library's `tomllib`. On Python 3.9
+or 3.10 (no `tomllib`), write the same settings as JSON instead — the keys and nesting are
+identical, just JSON syntax (`{"hours": 72, "thresholds": {...}, ...}`); a TOML-formatted file
+is silently ignored on those versions rather than applied. The settings panel writes whichever
+format your interpreter can read, so this only matters if you edit the file by hand.
+
+```toml
+hours = 72
+shell = "auto"                # resume command flavour: auto | powershell | posix
+sources = ["claude", "codex"]
+
+[thresholds]                   # seconds
+quiet_end = 180                # text-only reply + this much quiet = waiting
+stall_after = 900              # mid-turn + this much quiet = stalled
+late_after = 1200
+doze_after = 7200
+subagent_live = 120
+
+[projects.alias]
+"pillar2-main" = "Pillar2"     # rename, or map several folders to one lane
+```
+
+Command-line flags override the file. Served marks live in your data directory
+(`%LOCALAPPDATA%\session-saloon\served.json`, `~/.local/share/session-saloon/served.json`,
+`~/Library/Application Support/session-saloon/served.json`).
+
+## How states are decided
+
+| State | Rule |
+|---|---|
+| `waiting` | The last event is a finished turn or an interrupt, or it is a text-only reply and the transcript has been quiet for more than `quiet_end` |
+| `working` | Otherwise |
+| `stalled` | Mid-turn and quiet for more than `stall_after` (a live subagent counts as activity) |
+| `done` | Served by you and not prompted since; or a headless session that finished or went quiet |
+
+The transcript formats are not public contracts. All knowledge of them lives in
+`src/session_saloon/transcript.py` (Claude Code) and `codex.py` (Codex); unknown fields and malformed
+lines are tolerated. The page also has a size setting (small by default, or normal) in the gear panel.
+
+## Themes
+
+The stage is skinnable: **Saloon** (default) and **Tiki Isle**, picked in the gear panel. A theme is
+one self-contained object in `static/index.html` (palette + copy + a handful of drawing hooks) — see
+`docs/decisions.md` for the interface and, notably, the reasoning for why "Tiki Isle" is its own
+original design rather than a licensed-character reskin. See
+[docs/decisions.md](docs/decisions.md) for the interpretations made along the way.
+
+## Privacy
+
+* Runs on your machine only. The server binds to `127.0.0.1`, never sends anything off the machine,
+  and has no telemetry. The page loads no third-party resources (fonts are bundled).
+* Read-only toward Claude Code: it reads the transcripts Claude Code already writes and never modifies
+  them. The only thing it writes is the list of sessions you marked as served.
+* `POST` endpoints only accept `application/json` (so browsers must preflight, which the server never
+  answers), a loopback `Host` header (DNS-rebinding protection), a 4 KB body and strict ids.
+* Session titles and prompts are rendered with `textContent`, never `innerHTML`.
+
+## Development
+
+```
+pip install -e .[dev]
+pytest
+python tests/fixture_builders.py     # regenerate tests/fixtures (synthetic transcripts)
+saloon --dump --projects-dir tests/fixtures/projects --hours 0 --now 1790596800
+```
+
+MIT licensed. Fonts: Press Start 2P and VT323, SIL Open Font License.
+
+### Releasing (maintainers)
+
+Publishing to PyPI uses [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC) —
+no API token is stored as a repo secret. One-time setup on the PyPI project's *Publishing* page:
+add a GitHub publisher for `wasigh/session-saloon`, workflow `release.yml`, environment `pypi`.
+
+To ship a release: bump `version` in `pyproject.toml`, then
+
+```
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+`.github/workflows/release.yml` builds the package, runs the test matrix, and publishes on a
+green run. `.github/workflows/ci.yml` runs the same tests on every push and pull request.

session_saloon-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "session-saloon"
+version = "0.1.0"
+description = "A local, live dashboard that shows your Claude Code sessions as customers at a saloon bar."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+dependencies = []
+keywords = ["claude", "claude-code", "dashboard", "sessions"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Environment :: Console",
+  "Topic :: Utilities",
+]
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.scripts]
+saloon = "session_saloon.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+session_saloon = ["static/*.html", "static/fonts/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

session_saloon-0.1.0/setup.cfg

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

session_saloon-0.1.0/src/session_saloon/__init__.py

@@ -0,0 +1,3 @@
+"""Session Saloon: a local, live dashboard for Claude Code sessions."""
+
+__version__ = "0.1.0"

session_saloon-0.1.0/src/session_saloon/__main__.py

@@ -0,0 +1,103 @@
+"""Command-line entry point: ``saloon``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from . import __version__
+from .config import Config, config_path, load_config, resolve_codex_dir, resolve_projects_dir, served_path
+from .server import App, SaloonServer, open_browser, probe_existing
+from .tracker import ServedStore, Tracker
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="saloon",
+        description="A local, live dashboard that shows your Claude Code sessions as customers at a saloon bar.",
+    )
+    p.add_argument("--hours", type=float, help="time window in hours (default 72; 0 = no limit)")
+    p.add_argument("--port", type=int, help="port to serve on (default 7317)")
+    p.add_argument("--no-open", action="store_true", help="do not open the browser")
+    p.add_argument("--dump", action="store_true", help="print the snapshot as JSON and exit")
+    p.add_argument("--projects-dir", metavar="PATH", help="transcript root (default: ~/.claude/projects, or $CLAUDE_CONFIG_DIR/projects)")
+    p.add_argument("--codex-dir", metavar="PATH", help="Codex home (default: $CODEX_HOME or ~/.codex); sessions live in its sessions/ folder")
+    p.add_argument("--only", choices=["claude", "codex"], help="show only one agent's sessions")
+    p.add_argument("--demo", action="store_true", help="serve a synthetic, animated snapshot instead of real sessions")
+    p.add_argument("--config", metavar="FILE", help=f"config file (default: {config_path()})")
+    p.add_argument("--now", type=float, help=argparse.SUPPRESS)  # debugging aid: pretend it is this unix time (with --dump)
+    p.add_argument("--version", action="version", version=f"session-saloon {__version__}")
+    return p
+
+
+def config_from_args(args: argparse.Namespace) -> Config:
+    cfg = load_config(Path(args.config) if args.config else None)
+    if args.hours is not None:
+        cfg.hours = args.hours
+    if args.port is not None:
+        cfg.port = args.port
+    if args.projects_dir:
+        cfg.projects_dir = args.projects_dir
+    if args.codex_dir:
+        cfg.codex_dir = args.codex_dir
+    if args.only:
+        cfg.sources = [args.only]
+    return cfg
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    cfg = config_from_args(args)
+    if not 1 <= cfg.port <= 65535:
+        print(f"saloon: invalid port {cfg.port}", file=sys.stderr)
+        return 2
+
+    if args.dump:
+        tracker = Tracker(cfg, ServedStore(served_path()))
+        print(json.dumps(tracker.snapshot(args.now), indent=2))
+        return 0
+
+    if args.demo:
+        from .demo import make_demo
+
+        app = App(cfg, demo=make_demo(), served=ServedStore(None), persist_config=False)
+    else:
+        roots = []
+        if "claude" in cfg.sources:
+            roots.append(resolve_projects_dir(cfg))
+        if "codex" in cfg.sources:
+            roots.append(resolve_codex_dir(cfg) / "sessions")
+        if not any(r.is_dir() for r in roots):
+            where = " or ".join(str(r) for r in roots)
+            print(f"saloon: no transcripts found at {where} (use --projects-dir / --codex-dir, or start a session first)", file=sys.stderr)
+        app = App(cfg, tracker=Tracker(cfg, ServedStore(served_path())))
+
+    try:
+        server = SaloonServer(cfg.port, app)
+    except OSError:
+        if probe_existing(cfg.port):
+            print(f"Session Saloon is already open on http://127.0.0.1:{cfg.port}/")
+            if not args.no_open:
+                open_browser(cfg.port)
+            return 0
+        print(f"saloon: port {cfg.port} is in use by something else (try --port)", file=sys.stderr)
+        return 1
+
+    url = f"http://127.0.0.1:{cfg.port}/"
+    print(f"Session Saloon is open at {url}  (Ctrl+C to close the bar)")
+    if not args.no_open:
+        open_browser(cfg.port)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

session_saloon-0.1.0/src/session_saloon/codex.py

@@ -0,0 +1,130 @@
+"""All knowledge of the Codex CLI rollout format lives here.
+
+Codex writes ``~/.codex/sessions/YYYY/MM/DD/rollout-<time>-<uuid>.jsonl``. Each line is
+``{"timestamp", "type", "payload"}``. Unlike Claude Code, turn boundaries are explicit
+(``task_started`` / ``task_complete`` / ``turn_aborted``), so no "quiet" heuristic is needed
+to detect a finished turn. Like the Claude side, this is not a public contract: unknown
+fields and lines are ignored.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Optional, Sequence
+
+from . import transcript as tr
+
+WORK_ITEMS = {
+    "function_call", "function_call_output", "custom_tool_call", "custom_tool_call_output",
+    "local_shell_call", "web_search_call", "tool_search_call", "reasoning",
+}
+TOOL_CALLS = {"function_call", "custom_tool_call", "local_shell_call", "web_search_call", "tool_search_call"}
+HEADLESS_SOURCES = {"exec", "mcp"}  # `codex exec` and the MCP server run without a person at the keyboard
+
+
+def clean_cwd(cwd: Any) -> Optional[str]:
+    if not isinstance(cwd, str) or not cwd:
+        return None
+    return cwd[4:] if cwd.startswith("\\\\?\\") else cwd  # Windows extended-length prefix
+
+
+def parse_line(raw: str, markers: Sequence[str] = ()) -> Optional[tr.Record]:
+    raw = raw.strip()
+    if not raw:
+        return None
+    try:
+        obj = json.loads(raw)
+    except ValueError:
+        return None
+    if not isinstance(obj, dict):
+        return None
+    return parse_object(obj)
+
+
+def parse_object(obj: Dict[str, Any]) -> tr.Record:
+    rec = tr.Record()
+    rec.ts = tr.parse_timestamp(obj.get("timestamp"))
+    payload = obj.get("payload")
+    p: Dict[str, Any] = payload if isinstance(payload, dict) else {}
+    kind = obj.get("type")
+    ptype = p.get("type")
+
+    if kind == "session_meta":
+        rec.cwd = clean_cwd(p.get("cwd"))
+        git = p.get("git")
+        if isinstance(git, dict) and isinstance(git.get("branch"), str):
+            rec.branch = git["branch"]
+        _parse_source(p, rec)
+    elif kind == "turn_context":
+        rec.cwd = clean_cwd(p.get("cwd"))
+        model = p.get("model")
+        if isinstance(model, str) and model:
+            rec.model = model
+    elif kind == "compacted":
+        rec.kind = tr.COMPACT
+    elif kind == "event_msg":
+        _parse_event(p, ptype, rec)
+    elif kind == "response_item":
+        _parse_item(p, ptype, rec)
+    return rec
+
+
+def _parse_source(p: Dict[str, Any], rec: tr.Record) -> None:
+    source = p.get("source")
+    if isinstance(source, str):
+        if source in HEADLESS_SOURCES or p.get("originator") == "codex_exec":
+            rec.headless = True
+        return
+    if isinstance(source, dict) and isinstance(source.get("subagent"), dict):
+        spawn = source["subagent"].get("thread_spawn")
+        parent = spawn.get("parent_thread_id") if isinstance(spawn, dict) else None
+        if isinstance(parent, str) and parent:
+            rec.parent = parent  # a helper thread of another session: shown as a "mate" of it
+        else:
+            rec.headless = True  # e.g. the guardian reviewer: an automation
+
+
+def _parse_event(p: Dict[str, Any], ptype: Any, rec: tr.Record) -> None:
+    if ptype == "task_started":
+        rec.kind = tr.WORK
+    elif ptype == "user_message":
+        text = p.get("message")
+        if isinstance(text, str) and text.strip():
+            rec.kind = tr.PROMPT
+            rec.text = text.strip()[: tr.PROMPT_TEXT_LIMIT]
+    elif ptype == "task_complete":
+        rec.kind = tr.END
+    elif ptype == "turn_aborted":
+        rec.kind = tr.INTERRUPT
+    elif ptype == "token_count":
+        info = p.get("info")
+        usage = info.get("total_token_usage") if isinstance(info, dict) else None
+        out = usage.get("output_tokens") if isinstance(usage, dict) else None
+        if isinstance(out, (int, float)) and not isinstance(out, bool) and out >= 0:
+            rec.out_tokens_total = int(out)
+    elif ptype == "item_completed":
+        # Interactive sessions record what the person typed as a completed UserMessage item.
+        item = p.get("item")
+        if isinstance(item, dict) and item.get("type") == "UserMessage":
+            text = _item_text(item.get("content"))
+            if text:
+                rec.kind = tr.PROMPT
+                rec.text = text[: tr.PROMPT_TEXT_LIMIT]
+    # agent_message, thread_settings_applied, other items: they trail the turn markers, so
+    # they must not flip a finished turn back to "working".
+
+
+def _item_text(content: Any) -> str:
+    if isinstance(content, str):
+        return content.strip()
+    if not isinstance(content, list):
+        return ""
+    parts = [b.get("text", "") for b in content if isinstance(b, dict) and b.get("type") == "text" and isinstance(b.get("text"), str)]
+    return "\n".join(parts).strip()
+
+
+def _parse_item(p: Dict[str, Any], ptype: Any, rec: tr.Record) -> None:
+    if ptype in WORK_ITEMS or (ptype == "message" and p.get("role") == "assistant"):
+        rec.kind = tr.WORK
+        if ptype in TOOL_CALLS:
+            rec.tool_calls = 1