ai-session-manager
Per-project session persistence for AI CLI tools.
ai-session-manager adds automatic project-scoped resume behavior to supported AI CLIs so you can leave a project and come back without manually reopening the right conversation.
Tested on Linux and Windows.
Wrappers live in a dedicated directory placed before your tools in PATH. Setup leaves installed CLI binaries and their symlinks intact, so tools can still update normally.
Why
Most AI CLIs support sessions, but they do not all resume the same way and they do not all make project-scoped resume automatic. This project adds one consistent wrapper layer across tools.
Today it supports:
| Tool | Auto-resume behavior |
|---|---|
agy |
Starts normally on first run, then stores/discovers a native conversation ID and resumes with agy --conversation <id> |
copilot |
Stores a stable session UUID and launches copilot --session-id <uuid> |
claude |
Stores a managed session UUID, starts with claude --session-id <uuid>, then resumes with claude -r <uuid> |
codex |
Starts normally on first run, then stores/discovers the native session ID and resumes with codex resume <id> |
Project-scoped state lives in:
.ai-session-manager/inside the project root, whether it is a git repo or a plain folder
Existing state is still recognized and migrated from:
.git/ai-session-manager/
Copilot legacy state is also recognized and migrated from:
.git/copilot-session.copilot-session
Requirements
- Python 3.8+
- One or more supported CLIs installed: Antigravity, Copilot, Claude Code, or Codex CLI
Installation
pip install --editable ~/ai-session-manager
Once published:
pip install ai-session-manager
Setup
Install wrappers for every supported tool found in PATH:
ai-session-manager setup
Or target specific tools:
ai-session-manager setup agy copilot claude codex
Setup prints the wrapper location and the shell command needed to activate it. On Linux and macOS, the default location is ~/.local/share/ai-session-manager/bin (or $XDG_DATA_HOME/ai-session-manager/bin). Add it before your native tool directories in your shell profile:
export PATH="$HOME/.local/share/ai-session-manager/bin:$PATH"
Restart your shell, or run hash -r in Bash, then keep using the original tool commands. Run ai-session-manager status to check that the wrappers are active.
On Windows, add %LOCALAPPDATA%\ai-session-manager\bin before the tool directories in your user PATH and open a new terminal. Setup prints the exact directory. Wrappers use the Python interpreter that ran setup; rerun setup if you move or replace that Python environment.
Set AI_SESSION_MANAGER_BIN_DIR to use a different wrapper directory. Keep that setting when running setup, status, or teardown. Existing unrelated files and symlinks in that directory are never overwritten.
Migrating from a previous installation
Older releases renamed native binaries to <tool>-real. Before installing the new wrappers, restore those binaries:
ai-session-manager teardown
ai-session-manager setup
Then activate the new wrapper directory in PATH. Project session state is preserved. If the legacy real binary is missing, reinstall the affected native tool first. Teardown refuses to overwrite a native tool that has already been reinstalled.
Usage
Copilot
cd ~/my-project
copilot
# [ai-session-manager] New session 4f1a2b3c-... (my-project)
cd ~/my-project
copilot
# [ai-session-manager] Resuming session 4f1a2b3c-... (my-project)
AGY
agy
# [ai-session-manager] Starting new Antigravity CLI session (my-project)
agy
# [ai-session-manager] Resuming session 123e4567-... (my-project)
Claude
claude
# [ai-session-manager] New session 4f1a2b3c-... (my-project)
claude
# [ai-session-manager] Resuming session 4f1a2b3c-... (my-project)
Codex
codex
# [ai-session-manager] Starting new Codex session (my-project)
codex
# [ai-session-manager] Resuming session 019e94b3-... (my-project)
Supported tools are still fully usable with their own native session commands. If you pass an explicit resume or session-management flag/subcommand, the wrapper gets out of the way.
For example:
agy --conversation 123e4567-e89b-12d3-a456-426614174000
copilot --resume
claude -r my-session
codex resume --last
Start fresh in the current project
ai-session-manager reset
Or reset one tool only:
ai-session-manager reset claude
Commands
| Command | Description |
|---|---|
ai-session-manager setup [tools...] |
Install wrappers for all detected or selected tools |
ai-session-manager teardown [tools...] |
Remove dedicated wrappers, or restore legacy renamed binaries |
ai-session-manager status [tools...] |
Show paths, saved session IDs, and actionable installation/state problems |
ai-session-manager reset [tools...] |
Delete persisted wrapper state for the current project |
State layout
project root:
.ai-session-manager/
copilot.json
claude.json
codex.json
agy.json
Copilot and Claude store an exact managed session identifier in their state files from the first launch.
AGY and Codex store the tool's own native conversation/session identifier once the wrapper can discover it from local history after a successful run. If no exact project session can be found, they start fresh. They never automatically resume an unverified latest session. A missing Claude transcript is started with its managed session ID rather than resuming a different conversation.
State is written atomically. Invalid JSON or incompatible state stops the launch with a recovery message and leaves the original file intact. Back up that file if needed, then run ai-session-manager reset <tool> to start fresh.
Only one managed session per tool and project may run at a time. A second launch or reset reports that the session is busy. Different tools and different projects can run independently. Lock files remain in the state directory; the operating system releases the lock when its owning process exits. Native explicit session commands bypass this management, so you can still open an independent conversation intentionally.
status is read-only and returns a nonzero exit code for detected problems, including wrappers hidden by another PATH entry, missing native tools, invalid state, and missing saved transcripts where they can be checked. Fix the reported problem and rerun status.
Platform details
| Linux | macOS | Windows | |
|---|---|---|---|
| Wrapper file | tool name (shell script) | tool name (shell script) | tool .cmd wrapper |
| Native binary | Unchanged | Unchanged | Unchanged |
| Managed process launch | Subprocess held under a project lock | Subprocess held under a project lock | Subprocess held under a project lock |
Project structure
ai-session-manager/
├── pyproject.toml
├── README.md
└── src/
├── ai_session_manager/
│ ├── wrapper.py
│ ├── installation.py
│ └── cli.py
Reinstalling a tool CLI
Native tools can be updated or reinstalled in their normal locations. Wrappers discover the current native executable through PATH, skipping other session-manager wrappers. If the wrapper is no longer active, inspect the PATH order:
ai-session-manager status copilot
Uninstall
ai-session-manager teardown
pip uninstall ai-session-manager
Remove the wrapper directory from your shell profile or Windows user PATH if you no longer need it.
Development
The test suite uses the standard library and temporary directories; it does not need installed AI CLIs:
PYTHONPATH=src python -m unittest discover -s tests -v
On PowerShell, set $env:PYTHONPATH = "src" before running the Python command. CI runs on Linux and Windows with Python 3.8 and 3.12.
License
MIT
Metadata
Release files for ai-session-manager 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ai_session_manager-0.2.0.tar.gz | 22.8 kB | With provenance | Details for ai_session_manager-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ai_session_manager-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for ai_session_manager-0.2.0-py3-none-any.whl |
Total release size: 39.1 kB
Release files / ai_session_manager-0.2.0.tar.gz
| Download URL | ai_session_manager-0.2.0.tar.gz |
|---|---|
| Size | 22.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
83e7abbe6605c1018c61cc94d5d4c7e0e3b7dfc35c8808931053d3405f8ecd8b
|
|
BLAKE2b-256 checksum How to use checksums |
a56a2e0ca92524e4426956ae04f63fe523b6a0217c41d1c743dfc9896da797d4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.
Transparency logRelease files / ai_session_manager-0.2.0-py3-none-any.whl
| Download URL | ai_session_manager-0.2.0-py3-none-any.whl |
|---|---|
| Size | 16.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5d45328d926a6edd26e41cb4932e0c8208a96da1e487163ca7b4f6fc74f8bfe9
|
|
BLAKE2b-256 checksum How to use checksums |
e121d71111eec9320cf9fc1c930e33be9dde2859c30399b08ee38524e946f21a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.
Transparency logSecurity for ai-session-manager 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for ai_session_manager-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.