Skip to main content

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)

Source distribution for ai-session-manager 0.2.0
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)

Table of built distributions (wheels) for ai-session-manager 0.2.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page