Metadata-Version: 2.5
Name: cmgr-cli
Version: 1.0.0
Summary: Universal multi-provider manager and reasoning-blob session bridge for OpenAI Codex CLI
License-Expression: MIT
License-File: LICENSE
Keywords: agentrouter,anthropic,cli,codex,deepseek,ollama,openai,openrouter,session-manager,tui
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: inquirerpy>=0.3.4
Requires-Dist: pydantic>=2.6.0
Requires-Dist: rich>=13.7.0
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: tomli>=2.0.1; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Description-Content-Type: text/markdown

# Codex Manager (`codex-mgr` / `cmgr`)

<div align="center">

```text
 ██████╗ ██████╗ ██████╗ ███████╗██╗  ██╗    ███╗   ███╗ ██████╗ ██████╗ 
██╔════╝██╔═══██╗██╔══██╗██╔════╝╚██╗██╔╝    ████╗ ████║██╔════╝ ██╔══██╗
██║     ██║   ██║██║  ██║█████╗   ╚███╔╝     ██╔████╔██║██║  ███╗██████╔╝
██║     ██║   ██║██║  ██║██╔══╝   ██╔██╗     ██║╚██╔╝██║██║   ██║██╔══██╗
╚██████╗╚██████╔╝██████╔╝███████╗██╔╝ ██╗    ██║ ╚═╝ ██║╚██████╔╝██║  ██║
 ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝╚═╝  ╚═╝    ╚═╝     ╚═╝ ╚═════╝ ╚═╝  ╚═╝
```

**Universal multi-provider bridge, zero-loss config manager, and reasoning-blob healer for OpenAI Codex CLI.**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-3776AB.svg?style=flat-square&logo=python&logoColor=white)](https://www.python.org/downloads/)
[![Codex Ready](https://img.shields.io/badge/Codex%20CLI-Ready-00A67E.svg?style=flat-square&logo=openai&logoColor=white)](https://openai.com)
[![Privacy First](https://img.shields.io/badge/Telemetry-Zero%20%7C%20100%25%20Local-8A2BE2.svg?style=flat-square)](docs/wiki/Security-And-Privacy-Guide.md)
[![Bridge Latency](https://img.shields.io/badge/Bridge%20Latency-%3C%200.1s-brightgreen.svg?style=flat-square)](docs/wiki/Reasoning-Blobs-And-Fernet.md)

[Quickstart](#-quickstart) • [The Problem](#-the-problem) • [Features](#-key-features) • [TUI Showcase](#-interactive-tui-dashboard) • [CLI Commands](#-essential-commands) • [Supported Providers](#-verified-providers--models) • [Documentation Wiki](docs/wiki/Home.md)

</div>

---

## ⚡ The Problem

> *"You spend hours crafting a complex feature using a frontier model. Halfway through, you want to switch to a different provider or model—such as NVIDIA NIM, OpenRouter, OpenCode API, or AgentRouter—without losing your session history or crashing on proprietary tokens."*

Normally, switching providers causes Codex to crash with `HTTP 400 Bad Request: unrecognized parameter 'encrypted_content'` because OpenAI models embed proprietary Fernet-encrypted reasoning blobs. Hand-editing `.jsonl` session rollouts risks data corruption, and modifying `config.toml` risks blowing away custom MCP servers (`kaggle`, `firecrawl`), hooks, and themes.

**`codex-mgr` (`cmgr`) eliminates this friction entirely.** You can switch between different models and providers whenever you want, as many times as you need, seamlessly preserving your full conversation history.

---

## ✨ Key Features

- 🔄 **Universal Session Continuity:** Switch between providers on-demand as many times as you want without losing prompts, code diffs, or tool outputs.
- 🧠 **Encrypted Reasoning Sanitization:** Streaming sanitizer purges proprietary Fernet reasoning tokens in $<0.1$s, preventing `HTTP 400` schema collisions.
- 🔌 **Built-in Anthropic Protocol Adapter:** In-process micro-proxy that translates OpenAI Responses format to native Anthropic Messages on the fly.
- 🎛️ **Granular Model Generation Tuning:** Interactively configure context window caps, maximum output tokens, live streaming toggles, and reasoning effort levels directly within the TUI.
- 🛡️ **Zero-Loss Configuration Patching:** AST-aware updates to `config.toml` that keep custom MCP servers, hook hashes, and desktop UI settings 100% intact.
- ⚡ **Atomic Backups & 1-Click Rollback:** Pre-mutation snapshots created in `~/.codex/backups/sessions/` before every bridge operation with instant rollback.
- 🔒 **Zero Telemetry & Secret Hygiene:** 100% local execution, automatic terminal key masking, and safe configuration bundle export.

---

## 🚀 Quickstart

### 1. Installation

Install via `pip` or `pipx`:

```bash
# Recommended (isolated CLI environment):
pipx install cmgr-cli

# Or via standard pip:
pip install cmgr-cli
```

### 2. Launch the Interactive Dashboard

Simply run `cmgr` in your terminal:

```bash
cmgr
```

---

## 🎮 Interactive TUI Dashboard

<div align="center">

![Codex Manager TUI Preview](assets/images/cmgr-tui-preview.png)

</div>

---

## ⚡ Essential Commands

Prefer direct shell commands? `cmgr` is fully scriptable:

```bash
# Resume most recent session (auto-bridges across providers seamlessly)
cmgr resume --last

# Resume a specific session by title keywords or UUID
cmgr resume "Database refactor"
cmgr resume 019ee539-f672-7a12-acb7-2c2b614c1498

# Switch active provider instantly (preserves custom MCP servers & hooks)
cmgr switch nvidia
cmgr switch openrouter
cmgr switch opencode
cmgr switch openai

# Diagnostic health check (verifies binaries, configs, and connectivity)
cmgr doctor

# Revert a bridged session to its exact original pre-bridge snapshot
cmgr restore 019ee539-f672-7a12-acb7-2c2b614c1498

# Safely share configuration bundles across your team (redacts real API keys)
cmgr export --output team-setup.json --sanitize-keys
cmgr import team-setup.json
```

---

## 🌐 Verified Providers & Models

`codex-mgr` comes pre-configured with battle-tested presets:

- **OpenAI (Official):** Native subscription and OAuth support with frontier reasoning and completion models.
- **Anthropic Direct:** Native Claude integration via built-in Responses $\to$ Messages adapter.
- **NVIDIA NIM:** High-performance GPU inference endpoints for open frontier models.
- **OpenRouter:** Universal multi-model gateway with access to Claude, DeepSeek, GPT-4o, and Llama.
- **OpenCode API:** Endpoints optimized for open-source AI coding agent workflows.
- **AgentRouter:** High-speed multi-model router.
- **DeepSeek (Official):** Official `deepseek-chat` and `deepseek-reasoner` APIs.
- **Local Offline Models:** Full support for self-hosted Ollama and LM Studio.

---

## 🔒 Security & Privacy

- **Zero Telemetry:** 100% local operation. Your code, prompts, and credentials never touch external tracking servers.
- **Automatic Key Masking:** Terminal displays always mask tokens (`sk-...1a2b`).
- **Atomic Pre-Mutation Backups:** Snapshots are created in `~/.codex/backups/sessions/` before any file is touched.

---

## 📚 In-Depth Documentation & Wiki

For architecture deep-dives and technical specifications, visit the documentation wiki:
- 📖 [Wiki Home](docs/wiki/Home.md)
- 🧠 [Encrypted Reasoning Blobs & Fernet Cryptography](docs/wiki/Reasoning-Blobs-And-Fernet.md)
- 🏗️ [Architecture Deep-Dive](docs/wiki/Architecture-Deep-Dive.md)
- 🎛️ [Advanced Model Tuning Guide](docs/wiki/Advanced-Model-Tuning.md)
- 🛠️ [Contributor & Developer Guide (`FORDEV.md`)](FORDEV.md)

---

## 📄 License

Distributed under the **MIT License**. See [LICENSE](LICENSE) for details.
