sessionview 0.1.0__tar.gz → 0.3.0__tar.gz

sessionview-0.1.0/README.md → sessionview-0.3.0/PKG-INFO

@@ -1,29 +1,43 @@
-# Herd
+Metadata-Version: 2.5
+Name: sessionview
+Version: 0.3.0
+Summary: A sidebar for tmux: your projects (sessions) and your agents, here and on remote hosts.
+Project-URL: Homepage, https://github.com/sessionkit/sessionview
+Project-URL: Repository, https://github.com/sessionkit/sessionview
+Author-email: Mike Bailey <mike@sessionkit.ai>
+License-Expression: AGPL-3.0-or-later
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Terminals :: Terminal Emulators/X Terminals
+Requires-Python: <3.15,>=3.11
+Description-Content-Type: text/markdown
+
+# sessionview
 
 A sidebar for tmux, in the spirit of herdr: your projects (tmux sessions)
 and your agents (seats), here and on remote hosts, one click away, with a
 right-click menu built from what is installed. Session's TUI — a
 controller and view for the `session` tools, drawn beside tmux.
 
-`sessionview` 0.0.1 on PyPI reserves the name; the tool follows (Mike, approved by mail 00:25 Thu 2026-09-10).
-
+Install from PyPI: `uv tool install sessionview` (see [Install](#install)).
 
     sessionview [SESSION]            # in this terminal: sidebar left, SESSION attached
                                      # right (a private outer tmux holds the two panes)
     prefix H                         # the same sidebar as a popup in any tmux client
 
-Read [SPEC.md](SPEC.md) first: what Herd is, the rules of the view, the
-contract with `session`, the plugin manifest, config, measured limits.
-This repo is the **reference implementation** (Mike, 18:23 Sun
-2026-09-06: "a working reference implementation ... it can be a life
-raft") — session integrates from the spec; this stays comparable and
-runnable.
+Read [SPEC.md](SPEC.md) first: what sessionview is, the rules of the view, the
+contract with `session`, the plugin manifest, config, known limits.
+This repo is the **reference implementation**: session integrates from
+the spec; this stays comparable and runnable.
 
 ## Requirements
 
 Each line is measured against the code, not remembered;
-`bin/sessionview-install --check` checks tmux, Python and `session`
-on your machine.
+`bin/sessionview-install --check` checks tmux, Python, `session`,
+neomutt and notmuch's index on your machine.
 
 - **Claude Code, and the plugin is the install.** The `sessionview`
   wheel is an empty package (one `__init__.py`, no `[project.scripts]`);
@@ -36,13 +50,26 @@ on your machine.
   the frame are plain tmux + Python and should run on Linux, untested.
 - **tmux >= 3.7** (measured on 3.7c: `join-pane -l`, `focus-events`,
   status ranges). An older tmux satisfies `brew install tmux` silently.
-- **Python >= 3.11**, standard library only (`requires-python` in
-  `pyproject.toml`; the sidebar and the config tools).
+- **Python 3.11 to 3.14**, standard library only (`requires-python` in
+  `pyproject.toml` is `>=3.11,<3.15`; the sidebar and the config tools).
 - **bash**: macOS's 3.2 is enough; sessionview's own bash tools use no
   bash-4 construct.
 - **sessionmail** (`message` on PATH) for every mail action: the
   sidebar's mail, the agent pane menu, and the session, taskmaster and
-  voicemode plugins (each lists `message` in its `requires`).
+  voicemode plugins (each lists `message` in its `requires`). Mail is
+  sent as you: `$USER`, unless `sessionview-config set mail_from NAME`
+  (or `$SESSIONVIEW_FROM`) names your mail name; `sessionview from`
+  prints the name in effect.
+- **neomutt** for the `messages` tab (`bin/sessionview-messages` runs
+  `neomutt -R`; the tab exits 2 without it): `brew install neomutt`, built
+  with notmuch (Homebrew's is). Measured on NeoMutt 20260616. The tab's
+  sidebar (the box, Asks, Asks · threads) also needs **notmuch** with the
+  `Type` and `Project` headers indexed:
+  `notmuch config set index.header.Type Type`,
+  `notmuch config set index.header.Project Project`, then
+  `notmuch reindex '*'`. Without the index the Asks rows are every mail to
+  `NAME+ask`; without notmuch the sidebar is hidden and the tab still
+  opens the one folder.
 - **postfix: not needed by sessionview itself.** sessionview never talks
   to an MTA; sessionmail's `message send` hands each mail to
   `/usr/sbin/sendmail` (or `$SESSIONMAIL_SENDMAIL`) and refuses with
@@ -61,12 +88,7 @@ on your machine.
 
 ## Features
 
-Grouped by component, named in the terms a comparison matrix would use,
-so we can still describe them once we are used to them (Mike, voice
-13:40 + 13:46 Sat 2026-09-12: "we'll just get used to them, and then
-we'll have trouble describing them ... group the sidebar and have them
-as properties of the sidebar"). Agents maintain this list; it is not
-finger memory.
+Grouped by component, named in the terms a comparison matrix would use.
 
 **Sidebar** — projects (tmux sessions) above, agents (seats) below.
 
@@ -83,7 +105,7 @@ finger memory.
   control master you already hold. The sidebar never opens a connection
   of its own, so a hardware key is never asked for a touch by a redraw.
 
-**Menus**
+### Menus
 
 - *Overflow menu* — three dots `⋯` at the right of the selected session
   open its menu (rename, new tab, config, settings, start an agent,
@@ -101,7 +123,7 @@ listed, typing narrows, enter opens the highlighted one or a plain tab
 of the name you typed. The same picker starts an agent (the `+` under
 agents, or the menu): the names `session start` knows, pinned ones first.
 
-**Agents**
+### Agents
 
 - *Start an agent* — `+` under the agents list, or *Start an agent* on a
   project's menu. The list you pick from is the launcher's own
@@ -129,7 +151,7 @@ tmux fork or plugin manager.
 Tested: Terminal.app, iTerm2, Ghostty (macOS). The sidebar needs mouse
 reporting and focus reporting from the terminal; anything that gives
 tmux those should work, but only the three above have been driven by
-hand. Blink Shell on iPad is wanted and not yet connecting (Aug 31).
+hand. Blink Shell on iPad is wanted and not yet connecting.
 
 ## Layout
 
@@ -138,26 +160,35 @@ hand. Blink Shell on iPad is wanted and not yet connecting (Aug 31).
     bin/sessionview-frame       the frame: outer tmux, sidebar pane + client pane
     bin/sessionview-session     a project session with its configured tabs (repo / git / project / tasks)
     bin/sessionview-newtab      the tab bar's "+": the new-tab picker, in a popup
-    bin/sessionview-config      the config cascade: get / dump / path / set / unset
-    bin/sessionview-configure   the settings screen (project menu → Settings)
+    bin/sessionview-config      settings: no verb opens the screen; list / get / set / unset / dump / path
     bin/sessionview-autostart   the consent-on-open question; --start NAME is the + under agents
     bin/sessionview-sidebar-toggle  hide / show the sidebar (the ◧ glyph)
     bin/sessionview-terminal    which terminal the dock app opens
-    tmux/herd.conf       the herd look, session-scoped (sourced with S= and HERD_ROOT=)
+    tmux/frame.conf       the sessionview look, session-scoped (sourced with S= and SESSIONVIEW_ROOT=)
     tmux/tabs-top.conf   the same look, global and OPTIONAL (source-file it from ~/.tmux.conf
-                         to have it outside sessionview too; the frame applies herd.conf itself)
-    config/config.json   every default, explicit; ~/.sessionview/config.json is made from it
-    plugins/*/           herd-plugin.toml (+ scripts): session, voicemode, taskmaster
+                         to have it outside sessionview too; the frame applies frame.conf itself)
+    config/config.json   every default, explicit; ~/.sessionkit/view/settings/view.json is made from it
+    plugins/*/           plugin.toml (+ scripts): session, voicemode, taskmaster
     .claude-plugin/      sessionview is a Claude Code plugin; its skills load as
     skills/*/SKILL.md    sessionview:NAME - sessionview, tmux, lazygit, neovim,
                          claude-code: short, safe driving skills with tools
 
-Paths resolve from the checkout (`HERD_ROOT`); state lives in
-`~/.local/state/herd` (`HERD_STATE`). Requirements are listed above.
+Paths resolve from the checkout (`SESSIONVIEW_ROOT`); state lives in
+`~/.local/state/sessionview` (`SESSIONVIEW_STATE`). Requirements are listed above.
 
 ## Install
 
-    git clone https://github.com/mbailey/sessionview ~/Code/sessionview
+From PyPI:
+
+    uv tool install sessionview
+    sessionview install            # checks every requirement; links nothing
+
+That puts `sessionview`, `sessionview-config`, `sessionview-session` and
+`sessionview-messages` on PATH; `sessionview install` then only checks.
+
+From a checkout:
+
+    git clone https://github.com/sessionkit/sessionview ~/Code/sessionview
     ~/Code/sessionview/bin/sessionview-install     # or: make install
 
 That links the tools into `~/.local/bin` and checks every requirement,
@@ -171,7 +202,7 @@ show-me (github.com/mbailey/show-me) is referenced, not bundled.
 
 ### Dock app (macOS, optional)
 
-    make app            # or: bin/sessionview-app-install
+    sessionview install --app   # or: make app
 
 Builds `SessionView.app` from `macos/SessionView.applescript` and puts
 it in `~/Applications`; drag it to the Dock and one click opens
@@ -209,17 +240,61 @@ that; the app does not have one yet.
   quits, esc backs out of any view
 - tab bar: `◧` at the far left hides/shows the sidebar; click selects,
   drag reorders, `+` new tab (the picker); a close `×`, on by default;
-  `tmux set -g @herd_tab_close 0` turns it off
+  `tmux set -g @sessionview_tab_close 0` turns it off
 - menu: ↑↓ / j k move, the letter or enter picks, esc or a click
   anywhere else closes
 - agent panes (opt-in): right-click an agent's pane for Speak, Continue,
   Read Clipboard, Park or Succeed; each mails that agent. Turn it on
-  with `sessionview-config set pane_menu true` (and
-  `sessionview-config set pane_menu_from NAME` if your login name is not
-  your mail name). It replaces your own tmux right-click menu, which is
+  with `sessionview-config set pane_menu true`. It replaces your own tmux right-click menu, which is
   why it is off by default. Using tmux without session view? Add
   `source-file -q /path/to/sessionview/tmux/agent-menu.conf` to
   `~/.tmux.conf` and reload.
 
-Built by Pip, Fri 2026-09-04 – Sun 2026-09-06, from Mike's asks by voice,
-with Cora reading herdr's own window for the colours.
+The look follows herdr's; its colours were matched from herdr's own window.
+
+## Configuration
+
+- **Settings:** JSON, in layers, a later one winning. The template
+  `config/config.json` holds every key and its default.
+  `~/.sessionkit/view/settings/view.json` is yours, made from it on first
+  use; a store's and a project's `.sessionview` come after it.
+  `sessionview-config set KEY VALUE` writes yours, and
+  `sessionview-config dump --where` names the file behind each key.
+  An older install's settings are never read. Moving them is one step,
+  in [Upgrading from 0.1.0](docs/configuration.md#upgrading-from-010).
+  Until then sessionview makes nothing and refuses: `sessionview-config`
+  exits 3 and prints the move to run, and the sidebar shows the same
+  message. If the old file is left beside the new one, it uses the new one
+  and warns you to remove the old one.
+- **Your neomutt view:** `~/.sessionkit/view/settings/neomuttrc`,
+  optional, read after the shipped `config/neomuttrc`.
+- **Plugins:** `plugins/<name>/plugin.toml` in the checkout.
+- **Environment:** `SESSIONVIEW_CONFIG` (another file for yours),
+  `SESSIONVIEW_FROM` (the name mail is sent as), `SESSIONVIEW_STATE`
+  (state, default `~/.local/state/sessionview`), `SESSIONVIEW_PLUGINS`
+  (another plugin directory).
+- sessionview does not read the kit's settings cascade today, only these.
+
+Every file, variable and tmux option is in
+[Configuration](docs/configuration.md),
+and every key in
+[Settings](docs/settings.md).
+
+## Logs
+
+- `~/.local/state/sessionview/sessionview.log`: what went wrong, one
+  entry each, starting with the time (a failed tmux call, an uncaught
+  error with its traceback). Follow it with
+  `tail -f ~/.local/state/sessionview/sessionview.log` when a click
+  seems to do nothing.
+- **Levels:** `log_level` in your settings (or `$SESSIONVIEW_LOG_LEVEL`
+  for one run). `error`, the default, logs only what went wrong.
+  `timing` adds a line per click or key with its milliseconds, and each
+  command that took 50 ms or more, so a slow click names its slow part.
+  `debug` adds every command and every mouse event (what the old
+  `sidebar-mouse.log` held).
+- It sits under `$SESSIONVIEW_STATE` when that is set. It is not rotated:
+  turn `timing` or `debug` on while you look, then back to `error`.
+- **Health:** `sessionview install --check`: exit 0 and `ready` when
+  every requirement is present, exit 1 with each MISSING one named
+  otherwise. It checks the machine, not a running sidebar.

sessionview-0.1.0/PKG-INFO → sessionview-0.3.0/README.md

@@ -1,41 +1,26 @@
-Metadata-Version: 2.5
-Name: sessionview
-Version: 0.1.0
-Summary: sessionview - a sidebar for tmux: your projects (sessions) and your agents (seats), here and on remote hosts. Name reserved; the tool follows.
-Project-URL: Homepage, https://github.com/mbailey/sessionview
-Author: Mike Bailey
-License-Expression: AGPL-3.0-or-later
-License-File: LICENSE
-Classifier: Development Status :: 1 - Planning
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-
-# Herd
+# sessionview
 
 A sidebar for tmux, in the spirit of herdr: your projects (tmux sessions)
 and your agents (seats), here and on remote hosts, one click away, with a
 right-click menu built from what is installed. Session's TUI — a
 controller and view for the `session` tools, drawn beside tmux.
 
-`sessionview` 0.0.1 on PyPI reserves the name; the tool follows (Mike, approved by mail 00:25 Thu 2026-09-10).
-
+Install from PyPI: `uv tool install sessionview` (see [Install](#install)).
 
     sessionview [SESSION]            # in this terminal: sidebar left, SESSION attached
                                      # right (a private outer tmux holds the two panes)
     prefix H                         # the same sidebar as a popup in any tmux client
 
-Read [SPEC.md](SPEC.md) first: what Herd is, the rules of the view, the
-contract with `session`, the plugin manifest, config, measured limits.
-This repo is the **reference implementation** (Mike, 18:23 Sun
-2026-09-06: "a working reference implementation ... it can be a life
-raft") — session integrates from the spec; this stays comparable and
-runnable.
+Read [SPEC.md](SPEC.md) first: what sessionview is, the rules of the view, the
+contract with `session`, the plugin manifest, config, known limits.
+This repo is the **reference implementation**: session integrates from
+the spec; this stays comparable and runnable.
 
 ## Requirements
 
 Each line is measured against the code, not remembered;
-`bin/sessionview-install --check` checks tmux, Python and `session`
-on your machine.
+`bin/sessionview-install --check` checks tmux, Python, `session`,
+neomutt and notmuch's index on your machine.
 
 - **Claude Code, and the plugin is the install.** The `sessionview`
   wheel is an empty package (one `__init__.py`, no `[project.scripts]`);
@@ -48,13 +33,26 @@ on your machine.
   the frame are plain tmux + Python and should run on Linux, untested.
 - **tmux >= 3.7** (measured on 3.7c: `join-pane -l`, `focus-events`,
   status ranges). An older tmux satisfies `brew install tmux` silently.
-- **Python >= 3.11**, standard library only (`requires-python` in
-  `pyproject.toml`; the sidebar and the config tools).
+- **Python 3.11 to 3.14**, standard library only (`requires-python` in
+  `pyproject.toml` is `>=3.11,<3.15`; the sidebar and the config tools).
 - **bash**: macOS's 3.2 is enough; sessionview's own bash tools use no
   bash-4 construct.
 - **sessionmail** (`message` on PATH) for every mail action: the
   sidebar's mail, the agent pane menu, and the session, taskmaster and
-  voicemode plugins (each lists `message` in its `requires`).
+  voicemode plugins (each lists `message` in its `requires`). Mail is
+  sent as you: `$USER`, unless `sessionview-config set mail_from NAME`
+  (or `$SESSIONVIEW_FROM`) names your mail name; `sessionview from`
+  prints the name in effect.
+- **neomutt** for the `messages` tab (`bin/sessionview-messages` runs
+  `neomutt -R`; the tab exits 2 without it): `brew install neomutt`, built
+  with notmuch (Homebrew's is). Measured on NeoMutt 20260616. The tab's
+  sidebar (the box, Asks, Asks · threads) also needs **notmuch** with the
+  `Type` and `Project` headers indexed:
+  `notmuch config set index.header.Type Type`,
+  `notmuch config set index.header.Project Project`, then
+  `notmuch reindex '*'`. Without the index the Asks rows are every mail to
+  `NAME+ask`; without notmuch the sidebar is hidden and the tab still
+  opens the one folder.
 - **postfix: not needed by sessionview itself.** sessionview never talks
   to an MTA; sessionmail's `message send` hands each mail to
   `/usr/sbin/sendmail` (or `$SESSIONMAIL_SENDMAIL`) and refuses with
@@ -73,12 +71,7 @@ on your machine.
 
 ## Features
 
-Grouped by component, named in the terms a comparison matrix would use,
-so we can still describe them once we are used to them (Mike, voice
-13:40 + 13:46 Sat 2026-09-12: "we'll just get used to them, and then
-we'll have trouble describing them ... group the sidebar and have them
-as properties of the sidebar"). Agents maintain this list; it is not
-finger memory.
+Grouped by component, named in the terms a comparison matrix would use.
 
 **Sidebar** — projects (tmux sessions) above, agents (seats) below.
 
@@ -95,7 +88,7 @@ finger memory.
   control master you already hold. The sidebar never opens a connection
   of its own, so a hardware key is never asked for a touch by a redraw.
 
-**Menus**
+### Menus
 
 - *Overflow menu* — three dots `⋯` at the right of the selected session
   open its menu (rename, new tab, config, settings, start an agent,
@@ -113,7 +106,7 @@ listed, typing narrows, enter opens the highlighted one or a plain tab
 of the name you typed. The same picker starts an agent (the `+` under
 agents, or the menu): the names `session start` knows, pinned ones first.
 
-**Agents**
+### Agents
 
 - *Start an agent* — `+` under the agents list, or *Start an agent* on a
   project's menu. The list you pick from is the launcher's own
@@ -141,7 +134,7 @@ tmux fork or plugin manager.
 Tested: Terminal.app, iTerm2, Ghostty (macOS). The sidebar needs mouse
 reporting and focus reporting from the terminal; anything that gives
 tmux those should work, but only the three above have been driven by
-hand. Blink Shell on iPad is wanted and not yet connecting (Aug 31).
+hand. Blink Shell on iPad is wanted and not yet connecting.
 
 ## Layout
 
@@ -150,26 +143,35 @@ hand. Blink Shell on iPad is wanted and not yet connecting (Aug 31).
     bin/sessionview-frame       the frame: outer tmux, sidebar pane + client pane
     bin/sessionview-session     a project session with its configured tabs (repo / git / project / tasks)
     bin/sessionview-newtab      the tab bar's "+": the new-tab picker, in a popup
-    bin/sessionview-config      the config cascade: get / dump / path / set / unset
-    bin/sessionview-configure   the settings screen (project menu → Settings)
+    bin/sessionview-config      settings: no verb opens the screen; list / get / set / unset / dump / path
     bin/sessionview-autostart   the consent-on-open question; --start NAME is the + under agents
     bin/sessionview-sidebar-toggle  hide / show the sidebar (the ◧ glyph)
     bin/sessionview-terminal    which terminal the dock app opens
-    tmux/herd.conf       the herd look, session-scoped (sourced with S= and HERD_ROOT=)
+    tmux/frame.conf       the sessionview look, session-scoped (sourced with S= and SESSIONVIEW_ROOT=)
     tmux/tabs-top.conf   the same look, global and OPTIONAL (source-file it from ~/.tmux.conf
-                         to have it outside sessionview too; the frame applies herd.conf itself)
-    config/config.json   every default, explicit; ~/.sessionview/config.json is made from it
-    plugins/*/           herd-plugin.toml (+ scripts): session, voicemode, taskmaster
+                         to have it outside sessionview too; the frame applies frame.conf itself)
+    config/config.json   every default, explicit; ~/.sessionkit/view/settings/view.json is made from it
+    plugins/*/           plugin.toml (+ scripts): session, voicemode, taskmaster
     .claude-plugin/      sessionview is a Claude Code plugin; its skills load as
     skills/*/SKILL.md    sessionview:NAME - sessionview, tmux, lazygit, neovim,
                          claude-code: short, safe driving skills with tools
 
-Paths resolve from the checkout (`HERD_ROOT`); state lives in
-`~/.local/state/herd` (`HERD_STATE`). Requirements are listed above.
+Paths resolve from the checkout (`SESSIONVIEW_ROOT`); state lives in
+`~/.local/state/sessionview` (`SESSIONVIEW_STATE`). Requirements are listed above.
 
 ## Install
 
-    git clone https://github.com/mbailey/sessionview ~/Code/sessionview
+From PyPI:
+
+    uv tool install sessionview
+    sessionview install            # checks every requirement; links nothing
+
+That puts `sessionview`, `sessionview-config`, `sessionview-session` and
+`sessionview-messages` on PATH; `sessionview install` then only checks.
+
+From a checkout:
+
+    git clone https://github.com/sessionkit/sessionview ~/Code/sessionview
     ~/Code/sessionview/bin/sessionview-install     # or: make install
 
 That links the tools into `~/.local/bin` and checks every requirement,
@@ -183,7 +185,7 @@ show-me (github.com/mbailey/show-me) is referenced, not bundled.
 
 ### Dock app (macOS, optional)
 
-    make app            # or: bin/sessionview-app-install
+    sessionview install --app   # or: make app
 
 Builds `SessionView.app` from `macos/SessionView.applescript` and puts
 it in `~/Applications`; drag it to the Dock and one click opens
@@ -221,17 +223,61 @@ that; the app does not have one yet.
   quits, esc backs out of any view
 - tab bar: `◧` at the far left hides/shows the sidebar; click selects,
   drag reorders, `+` new tab (the picker); a close `×`, on by default;
-  `tmux set -g @herd_tab_close 0` turns it off
+  `tmux set -g @sessionview_tab_close 0` turns it off
 - menu: ↑↓ / j k move, the letter or enter picks, esc or a click
   anywhere else closes
 - agent panes (opt-in): right-click an agent's pane for Speak, Continue,
   Read Clipboard, Park or Succeed; each mails that agent. Turn it on
-  with `sessionview-config set pane_menu true` (and
-  `sessionview-config set pane_menu_from NAME` if your login name is not
-  your mail name). It replaces your own tmux right-click menu, which is
+  with `sessionview-config set pane_menu true`. It replaces your own tmux right-click menu, which is
   why it is off by default. Using tmux without session view? Add
   `source-file -q /path/to/sessionview/tmux/agent-menu.conf` to
   `~/.tmux.conf` and reload.
 
-Built by Pip, Fri 2026-09-04 – Sun 2026-09-06, from Mike's asks by voice,
-with Cora reading herdr's own window for the colours.
+The look follows herdr's; its colours were matched from herdr's own window.
+
+## Configuration
+
+- **Settings:** JSON, in layers, a later one winning. The template
+  `config/config.json` holds every key and its default.
+  `~/.sessionkit/view/settings/view.json` is yours, made from it on first
+  use; a store's and a project's `.sessionview` come after it.
+  `sessionview-config set KEY VALUE` writes yours, and
+  `sessionview-config dump --where` names the file behind each key.
+  An older install's settings are never read. Moving them is one step,
+  in [Upgrading from 0.1.0](docs/configuration.md#upgrading-from-010).
+  Until then sessionview makes nothing and refuses: `sessionview-config`
+  exits 3 and prints the move to run, and the sidebar shows the same
+  message. If the old file is left beside the new one, it uses the new one
+  and warns you to remove the old one.
+- **Your neomutt view:** `~/.sessionkit/view/settings/neomuttrc`,
+  optional, read after the shipped `config/neomuttrc`.
+- **Plugins:** `plugins/<name>/plugin.toml` in the checkout.
+- **Environment:** `SESSIONVIEW_CONFIG` (another file for yours),
+  `SESSIONVIEW_FROM` (the name mail is sent as), `SESSIONVIEW_STATE`
+  (state, default `~/.local/state/sessionview`), `SESSIONVIEW_PLUGINS`
+  (another plugin directory).
+- sessionview does not read the kit's settings cascade today, only these.
+
+Every file, variable and tmux option is in
+[Configuration](docs/configuration.md),
+and every key in
+[Settings](docs/settings.md).
+
+## Logs
+
+- `~/.local/state/sessionview/sessionview.log`: what went wrong, one
+  entry each, starting with the time (a failed tmux call, an uncaught
+  error with its traceback). Follow it with
+  `tail -f ~/.local/state/sessionview/sessionview.log` when a click
+  seems to do nothing.
+- **Levels:** `log_level` in your settings (or `$SESSIONVIEW_LOG_LEVEL`
+  for one run). `error`, the default, logs only what went wrong.
+  `timing` adds a line per click or key with its milliseconds, and each
+  command that took 50 ms or more, so a slow click names its slow part.
+  `debug` adds every command and every mouse event (what the old
+  `sidebar-mouse.log` held).
+- It sits under `$SESSIONVIEW_STATE` when that is set. It is not rotated:
+  turn `timing` or `debug` on while you look, then back to `error`.
+- **Health:** `sessionview install --check`: exit 0 and `ready` when
+  every requirement is present, exit 1 with each MISSING one named
+  otherwise. It checks the machine, not a running sidebar.

sessionview-0.3.0/bin/sessionview

@@ -0,0 +1,75 @@
+#!/bin/sh
+# sessionview - a sidebar for tmux, in this terminal. Needs tmux, nothing else.
+#
+# usage: sessionview [SESSION] [--sock SERVER] [--width N]
+#        sessionview COMMAND [ARGS]
+#
+#   sessionview [SESSION]  the frame: sidebar on the left, SESSION attached on
+#                    the right (default main; a named SESSION must exist).
+#                    --sock names its tmux server; --width, columns.
+#   sessionview config     settings: no verb opens the screen (get/set/list ...)
+#   sessionview session NAME    open a project session with its standard tabs
+#   sessionview messages PROJECT   a project's mail, read-only, in NeoMutt
+#   sessionview install    check requirements (--app: the macOS Dock app)
+#   sessionview autostart --status   which agent starts when sessionview opens
+#   sessionview from       the name your mail is sent as (mail_from, else $USER)
+#   sessionview sidebar-toggle   hide the sidebar, or show it again
+#   sessionview sidebar    the sidebar under its supervisor (the frame's left
+#                    pane runs this). In it: q reloads, Q quits.
+#
+# Also: prefix H in any tmux client opens the sidebar as a popup.
+# Config: ~/.sessionkit/view/settings/view.json over the shipped config/config.json.
+# State: ~/.local/state/sessionview (SESSIONVIEW_STATE=).
+#
+# Ghostty was stripped out so this works in any terminal with only tmux. It
+# started as ghostty-herd; the Ghostty launcher, the split hook and cmd+d
+# went with the frame (1fd29ce) and this rename. -h prints the usage above
+# without the comment marks, so the help reads cleanly.
+SESSIONVIEW_ROOT="${SESSIONVIEW_ROOT:-$(cd "$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")")/.." && pwd)}"
+SESSIONVIEW_STATE="${SESSIONVIEW_STATE:-$HOME/.local/state/sessionview}"; . "$SESSIONVIEW_ROOT/lib/state.sh"; . "$SESSIONVIEW_ROOT/lib/python.sh"; export SESSIONVIEW_ROOT SESSIONVIEW_STATE
+# The header above is the usage: -h prints it, and so does an unknown word.
+usage() { sed -n '2,22p' "$0" | sed 's/^# \{0,1\}//'; }
+case "${1:-}" in
+  -h|--help|help) usage; exit 0;;
+  config|session|messages|install|autostart|terminal|usermail|from|sidebar-toggle)
+    sub="$1"; shift; exec "$SESSIONVIEW_ROOT/bin/sessionview-$sub" "$@";;
+  sidebar)
+    # The supervisor: q = exit 0 = reload (picks up an edited tmux-sidebar or
+    # sidebar.toml), Q = exit 3 = quit. A CRASH IS NOT A QUIT: any other exit
+    # holds the error on screen and waits (one undefined name once took the
+    # whole sidebar away).
+    while :; do
+      "$SESSIONVIEW_ROOT/bin/tmux-sidebar"; rc=$?
+      [ "$rc" = 3 ] && break
+      [ "$rc" = 0 ] && continue
+      printf '\n\033[31m sidebar crashed (exit %s)\033[0m -- Enter restarts, Q then Enter quits. ' "$rc"
+      read -r k || break
+      case "$k" in [Qq]) break;; esac
+    done
+    exit 0;;
+esac
+# Anything else is the frame. A word that names no subcommand opens a frame
+# ONLY on a session that already exists on the server the frame will use
+# (--sock, else this tmux's own server when run inside one, else default):
+# a typo or a probe word must not mean "open a frame on a new session named
+# after it". Read-only check; on a miss, usage and exit 2, nothing touched.
+# A new named session is `sessionview session NAME`. No word = main, as before.
+word=""; sock=""; prev=""
+for a in "$@"; do
+  case "$prev" in --sock) sock="$a"; prev=""; continue;; --width) prev=""; continue;; esac
+  case "$a" in --sock|--width) prev="$a";; -*) ;; *) word="$a";; esac
+done
+if [ -n "$word" ]; then
+  extra=""
+  if [ -z "$sock" ]; then
+    if [ -n "${TMUX:-}" ]; then sock="$(printf %s "${TMUX%%,*}")"; sock="${sock##*/}"; extra=1; else sock=default; fi
+  fi
+  if ! tmux -L "$sock" has-session -t "=$word" 2>/dev/null; then
+    echo "sessionview: no command or session named '$word' (on tmux server $sock); a new session is: sessionview session $word" >&2
+    usage >&2
+    exit 2
+  fi
+  # the frame looks where this checked: inside tmux, the caller's own server
+  [ -n "$extra" ] && set -- "$@" --sock "$sock"
+fi
+exec "$SESSIONVIEW_ROOT/bin/sessionview-frame" "$@"

sessionview-0.3.0/bin/sessionview-app-install

@@ -0,0 +1,75 @@
+#!/bin/sh
+# sessionview-app-install - build the macOS Dock app from macos/ and install it.
+#
+#   sessionview-app-install            build + install to ~/Applications
+#   sessionview-app-install --check    say what it would do, change nothing
+#   DEST=/Applications sessionview-app-install
+#
+# Why this exists: the Dock app once existed ONLY as a compiled bundle in
+# one person's ~/Applications. Nobody could read it, diff it or install it,
+# and a path bug in it went unseen for a day.
+# The source is now macos/SessionView.applescript and this rebuilds it.
+#
+# The app is a FRONT DOOR, not the product: it opens a terminal and runs
+# `sessionview` in it. `sessionview` in any shell does the same job.
+set -u
+ROOT="$(cd "$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")")/.." && pwd)"
+SRC="$ROOT/macos/SessionView.applescript"
+ICON="$ROOT/macos/dreamcatcher.icns"
+DEST="${DEST:-$HOME/Applications}"
+APP="$DEST/SessionView.app"
+CHECK=""; [ "${1:-}" = "--check" ] && CHECK=1
+
+[ "$(uname -s)" = "Darwin" ] || { echo "sessionview-app-install: macOS only (this is $(uname -s))" >&2; exit 1; }
+[ -f "$SRC" ] || { echo "sessionview-app-install: missing $SRC" >&2; exit 1; }
+command -v osacompile >/dev/null 2>&1 || { echo "sessionview-app-install: osacompile not found (install Xcode command line tools)" >&2; exit 1; }
+
+if [ -n "$CHECK" ]; then
+  echo "source: $SRC"
+  echo "icon:   $ICON"
+  echo "would install: $APP"
+  [ -e "$APP" ] && echo "note: $APP exists and would be REPLACED"
+  exit 0
+fi
+
+TMP="$(mktemp -d)" || exit 1
+trap 'rm -rf "$TMP"' EXIT
+osacompile -o "$TMP/SessionView.app" "$SRC" || exit 1
+
+# custom icon: the compiled applet ships AppleScript's own
+if [ -f "$ICON" ]; then
+  cp "$ICON" "$TMP/SessionView.app/Contents/Resources/dreamcatcher.icns" || exit 1
+  /usr/libexec/PlistBuddy -c "Set :CFBundleIconFile dreamcatcher" \
+    "$TMP/SessionView.app/Contents/Info.plist" >/dev/null 2>&1 \
+    || /usr/libexec/PlistBuddy -c "Add :CFBundleIconFile string dreamcatcher" \
+       "$TMP/SessionView.app/Contents/Info.plist" >/dev/null
+  # the compiled applet also names an icon inside Assets.car; that key wins
+  # over CFBundleIconFile on recent macOS, so it goes.
+  /usr/libexec/PlistBuddy -c "Delete :CFBundleIconName" \
+    "$TMP/SessionView.app/Contents/Info.plist" >/dev/null 2>&1 || :
+fi
+for kv in "CFBundleName Dreamcatcher" "CFBundleDisplayName Dreamcatcher" "CFBundleIdentifier Dreamcatcher"; do
+  k=${kv%% *}; v=${kv#* }
+  /usr/libexec/PlistBuddy -c "Set :$k $v" "$TMP/SessionView.app/Contents/Info.plist" >/dev/null 2>&1 \
+    || /usr/libexec/PlistBuddy -c "Add :$k string $v" "$TMP/SessionView.app/Contents/Info.plist" >/dev/null
+done
+# ad-hoc signature: unsigned bundles that CHANGE in place get killed by
+# Gatekeeper's cached hashes ("damaged"). Re-signing after every edit is the fix.
+codesign -f -s - "$TMP/SessionView.app" >/dev/null 2>&1 || \
+  echo "sessionview-app-install: warning - could not sign the bundle" >&2
+
+mkdir -p "$DEST" || exit 1
+rm -rf "$APP" || exit 1
+mv "$TMP/SessionView.app" "$APP" || exit 1
+touch "$APP"            # nudge Finder to re-read the icon
+echo "sessionview: installed $APP"
+echo "drag it to your Dock; one click opens sessionview in your preferred terminal"
+# The ad-hoc signature is a fresh identity every build, and macOS keys TCC
+# permissions to it -- so a rebuild silently revokes the Accessibility tick
+# that `fullscreen` needs on Terminal.app. Say so, every time, rather than
+# letting it look like the feature broke.
+if [ "$(command -v sessionview-config >/dev/null 2>&1 && sessionview-config get fullscreen 2>/dev/null)" = "true" ]; then
+  echo
+  echo "note: fullscreen is on, and this REBUILD resets its Accessibility permission."
+  echo "      System Settings > Privacy & Security > Accessibility > turn SessionView back on."
+fi