ai-sessions 3.0.0__tar.gz

ai_sessions-3.0.0/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+build/
+dist/
+
+# Never commit local provider conversations, credentials, or utility state.
+.codex/
+.claude/
+.config/ai-sessions/
+.cache/ai-sessions/
+state.json
+config.toml
+*.sqlite
+*.sqlite-shm
+*.sqlite-wal
+*.jsonl

ai_sessions-3.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew VanDyke
+
+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.

ai_sessions-3.0.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.5
+Name: ai-sessions
+Version: 3.0.0
+Summary: A friendly terminal browser for local Codex CLI and Claude Code sessions
+Project-URL: Homepage, https://github.com/vandyand/ai-sessions
+Project-URL: Repository, https://github.com/vandyand/ai-sessions
+Project-URL: Issues, https://github.com/vandyand/ai-sessions/issues
+Author-email: Andrew VanDyke <vandyand@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude-code,codex,sessions,terminal,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console :: Curses
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: psutil>=5.9
+Requires-Dist: windows-curses>=2.4.1; sys_platform == 'win32'
+Description-Content-Type: text/markdown
+
+# ai-sessions
+
+`ai-sessions` is a searchable terminal browser for local [Codex CLI](https://developers.openai.com/codex/cli/) and Claude Code conversations. It indexes each provider's existing on-disk history without modifying transcripts or provider databases.
+
+It runs as `sessions` on Linux and native Windows PowerShell.
+
+## Features
+
+- One navigable list for Codex and Claude sessions
+- Search and filters for provider, directory, origin, open state, and visibility
+- Human, cross-provider, and subagent/automation origin labels
+- Started and updated timestamps plus user-message counts across compactions
+- Utility-local rename and hide operations that never alter vendor data
+- Detection of currently open sessions on Linux and Windows
+- tmux pane and desktop-terminal focus on Linux when the environment exposes it
+- Safe, dangerous, and custom launch profiles
+- Native paths and argument handling on both operating systems
+
+Windows Terminal does not expose a stable session-ID-to-tab interface. On Windows, open sessions are identified, but exact tab focusing is intentionally not attempted.
+
+## Requirements
+
+- Python 3.11 or newer
+- Codex CLI, Claude Code, or both
+- Linux or native Windows PowerShell
+
+The Windows-only `windows-curses` dependency is installed automatically. `psutil` is used for portable process inspection.
+
+## Install
+
+From a checkout:
+
+```bash
+python -m pip install .
+sessions
+```
+
+With `pipx`:
+
+```bash
+pipx install .
+sessions
+```
+
+From PyPI:
+
+```bash
+pipx install ai-sessions
+```
+
+On Windows, `py -m pip` can be used in place of `python -m pip`.
+
+## Everyday use
+
+Run `sessions`, navigate with the arrow keys or `j`/`k`, and press Enter to resume the selected conversation.
+
+| Key | Action |
+| --- | --- |
+| `Ctrl-F` or `/` | Start search mode |
+| `Tab` | Cycle provider filter |
+| `o` | Cycle Human, Cross, Agent, and All origins |
+| `v` | Cycle visible, hidden, and all sessions |
+| `d` | Choose a directory |
+| `s` | Cycle sort order |
+| `p` | Cycle Safe, Dangerous, and Custom launch modes |
+| `r` | Rename locally |
+| `h` | Hide or restore locally |
+| `Ctrl-R` | Refresh |
+| `?` | Show complete help |
+
+Useful noninteractive forms include:
+
+```bash
+sessions --list --tool codex
+sessions --list --query "is:open dir:my-project"
+sessions --list --visibility hidden
+sessions --resume SESSION_ID
+sessions --resume SESSION_ID --dry-run
+```
+
+## Launch safety
+
+The package defaults to `safe`. This leaves approval and sandbox behavior to each provider's normal configuration:
+
+```text
+claude --resume SESSION_ID
+codex resume SESSION_ID
+```
+
+Dangerous mode adds the providers' explicit bypass flags:
+
+```text
+claude --dangerously-skip-permissions --resume SESSION_ID
+codex --dangerously-bypass-approvals-and-sandbox resume SESSION_ID
+```
+
+These options disable important protections. Use them only where you have consciously accepted that risk.
+
+Set a persistent mode from the command line:
+
+```bash
+sessions --set-launch-mode safe
+sessions --set-launch-mode dangerous
+```
+
+Use `--launch-mode` for a one-time override. The active mode is always displayed in the interface header.
+
+## Configuration
+
+Configuration is stored in:
+
+- Linux: `~/.config/ai-sessions/config.toml`
+- Windows: `%APPDATA%\ai-sessions\config.toml`
+
+The optional custom profile uses structured argument arrays, avoiding shell interpolation:
+
+```toml
+[launch]
+mode = "custom"
+claude_command = ["claude"]
+codex_command = ["codex"]
+
+[launch.custom]
+claude_args = ["--permission-mode", "acceptEdits"]
+codex_args = ["--sandbox", "workspace-write", "--ask-for-approval", "on-request"]
+```
+
+Rename/hide state is kept alongside the configuration as `state.json`. Caches use `~/.cache/ai-sessions` on Linux and `%LOCALAPPDATA%\ai-sessions` on Windows. Environment overrides are available through `AI_SESSIONS_CONFIG_FILE`, `AI_SESSIONS_STATE_FILE`, `CODEX_HOME`, and `CLAUDE_CONFIG_DIR`.
+
+## How open-session detection works
+
+- Claude Code publishes a live PID/session registry.
+- Codex on Linux holds per-thread writer locks.
+- Codex on Windows records thread IDs alongside process IDs in its local log database.
+- Linux focus support follows the process into tmux and then uses `wmctrl`/`xdotool` when available.
+
+Detection is best-effort and read-only. The utility never writes to provider storage.
+
+## Privacy
+
+No transcripts, caches, credentials, local names, or hidden-session state belong in this repository. The defensive `.gitignore` excludes common provider and local data paths.
+
+## Development
+
+```bash
+python -m unittest discover -s tests -v
+python -m build
+```
+
+CI exercises Python 3.11–3.13 on Ubuntu and Windows.

ai_sessions-3.0.0/README.md

@@ -0,0 +1,150 @@
+# ai-sessions
+
+`ai-sessions` is a searchable terminal browser for local [Codex CLI](https://developers.openai.com/codex/cli/) and Claude Code conversations. It indexes each provider's existing on-disk history without modifying transcripts or provider databases.
+
+It runs as `sessions` on Linux and native Windows PowerShell.
+
+## Features
+
+- One navigable list for Codex and Claude sessions
+- Search and filters for provider, directory, origin, open state, and visibility
+- Human, cross-provider, and subagent/automation origin labels
+- Started and updated timestamps plus user-message counts across compactions
+- Utility-local rename and hide operations that never alter vendor data
+- Detection of currently open sessions on Linux and Windows
+- tmux pane and desktop-terminal focus on Linux when the environment exposes it
+- Safe, dangerous, and custom launch profiles
+- Native paths and argument handling on both operating systems
+
+Windows Terminal does not expose a stable session-ID-to-tab interface. On Windows, open sessions are identified, but exact tab focusing is intentionally not attempted.
+
+## Requirements
+
+- Python 3.11 or newer
+- Codex CLI, Claude Code, or both
+- Linux or native Windows PowerShell
+
+The Windows-only `windows-curses` dependency is installed automatically. `psutil` is used for portable process inspection.
+
+## Install
+
+From a checkout:
+
+```bash
+python -m pip install .
+sessions
+```
+
+With `pipx`:
+
+```bash
+pipx install .
+sessions
+```
+
+From PyPI:
+
+```bash
+pipx install ai-sessions
+```
+
+On Windows, `py -m pip` can be used in place of `python -m pip`.
+
+## Everyday use
+
+Run `sessions`, navigate with the arrow keys or `j`/`k`, and press Enter to resume the selected conversation.
+
+| Key | Action |
+| --- | --- |
+| `Ctrl-F` or `/` | Start search mode |
+| `Tab` | Cycle provider filter |
+| `o` | Cycle Human, Cross, Agent, and All origins |
+| `v` | Cycle visible, hidden, and all sessions |
+| `d` | Choose a directory |
+| `s` | Cycle sort order |
+| `p` | Cycle Safe, Dangerous, and Custom launch modes |
+| `r` | Rename locally |
+| `h` | Hide or restore locally |
+| `Ctrl-R` | Refresh |
+| `?` | Show complete help |
+
+Useful noninteractive forms include:
+
+```bash
+sessions --list --tool codex
+sessions --list --query "is:open dir:my-project"
+sessions --list --visibility hidden
+sessions --resume SESSION_ID
+sessions --resume SESSION_ID --dry-run
+```
+
+## Launch safety
+
+The package defaults to `safe`. This leaves approval and sandbox behavior to each provider's normal configuration:
+
+```text
+claude --resume SESSION_ID
+codex resume SESSION_ID
+```
+
+Dangerous mode adds the providers' explicit bypass flags:
+
+```text
+claude --dangerously-skip-permissions --resume SESSION_ID
+codex --dangerously-bypass-approvals-and-sandbox resume SESSION_ID
+```
+
+These options disable important protections. Use them only where you have consciously accepted that risk.
+
+Set a persistent mode from the command line:
+
+```bash
+sessions --set-launch-mode safe
+sessions --set-launch-mode dangerous
+```
+
+Use `--launch-mode` for a one-time override. The active mode is always displayed in the interface header.
+
+## Configuration
+
+Configuration is stored in:
+
+- Linux: `~/.config/ai-sessions/config.toml`
+- Windows: `%APPDATA%\ai-sessions\config.toml`
+
+The optional custom profile uses structured argument arrays, avoiding shell interpolation:
+
+```toml
+[launch]
+mode = "custom"
+claude_command = ["claude"]
+codex_command = ["codex"]
+
+[launch.custom]
+claude_args = ["--permission-mode", "acceptEdits"]
+codex_args = ["--sandbox", "workspace-write", "--ask-for-approval", "on-request"]
+```
+
+Rename/hide state is kept alongside the configuration as `state.json`. Caches use `~/.cache/ai-sessions` on Linux and `%LOCALAPPDATA%\ai-sessions` on Windows. Environment overrides are available through `AI_SESSIONS_CONFIG_FILE`, `AI_SESSIONS_STATE_FILE`, `CODEX_HOME`, and `CLAUDE_CONFIG_DIR`.
+
+## How open-session detection works
+
+- Claude Code publishes a live PID/session registry.
+- Codex on Linux holds per-thread writer locks.
+- Codex on Windows records thread IDs alongside process IDs in its local log database.
+- Linux focus support follows the process into tmux and then uses `wmctrl`/`xdotool` when available.
+
+Detection is best-effort and read-only. The utility never writes to provider storage.
+
+## Privacy
+
+No transcripts, caches, credentials, local names, or hidden-session state belong in this repository. The defensive `.gitignore` excludes common provider and local data paths.
+
+## Development
+
+```bash
+python -m unittest discover -s tests -v
+python -m build
+```
+
+CI exercises Python 3.11–3.13 on Ubuntu and Windows.

ai_sessions-3.0.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ai-sessions"
+version = "3.0.0"
+description = "A friendly terminal browser for local Codex CLI and Claude Code sessions"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Andrew VanDyke", email = "vandyand@gmail.com" }]
+keywords = ["codex", "claude-code", "terminal", "sessions", "tui"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console :: Curses",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: Microsoft :: Windows",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development",
+]
+dependencies = [
+  "psutil>=5.9",
+  "windows-curses>=2.4.1; sys_platform == 'win32'",
+]
+
+[project.urls]
+Homepage = "https://github.com/vandyand/ai-sessions"
+Repository = "https://github.com/vandyand/ai-sessions"
+Issues = "https://github.com/vandyand/ai-sessions/issues"
+
+[project.scripts]
+sessions = "ai_sessions.app:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ai_sessions"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/ai_sessions", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I"]

ai_sessions-3.0.0/src/ai_sessions/__init__.py

@@ -0,0 +1,3 @@
+"""Browse and resume local Codex CLI and Claude Code sessions."""
+
+__version__ = "3.0.0"

ai_sessions-3.0.0/src/ai_sessions/__main__.py

@@ -0,0 +1,3 @@
+from .app import main
+
+raise SystemExit(main())