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.
