sessiontools 0.1.0__tar.gz → 0.2.0__tar.gz

sessiontools-0.2.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: sessiontools
+Version: 0.2.0
+Summary: The harness layer: sessions, status and idle, one driver per harness - a library first
+Author: Mike Bailey
+Author-email: Mike Bailey <mike@sessionkit.ai>
+License-Expression: AGPL-3.0-or-later
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Requires-Dist: pyyaml>=6
+Requires-Dist: jsonschema>=4
+Requires-Python: >=3.11, <3.15
+Project-URL: Homepage, https://github.com/sessionkit/sessiontools
+Project-URL: Repository, https://github.com/sessionkit/sessiontools
+Description-Content-Type: text/markdown
+
+# sessiontools
+
+`session`: one command for the coding-agent sessions on this machine.
+Which are live, whether each is busy or idle, how full its context is,
+and how to start one from an agent file. For anyone running several
+Claude Code sessions side by side, and for the tools that watch them.
+
+## Install
+
+```console
+uv tool install sessiontools     # puts `session` on the PATH
+```
+
+Python 3.11 to 3.14. Optional: [the Claude Code plugin][plugin] adds
+the `session` skill and two hooks.
+
+Shell completion, one line per shell ([shell completion][completion]):
+
+```console
+eval "$(session completion zsh)"     # zsh: in ~/.zshrc, after compinit
+session completion bash > ~/.local/share/bash-completion/completions/session  # bash with bash-completion 2
+eval "$(session completion bash)"    # bash 3.2 or any bash without it: in ~/.bashrc
+```
+
+## Quick start
+
+```console
+session list                 # the live sessions: panes, state, context
+session get state            # this session: busy, idle with children, idle
+session context              # how full this session's context window is
+session context --parts      # what filled it: boot, then growth by category
+session ledger --short       # each file read and command run, by tokens
+session account status       # which Claude account this Mac is on
+session start --list-agents  # the agents it can start
+session reap                 # seats idle past 1h: CLOSE or KEEP, and why (a dry run)
+session --help               # every verb
+```
+
+## Switching accounts
+
+`session account use NAME` moves this Mac to another Claude account from
+a token you already hold: no browser, no restart, and it never prints a
+token. On a Keychain host it moves **every** seat, not one:
+
+| route | moves | cache cost | reversible by | gate |
+|---|---|---|---|---|
+| `account use` (Keychain) | every seat on the Mac with no env token, within ~50 s | the sum of their contexts (2.07M / 1.10M measured) | `use` back, or restore from the backup | witness, `--yes`, preflight, backup |
+| `account use` (token file) | no live seat; each one that relaunches from a shell that reads the file | none now; each seat's context when it restarts | `use` back, or restore from the backup | witness, `--yes`, preflight, backup |
+
+A host whose shell exports `CLAUDE_CODE_OAUTH_TOKEN` from a file names it
+in the `session` setting `account.token_file`, and `use` swaps the file.
+Without `--yes`, `use` shows the plan and writes nothing. To add an
+account, `session account new NAME --email E` signs in through `claude
+setup-token`, saves the token to passage, reads it back and registers
+it; the token is never shown. See [Switching Claude accounts][account].
+
+## Uninstall
+
+```console
+uv tool uninstall sessiontools
+```
+
+It leaves `~/.session/` (session dirs, the list cache) and
+`~/.sessionkit/tools/settings/`; remove them by hand to leave nothing
+behind.
+
+## Docs
+
+- [The `session` verbs][verbs]: list, get, context, ledger, account,
+  settings, operator, reap
+- [Starting a session][start]: agent files, flags, tmux, one holder
+- [Switching Claude accounts][account]: `session account`, its blast
+  radius, and `new`, which adds an account
+- [The `session list` cache][cache]: one computation, many readers
+- [Operator and privileged seats][operator]: who seats ask
+- [Closing idle seats][reap]: `session reap`, a dry run by default
+- [Shell completion][completion]: `session completion bash|zsh`, a static
+  script built from the verbs' own parsers
+- [The Claude Code plugin][plugin]: the skill and the hooks
+- [The settle alert][settle]: one line past a context threshold
+- [The busy sound][busy]: a sound while a tool batch runs long
+- [The sound engine][engine]: the busy sound from one resident process
+- [The status line][status-line]: `session statusline install` puts it in the
+  kit's claude-code layer, never `~/.claude`. `session start` seats show it;
+  a bare `claude` does not (`alias claude='session start -'`)
+- [The pane signal][pane-state]: BUSY / FREE on each seat's tmux pane,
+  and `session pane-state agent`, the launchd agent that publishes it
+- [The Python library][library]: `from sessiontools import sessions`
+- [Building and testing][building]: make targets, specs, releases
+- [CHANGELOG][changelog]; licence AGPL-3.0-or-later ([LICENSE][license])
+
+## Configuration
+
+Nothing needs configuring: unset, every part uses its default. What can
+be set, and where each one lives ([configuration][configuration]):
+
+- **Settings files**, JSON in layers: `~/.sessionkit/tools/settings/session.json`
+  (the operator, the list cache, the pane signal, accounts, a session's
+  home), `~/.sessionkit/tools/settings/sounds.json` (the busy sound), and
+  `~/.sessionkit/tools/settings/claude-code.json` (the model, effort
+  and status line `session start` passes on). Every key, its default and
+  which layers it is read from: [settings][settings].
+- **Folders of its own:** `~/.session/` (sessions, seats, agent files, the
+  state dir) and `~/.sessionkit/tools/accounts/` (`session account`).
+- **Environment variables:** the settle alert's `SESSION_SETTLE_AT`, the
+  hooks' `SESSIONTOOLS_HOOK_*` switches, and the paths it reads, such as
+  `SESSIONS_DIR` and `SESSION_STATE_DIR`. The configuration page lists
+  each one with its default, under the part that reads it.
+
+## Logs
+
+- **The sound engine:** `~/Library/Logs/sessiontools/sound-engine.log`,
+  once `session sound engine on` has run.
+- **The pane signal's agent:** `~/Library/Logs/sessiontools/pane-state.log`,
+  once `session pane-state agent on` has run.
+- **`session reap --yes`:** `~/.session/state/reap.log`, one line for each
+  seat it closed or failed to close.
+- **Each session's settings at birth:**
+  `~/.session/sessions/<session-id>/log/settings.jsonl`, what `session
+  start` read into that session's settings: each environment variable
+  by name, never its value.
+- **The status line:** `~/.config/session/statusline-log.jsonl`, one line
+  per render, only when `~/.config/session/` already exists.
+
+Follow one as it grows with `tail -F`, for example
+`tail -F ~/Library/Logs/sessiontools/pane-state.log`.
+
+- **Health:** `session list` prints a row for each live session, with its
+  state and context. A session you know is running that is not listed is
+  one sessiontools cannot see.
+
+[verbs]: docs/session-command-verbs.md
+[start]: docs/session-start-launcher.md
+[account]: docs/account.md
+[cache]: docs/list-snapshot-cache.md
+[operator]: docs/operator-privileged-seats.md
+[reap]: docs/session-reap.md
+[completion]: docs/shell-completion.md
+[plugin]: docs/claude-code-plugin.md
+[settle]: docs/settle-alert-hook.md
+[busy]: docs/busy-sound-hook.md
+[engine]: docs/sound-engine-agent.md
+[status-line]: docs/status-line-script.md
+[pane-state]: docs/pane-state-signal.md
+[library]: docs/python-library-api.md
+[building]: docs/building-and-testing.md
+[changelog]: CHANGELOG.md
+[license]: LICENSE
+[configuration]: docs/configuration.md
+[settings]: docs/settings.md

sessiontools-0.2.0/README.md

@@ -0,0 +1,150 @@
+# sessiontools
+
+`session`: one command for the coding-agent sessions on this machine.
+Which are live, whether each is busy or idle, how full its context is,
+and how to start one from an agent file. For anyone running several
+Claude Code sessions side by side, and for the tools that watch them.
+
+## Install
+
+```console
+uv tool install sessiontools     # puts `session` on the PATH
+```
+
+Python 3.11 to 3.14. Optional: [the Claude Code plugin][plugin] adds
+the `session` skill and two hooks.
+
+Shell completion, one line per shell ([shell completion][completion]):
+
+```console
+eval "$(session completion zsh)"     # zsh: in ~/.zshrc, after compinit
+session completion bash > ~/.local/share/bash-completion/completions/session  # bash with bash-completion 2
+eval "$(session completion bash)"    # bash 3.2 or any bash without it: in ~/.bashrc
+```
+
+## Quick start
+
+```console
+session list                 # the live sessions: panes, state, context
+session get state            # this session: busy, idle with children, idle
+session context              # how full this session's context window is
+session context --parts      # what filled it: boot, then growth by category
+session ledger --short       # each file read and command run, by tokens
+session account status       # which Claude account this Mac is on
+session start --list-agents  # the agents it can start
+session reap                 # seats idle past 1h: CLOSE or KEEP, and why (a dry run)
+session --help               # every verb
+```
+
+## Switching accounts
+
+`session account use NAME` moves this Mac to another Claude account from
+a token you already hold: no browser, no restart, and it never prints a
+token. On a Keychain host it moves **every** seat, not one:
+
+| route | moves | cache cost | reversible by | gate |
+|---|---|---|---|---|
+| `account use` (Keychain) | every seat on the Mac with no env token, within ~50 s | the sum of their contexts (2.07M / 1.10M measured) | `use` back, or restore from the backup | witness, `--yes`, preflight, backup |
+| `account use` (token file) | no live seat; each one that relaunches from a shell that reads the file | none now; each seat's context when it restarts | `use` back, or restore from the backup | witness, `--yes`, preflight, backup |
+
+A host whose shell exports `CLAUDE_CODE_OAUTH_TOKEN` from a file names it
+in the `session` setting `account.token_file`, and `use` swaps the file.
+Without `--yes`, `use` shows the plan and writes nothing. To add an
+account, `session account new NAME --email E` signs in through `claude
+setup-token`, saves the token to passage, reads it back and registers
+it; the token is never shown. See [Switching Claude accounts][account].
+
+## Uninstall
+
+```console
+uv tool uninstall sessiontools
+```
+
+It leaves `~/.session/` (session dirs, the list cache) and
+`~/.sessionkit/tools/settings/`; remove them by hand to leave nothing
+behind.
+
+## Docs
+
+- [The `session` verbs][verbs]: list, get, context, ledger, account,
+  settings, operator, reap
+- [Starting a session][start]: agent files, flags, tmux, one holder
+- [Switching Claude accounts][account]: `session account`, its blast
+  radius, and `new`, which adds an account
+- [The `session list` cache][cache]: one computation, many readers
+- [Operator and privileged seats][operator]: who seats ask
+- [Closing idle seats][reap]: `session reap`, a dry run by default
+- [Shell completion][completion]: `session completion bash|zsh`, a static
+  script built from the verbs' own parsers
+- [The Claude Code plugin][plugin]: the skill and the hooks
+- [The settle alert][settle]: one line past a context threshold
+- [The busy sound][busy]: a sound while a tool batch runs long
+- [The sound engine][engine]: the busy sound from one resident process
+- [The status line][status-line]: `session statusline install` puts it in the
+  kit's claude-code layer, never `~/.claude`. `session start` seats show it;
+  a bare `claude` does not (`alias claude='session start -'`)
+- [The pane signal][pane-state]: BUSY / FREE on each seat's tmux pane,
+  and `session pane-state agent`, the launchd agent that publishes it
+- [The Python library][library]: `from sessiontools import sessions`
+- [Building and testing][building]: make targets, specs, releases
+- [CHANGELOG][changelog]; licence AGPL-3.0-or-later ([LICENSE][license])
+
+## Configuration
+
+Nothing needs configuring: unset, every part uses its default. What can
+be set, and where each one lives ([configuration][configuration]):
+
+- **Settings files**, JSON in layers: `~/.sessionkit/tools/settings/session.json`
+  (the operator, the list cache, the pane signal, accounts, a session's
+  home), `~/.sessionkit/tools/settings/sounds.json` (the busy sound), and
+  `~/.sessionkit/tools/settings/claude-code.json` (the model, effort
+  and status line `session start` passes on). Every key, its default and
+  which layers it is read from: [settings][settings].
+- **Folders of its own:** `~/.session/` (sessions, seats, agent files, the
+  state dir) and `~/.sessionkit/tools/accounts/` (`session account`).
+- **Environment variables:** the settle alert's `SESSION_SETTLE_AT`, the
+  hooks' `SESSIONTOOLS_HOOK_*` switches, and the paths it reads, such as
+  `SESSIONS_DIR` and `SESSION_STATE_DIR`. The configuration page lists
+  each one with its default, under the part that reads it.
+
+## Logs
+
+- **The sound engine:** `~/Library/Logs/sessiontools/sound-engine.log`,
+  once `session sound engine on` has run.
+- **The pane signal's agent:** `~/Library/Logs/sessiontools/pane-state.log`,
+  once `session pane-state agent on` has run.
+- **`session reap --yes`:** `~/.session/state/reap.log`, one line for each
+  seat it closed or failed to close.
+- **Each session's settings at birth:**
+  `~/.session/sessions/<session-id>/log/settings.jsonl`, what `session
+  start` read into that session's settings: each environment variable
+  by name, never its value.
+- **The status line:** `~/.config/session/statusline-log.jsonl`, one line
+  per render, only when `~/.config/session/` already exists.
+
+Follow one as it grows with `tail -F`, for example
+`tail -F ~/Library/Logs/sessiontools/pane-state.log`.
+
+- **Health:** `session list` prints a row for each live session, with its
+  state and context. A session you know is running that is not listed is
+  one sessiontools cannot see.
+
+[verbs]: docs/session-command-verbs.md
+[start]: docs/session-start-launcher.md
+[account]: docs/account.md
+[cache]: docs/list-snapshot-cache.md
+[operator]: docs/operator-privileged-seats.md
+[reap]: docs/session-reap.md
+[completion]: docs/shell-completion.md
+[plugin]: docs/claude-code-plugin.md
+[settle]: docs/settle-alert-hook.md
+[busy]: docs/busy-sound-hook.md
+[engine]: docs/sound-engine-agent.md
+[status-line]: docs/status-line-script.md
+[pane-state]: docs/pane-state-signal.md
+[library]: docs/python-library-api.md
+[building]: docs/building-and-testing.md
+[changelog]: CHANGELOG.md
+[license]: LICENSE
+[configuration]: docs/configuration.md
+[settings]: docs/settings.md

{sessiontools-0.1.0 → sessiontools-0.2.0}/pyproject.toml

@@ -1,38 +1,43 @@
 [project]
 name = "sessiontools"
-version = "0.1.0"
+version = "0.2.0"
 description = "The harness layer: sessions, status and idle, one driver per harness - a library first"
+readme = "README.md"
 license = "AGPL-3.0-or-later"
 license-files = ["LICENSE"]
 authors = [
-    { name = "Cora 7", email = "ai-cora@failmode.com" }
+    { name = "Mike Bailey", email = "mike@sessionkit.ai" }
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
 ]
 # >=3.11, not the recipe's >=3.13: sessionmail (the first consumer) declares
 # >=3.11, and uv resolves for EVERY version a project allows, so a stricter
-# floor here made sessionmail's `uv sync` unsatisfiable (Pip, 13:02 Thu
-# 2026-09-17). Measured: the suite passes on 3.11, 3.12 and 3.13; nothing in
-# the tree needs 3.13.
-requires-python = ">=3.11"
-# ONE runtime dependency, and only for `session start`: agent front matter
-# is YAML (the same YAML Claude Code reads itself). Mike, voice 00:12 Tue
-# 2026-09-29, asked "Can start pull in the YAML library, just for itself?":
-# "Um, yes." So PyYAML is declared here and imported by exactly one module,
+# floor here made sessionmail's `uv sync` unsatisfiable.
+# Measured: the suite passes on 3.11, 3.12 and 3.13; nothing in
+# the tree needs 3.13. The ceiling, <3.15, makes 3.14 the newest supported
+# version.
+requires-python = ">=3.11,<3.15"
+# TWO runtime dependencies. The FIRST, PyYAML, for agent front matter, which
+# is YAML (the same YAML Claude Code reads itself), and `session start`
+# may pull in the YAML library for itself alone. So PyYAML is declared here and imported by exactly one module,
 # `sessiontools.start.agentfile`; `import sessiontools` (the library
 # sessionmail depends on) still imports nothing outside the standard library.
 # tests/test_cli.py pins both halves.
 # The SECOND: jsonschema, for `session settings` alone - each tool ships a
 # JSON Schema and the reader checks the merged result against it. No
-# configuration library for the layering (Mike, voice 19:15 Sat 2026-10-03,
-# Cora /RULINGS 4600); imported inside `sessiontools.settings.check_schema`,
+# configuration library for the layering, by design; imported inside `sessiontools.settings.check_schema`,
 # so `import sessiontools` still reaches nothing outside the standard library.
 dependencies = ["PyYAML>=6", "jsonschema>=4"]
 
-# THE `session` COMMAND - ruled at the cutover. Mike, voice 23:25-23:28 Mon
-# 2026-09-28, the session repo just moved aside: sessiontools provides it
-# ("Ah, yes, it should"), same verbs, ported as package code ("port it
-# nicely"), superseding his 12:18 Thu 2026-09-17 "not on our path today".
+# THE `session` COMMAND - settled at the cutover, when the session repo moved
+# aside: sessiontools provides it, same verbs, ported as package code.
 # Exactly one package owns `session` on the PATH; from here it is this one.
 # argparse and the library; PyYAML for `session start` alone (above).
+[project.urls]
+Homepage = "https://github.com/sessionkit/sessiontools"
+Repository = "https://github.com/sessionkit/sessiontools"
+
 [project.scripts]
 session = "sessiontools.cli:main"
 

{sessiontools-0.1.0 → sessiontools-0.2.0}/src/sessiontools/__init__.py

@@ -1,16 +1,19 @@
 """sessiontools - the harness layer: sessions, their status, and how long
 they have been idle - one driver per harness, a library first.
 
-Import it, or use the command it ships: `session` (Mike, voice 23:25-23:28
-Mon 2026-09-28, when the session repo was retired). `session list` and
+Import it, or use the command it ships: `session` (since
+2030-07-29, when the session repo was retired). `session list` and
 `session get` are built on the functions below; `session start` is its own
-package, `sessiontools.start`; `session send` is disabled (2026-09-29).
+package, `sessiontools.start`; `session send` is disabled (2030-07-30).
 
     from sessiontools import sessions, live, find, idle_seconds
     from sessiontools import session_id, current, SESSION_ID_VARS
+    from sessiontools import read_operator, Operator   # who asks, who is privileged
 
 Every function speaks OUR words - busy, not busy, unknown - never a
-harness's. The first driver is `claude_code`; the day a harness changes a
+harness's. `Session.state` is one of three: `busy`, `idle with children`
+(the turn is over, a background agent runs) or `idle`. The first driver is
+`claude_code`; the day a harness changes a
 status word, that driver changes and nothing above it does.
 """
 
@@ -19,8 +22,12 @@ from __future__ import annotations
 from importlib.metadata import PackageNotFoundError, version
 
 from sessiontools.claude_code import (
+    BUSY,
+    IDLE,
+    IDLE_WITH_CHILDREN,
     SESSION_ID_VARS,
     SIDECAR_DIR_ENV,
+    STATES,
     Session,
     current,
     find,
@@ -30,6 +37,7 @@ from sessiontools.claude_code import (
     sessions,
     sidecar_dir,
 )
+from sessiontools.operator import Operator, read_operator
 
 try:
     __version__ = version("sessiontools")
@@ -37,14 +45,20 @@ except PackageNotFoundError:   # a checkout that is not installed
     __version__ = "0+unknown"
 
 __all__ = [
+    "BUSY",
+    "IDLE",
+    "IDLE_WITH_CHILDREN",
     "SESSION_ID_VARS",
     "SIDECAR_DIR_ENV",
+    "STATES",
+    "Operator",
     "Session",
     "__version__",
     "current",
     "find",
     "idle_seconds",
     "live",
+    "read_operator",
     "session_id",
     "sessions",
     "sidecar_dir",

sessiontools-0.2.0/src/sessiontools/account/__init__.py

@@ -0,0 +1,15 @@
+"""`session account`: which of the user's Claude accounts the host is on, and
+the switch between them.
+
+    session account list | status | use NAME | add NAME | remove NAME
+
+`main(argv)` is the group (`cli`). The pieces are each their own module:
+the registry of names (`registry`), the Keychain seam (`keychain`), `use`
+(`use`), `status` and `list` (`status`), `add`/`remove` and the argparse
+group (`cli`), and the token-leak scan (`leakscan`). Nothing here prints,
+logs or stores a token.
+"""
+
+from sessiontools.account.cli import main
+
+__all__ = ["main"]