CodexSessionManager

A safety-first GUI and CLI for auditing, backing up, cleaning, importing, and trimming Codex conversations.
English · 简体中文 · Bilingual GUI guide

Long-running Codex work spreads conversations across projects and lets context grow unchecked. CodexSessionManager brings review, encrypted backup, guarded cleanup, and non-destructive context trimming into one auditable desktop tool.

✨ Key features

• Group and search Codex conversations by project, activity, source, and relationship.
• Create streaming, age-encrypted .csmbackup archives with full integrity verification.
• Plan archive, restore, import, trim, and purge operations before any write occurs.
• Reduce context through a derived task while keeping the original conversation unchanged.
• Review model-visible content, Markdown, hidden tags, dependencies, and estimated token savings.
• Scan locally for likely credentials and personal data; matched text can be highlighted for review.
• Use the GUI, CLI, explicit Codex Skill, or optional fail-open PreCompact/PostCompact Hooks.
• Run self-contained macOS arm64 and Windows x64 builds without installing Python, Qt, uv, or age.

Safer defaults at a glance

Need	Ad hoc workflow	CodexSessionManager
Review many conversations	Search projects and raw history separately	Project-grouped inventory and timeline review
Clean old work	Delete or archive without a reproducible decision record	Dry-run plan, fingerprint checks, descendant expansion, then App Server write
Reduce context	Rewrite history or accept all-or-nothing compaction	Keep, exclude, summarize, or protect content in a new derived task
Back up and migrate	Copy internal files and hope versions match	Encrypted logical records, checksums, provenance, verification, and new IDs on restore

⚙️ Quick start

Warning

v1.0.0 is a test prerelease. The macOS build is ad-hoc signed and not notarized; the Windows build is unsigned. Verify the matching SHA-256 file before launch and do not treat either build as production-ready.

Requirements

• Release build: Apple Silicon macOS or Windows x64, plus a local Codex App/CLI installation for App Server access.
• Source build: uv and Git. uv manages the pinned CPython 3.13.14 environment.

1. Download a test build

Download the archive and its .sha256 file from the v1.0.0 test release:

• macOS arm64 ZIP · SHA-256
• Windows x64 ZIP · SHA-256

2. Verify and launch

macOS arm64:

shasum -a 256 -c CodexSessionManager-macOS-arm64-1.0.0-test.zip.sha256
ditto -x -k CodexSessionManager-macOS-arm64-1.0.0-test.zip .
"./CodexSessionManager.app/Contents/MacOS/CodexSessionManager" cli doctor
"./CodexSessionManager.app/Contents/MacOS/CodexSessionManager"

Windows x64 PowerShell:

$Archive = ".\CodexSessionManager-Windows-x64-1.0.0-test.zip"
$Expected = ((Get-Content "$Archive.sha256").Trim() -split '\s+')[0]
$Actual = (Get-FileHash $Archive -Algorithm SHA256).Hash
if ($Actual.ToLower() -ne $Expected.ToLower()) { throw "SHA-256 mismatch" }
Expand-Archive $Archive -DestinationPath . -Force
PowerShell -NoProfile -ExecutionPolicy Bypass -File .\CodexSessionManager-Windows-x64\Install-CodexSessionManager.ps1
& "$env:LOCALAPPDATA\CodexSessionManager\CodexSessionManager.exe"

Or run the basic GUI and CLI directly from source:

uv sync --locked --compile-bytecode
uv run csm --help
uv run CodexSessionManager

Backup verification and a complete doctor check also require an age executable. The platform build scripts fetch and verify the pinned binary; development environments may instead provide CSM_AGE_BIN.

3. Try the minimum GUI workflow

1. Search for a project/conversation, or enter a complete conversation ID.
2. Select a turn or item, then choose Keep, Exclude, Summary, or Protect.
3. Use Save plan to store the reviewed plan without changing Codex, or Create trimmed task to create a new derived conversation.

Build and release status

Note

The repository's code was generated entirely by ChatGPT. Human review, automated tests, and target-platform validation are still required; inspect the code independently before relying on write operations.

Contents

• ✨ Key features
• ⚙️ Quick start
• 📌 Use cases
• Safety model
• 📖 Documentation
• 🔧 Configuration
• Development, testing, and packaging
• ❓ FAQ
• 🤝 Contributing
• 📄 License

📌 Use cases

Scenario	What CSM provides
Many long-running Codex projects	One project-grouped list with conversation search, relative activity, multi-selection, and relationship tracking
Context approaching compaction	Manual review or an optional PreCompact prompt before native compaction proceeds
Old or inactive conversations	Rule-based candidates, dry-run archive plans, batch limits, and human confirmation
Backup or account migration	Encrypted CSM backups, logical restore, Codex rollout import, and ChatGPT export branch expansion
Sensitive-data review	Local deterministic scanning and red highlighting without uploading conversation content
Auditable maintenance	Immutable plan hashes, source fingerprints, capability checks, and a CSM-owned audit chain

The primary audience is developers and maintainers who use Codex across multiple repositories, keep long-lived conversations, or need a reviewable alternative to manipulating Codex's internal storage.

Safety model

• Online Codex reads and writes use the official App Server. CSM does not rewrite Codex JSONL or SQLite.
• Unknown, incomplete, or unaudited protocol capabilities disable writes and leave inventory, backup, verification, and planning available.
• Every write consumes a SHA-256-bound plan and re-checks state, content fingerprints, capabilities, expiry, and spawned descendants.
• Automatic operations stop at archive. Permanent purge requires a separate plan, verified backup evidence, trusted archive history, and explicit confirmation.
• Context trimming creates a new task. The source task remains unchanged and system/developer instructions are reloaded from the current project.
• Tool calls/results and file changes/verifications are retained or summarized as groups, not split into unsafe fragments.
• Hook failures are fail-open: timeout, close, crash, or launch failure continues native compaction.

📖 Documentation

Stable user installation

Launching the extracted macOS App directly does not install the Skill or CLI launcher. From a checkout matching the release tag, install it into the stable user path with:

scripts/install_user.sh /absolute/path/to/CodexSessionManager.app
~/.local/bin/csm doctor

The installer atomically replaces ~/Applications/CodexSessionManager.app, retains the previous App for rollback, creates ~/.local/bin/csm, and links the bundled Skill. The Windows installer shown in Quick start provides the equivalent user-level installation under %LOCALAPPDATA%\CodexSessionManager. Neither installer enables Hooks automatically.

GUI workflow

_{12-second deterministic demo · fictional IDs, paths, repository, and conversation content}

1. Projects & Tasks groups conversations by project cwd or Git remote. Search and complete-ID loading share one field; multi-selection supports guarded batch actions.
2. Timeline shows model-visible turns/items and hides empty internal events by default. Token totals use compact units.
3. Context is editable and supports hidden-tag display, segmented source rendering, Markdown preview, and local sensitive-range highlighting.
4. Trim actions apply keep, exclude, summary, or protect. Hard-protected requests, active turns, goals, unresolved errors, and unknown items cannot be silently removed.

Saving a plan only persists the reviewed TrimPlan; it does not write to Codex. Creating a trimmed task first revalidates the plan, waits for the source to become idle, and then creates a new derived task.

CLI workflows

csm doctor
csm threads list
csm threads show CONVERSATION_ID --include-content
csm trim review --thread-id CONVERSATION_ID
csm audit show

Create and verify an encrypted backup before planning an archive:

csm backup create backup.csmbackup \
  --thread CONVERSATION_ID \
  --recipient age1... \
  --identity /secure/path/identity.txt
csm cleanup plan --action archive --older-than-days 90
csm cleanup apply PLAN.json --confirm PLAN_ID

Important command groups:

Command	Purpose
csm threads list|show	Read-only inventory and content inspection
csm backup create|verify	Streaming age-encrypted backup and full verification
csm cleanup plan|apply	Reversible archive/unarchive workflow
csm purge plan|apply	Separately gated permanent deletion workflow
csm restore plan|apply	Logical restore with new conversation IDs
csm import {chatgpt|codex} ...	Plan and apply imports from official ChatGPT exports or Codex rollout data
csm trim review|suggest|apply	GUI/manual review, local suggestions, and derived trimming
csm hook install|status|uninstall	Optional PreCompact/PostCompact integration
csm audit show|verify	Inspect and verify the CSM audit chain

Passphrase mode reads the secret directly from the terminal. Do not place backup passphrases in command arguments, environment variables, logs, issues, or model context. GUI and unattended workflows use age recipients instead.

Codex Skill

The stable installers place manage-codex-sessions under ~/.agents/skills. Restart Codex, then invoke it explicitly:

$manage-codex-sessions open context trimming for this conversation

The Skill does not run automatically during ordinary coding work. It resolves the stable csm launcher or bundled executable and follows the same plan and safety gates as the GUI and CLI.

Optional Hooks

csm hook status
csm hook install --yes
csm hook uninstall --yes

Installation does not silently enable Hooks. After installation, review and trust the exact command in Codex /hooks. PreCompact shows a lightweight prompt; it returns continue: false only after a plan is safely persisted, and never creates a derived task inside the active turn.

Further reading

• Bilingual GUI guide (PPTX)
• Skill command workflows
• Skill safety invariants
• v1.0.0 test-release notes
• Project development constraints

🔧 Configuration

CSM uses platform-native user directories by default. Environment variables are intended for explicit account selection, isolated tests, or advanced installations.

Variable	Purpose
CSM_CODEX_HOME	Explicit Codex data root used by CSM
CODEX_HOME	Codex's official data-root override; if both home variables are set, they must resolve to the same path
CSM_CODEX_BIN	Absolute path or command name for the Codex CLI/App Server launcher
CSM_APP_PATH	Stable installed App root or executable used when generating Hook commands
CSM_DATA_DIR	Plans, imports, backups, and audit database root
CSM_CONFIG_DIR	CSM configuration root
CSM_CACHE_DIR	Cache root
CSM_LOG_DIR	Application and Hook log root
CSM_AGE_BIN	Development-only age executable override; standalone builds use their verified bundled binary

If CSM_CODEX_HOME and CODEX_HOME point to different roots, every entry point refuses to continue. This prevents one account's task state from being combined with another account's plans or audit evidence.

Stable installation paths are ~/Applications/CodexSessionManager.app on macOS and %LOCALAPPDATA%\CodexSessionManager on Windows. Hooks must target these stable locations, never a source checkout or .venv.

Development, testing, and packaging

Development setup

git clone https://github.com/Aiyawoc/CodexSessionManager.git
cd CodexSessionManager
uv sync --locked --compile-bytecode
scripts/check.sh

scripts/check.sh verifies generated Qt files, Ruff formatting/lint, strict mypy, offscreen PySide6 tests, and the Skill contract. More focused workflows are available for source, installation, Skill, Hook, and lifecycle checks:

scripts/test_source_workflow.sh
scripts/test_install_workflow.sh dist/CodexSessionManager.app
scripts/test_skill_workflow.sh dist/CodexSessionManager.app
scripts/test_hook_workflow.sh dist/CodexSessionManager.app
scripts/test_full_workflow.sh

These checks use isolated temporary data. They do not replace real-account App Server testing, physical-device UI testing, signing/notarization, SmartScreen reputation, or production acceptance.

To test a macOS App against a copy of the current Codex home:

scripts/install_test_app.sh
scripts/launch_test_app.sh /absolute/path/printed/as/TEST_ROOT

The copied test root may contain authentication data. Close Codex before copying when possible, and remove only the exact TEST_ROOT printed by the installer.

Desktop packaging

macOS arm64, on real Apple Silicon hardware:

scripts/build_macos_app.sh
scripts/accept_macos_bundle.sh dist/CodexSessionManager.app

Windows x64, on Windows AMD64 or the manual GitHub Actions workflow:

.\scripts\check_windows.ps1
.\scripts\build_windows_app.ps1 -Version 1.0.0

Both builds use pyside6-deploy / Nuitka standalone mode and include pinned Python, Qt, plugins, application dependencies, and a verified age binary. Formal public distribution still requires Developer ID signing/notarization/stapling on macOS and an appropriate Authenticode signature on Windows.

❓ FAQ

Does CSM modify Codex's JSONL or SQLite files?

No. Online reads and writes use the App Server. Raw rollout data may be retained inside an encrypted disaster-recovery backup, but CSM does not treat direct internal-file editing as a supported restore or trimming API.

Do end users need Python, uv, Qt, or age?

No for standalone builds. The macOS and Windows bundles carry their own runtime and verified age executable. Source development requires uv; uv obtains the pinned Python version without changing the system Python.

Why does Gatekeeper or SmartScreen warn about the download?

v1.0.0 is explicitly a test release. macOS is ad-hoc signed and not notarized; Windows has no Authenticode signature or SmartScreen reputation. Verify the published checksum and source before evaluating it. Do not bypass a warning for an unverified file.

Why is the conversation list empty or App Server unavailable?

Run csm doctor. Confirm the Codex CLI is installed and reachable, or set CSM_CODEX_BIN to its absolute path. Also verify that CODEX_HOME and CSM_CODEX_HOME refer to the intended, identical data root.

What is the difference between “Save plan” and “Create trimmed task”?

Save plan only writes a reviewed immutable plan to CSM's data directory. Create trimmed task revalidates that plan and creates a new Codex task; the original remains unchanged.

Can CSM permanently delete conversations?

Yes, but never automatically. Purge requires a separate immutable plan, a verified encrypted backup, trusted archive evidence, waiting-period checks, descendant expansion, and explicit human confirmation. Archive is the maximum automatic action.

Does sensitive scan prove that a secret is valid or leaked?

No. It uses deterministic local patterns and checksum validation where applicable. It can produce false positives and miss unusual formats; it is a review aid, not a credential-validation service.

Can I merge conversations from another account?

CSM can plan logical imports from CSM backups, Codex rollout data, and official ChatGPT exports. Imported conversations receive new IDs, keep source provenance, and never replay tool calls. Uncertain project mappings remain quarantined for review.

Which platforms are currently released?

The test release covers macOS arm64 and Windows x64. There is no released Intel macOS or Linux build. Target-platform acceptance must be performed on the corresponding real platform or hosted Windows runner.

🤝 Contributing

Focused issues and pull requests are welcome.

1. Describe the problem, expected behavior, reproduction scope, and platform without attaching credentials or real conversation data.
2. Add or update tests for behavior changes; keep GUI, CLI, Skill, and Hook entry points on the shared plan/safety layer.
3. Run scripts/check.sh and the relevant focused workflow before opening a pull request.
4. Update both README files when user-visible commands, platform support, or safety behavior changes.

Read AGENTS.md before making implementation changes. Do not add direct Codex JSONL/SQLite writes, implicit network installation in Hooks, or write paths that bypass immutable plans.

The current project code was generated entirely by ChatGPT, but generated code is not self-validating. Contributions of any origin still require human review, reproducible tests, and honest target-environment evidence.

📄 License

CodexSessionManager is released under the MIT License. Bundled dependencies and tools retain their own licenses; see THIRD_PARTY_NOTICES.md.

⭐ If this project is useful to you, consider giving it a Star. Continued maintenance and iteration are planned.