cdx-manager 0.5.1 → 0.5.3

package/README.md

@@ -1,6 +1,6 @@
 # CDX Manager
 
-[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.5.1-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
+[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.5.3-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
 
 **Run multiple Codex and Claude sessions from one terminal. Switch between accounts instantly.**
 
@@ -37,7 +37,7 @@ One command to launch any session. Zero auth juggling.
 - **Auth guardrails.** `cdx` checks authentication before launching. If a session is not logged in, it tells you exactly what to run — no silent failures.
 - **Usage at a glance.** `cdx status` shows token usage, 5-hour window quota, weekly quota, and last-updated timestamps for every session in one aligned table.
 - **Session control.** Disable a session without deleting it when an account is temporarily out of credits; disabled sessions remain visible and sort last.
-- **Shared handoff context.** Keep a per-workspace Markdown context and install it into another assistant session before switching providers or accounts.
+- **Shared handoff context.** Keep a per-workspace Markdown context, or build one from a source session transcript, and install it into another assistant session before switching providers or accounts.
 - **Passive status resolution.** Codex status is read from the local Codex app-server rate-limit API when available, with legacy transcript/history parsing kept as a fallback.
 - **Session transcript capture.** Every launch is recorded to a local log file via `script`, giving you a full terminal transcript for each session.
 - **Clean removal.** `cdx rmv` wipes a session and its entire auth directory. No orphaned files, no stale credentials.
@@ -126,7 +126,7 @@ For a specific version:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.sh -o install.sh
-CDX_VERSION=v0.5.1 sh install.sh
+CDX_VERSION=v0.5.3 sh install.sh
 ```
 
 From source:
@@ -250,6 +250,7 @@ cdx status
 | `cdx enable <name> [--json]` | Re-enable a disabled session |
 | `cdx context show\|path\|init\|edit\|clear\|set [text...] [--json]` | Manage the shared Markdown context for the current workspace |
 | `cdx handoff <name> [--json]` | Install the current workspace context into a target session and launch it unless `--json` is used |
+| `cdx handoff <source> <target> [--json]` | Build shared context from the source session's latest launch transcript, install it into the target session, and launch the target unless `--json` is used; supports Codex and Claude targets, including cross-provider handoff |
 | `cdx rmv <name> [--force] [--json]` | Remove a session and its auth data (prompts for confirmation unless `--force`) |
 | `cdx clean [name] [--json]` | Clear launch transcript logs for one session or all sessions |
 | `cdx export <file> [--include-auth] [--sessions a,b] [--passphrase-env VAR] [--force] [--json]` | Export sessions to a portable bundle; `--include-auth` encrypts auth data with a passphrase |

package/changelogs/CHANGELOGS_0_5_2.md

@@ -0,0 +1,42 @@
+# Changelog (`0.5.1 -> 0.5.2`)
+
+Release date: 2026-05-22
+
+## Major Highlights
+
+- Added transcript-based handoff between two sessions of the same provider.
+- Added automatic launch prompting so the target Codex session reads `shared-context.md` and resumes without a manual instruction.
+- Prepared the package metadata for the 0.5.2 release across npm, PyPI, CLI version output, and README install examples.
+
+## Transcript-Based Session Handoff
+
+- Added `cdx handoff <source> <target> [--json]`.
+- Builds a shared context from the source session's latest captured launch transcript.
+- Installs the generated context into the target session as `shared-context.md`.
+- Preserves target account authentication and does not copy source credentials.
+- Rejects same-session and cross-provider handoffs with explicit errors.
+- Truncates very large transcripts to the most recent tail before writing the handoff context.
+
+## Launch and JSON Output
+
+- Passes an initial Codex prompt during handoff launch so the target session is told to read `$CODEX_HOME/shared-context.md`.
+- Adds `launch_prompt` to `cdx handoff ... --json` output for non-interactive integrations.
+- Keeps `--json` handoff mode non-launching while exposing source transcript, generated context, and installed target context paths.
+
+## Documentation
+
+- Updated CLI help and session-list command hints for `cdx handoff <source> <target>`.
+- Updated the README feature summary and command table for transcript-based handoff.
+- Updated the README badge and pinned installer example to `v0.5.2`.
+
+## Validation and Regression Coverage
+
+- Added CLI coverage for source-to-target handoff context generation.
+- Added CLI coverage proving non-JSON handoff launches the target Codex session with the resume prompt.
+- Kept full Python test coverage and Logics lint green.
+
+## Validation and Regression Evidence
+
+- `python -m pytest test -q`
+- `python logics/skills/logics.py lint --require-status`
+- `git diff --check`

package/changelogs/CHANGELOGS_0_5_3.md

@@ -0,0 +1,42 @@
+# Changelog (`0.5.2 -> 0.5.3`)
+
+Release date: 2026-05-23
+
+## Major Highlights
+
+- Added Claude-compatible handoff launch prompting so Claude targets are told exactly which `shared-context.md` file to read.
+- Added Claude launch transcript capture, enabling transcript-based handoff from Claude source sessions.
+- Enabled cross-provider transcript handoff between Codex and Claude sessions.
+- Prepared the package metadata for the 0.5.3 release across npm, PyPI, CLI version output, and README install examples.
+
+## Claude Handoff
+
+- Passes the handoff prompt to Claude as the initial prompt argument during launch.
+- Installs shared context into the target Claude session profile and references the concrete `shared-context.md` path in the prompt.
+- Captures Claude launch transcripts under the session's `claude-home/log/` directory using the same transcript wrapper path as Codex.
+- Preserves Claude `HOME` isolation while running through the transcript wrapper.
+
+## Cross-Provider Handoff
+
+- Allows `cdx handoff <source> <target>` when the source and target providers differ.
+- Keeps generated handoff context provider-neutral while still recording source and target provider metadata.
+- Preserves target account authentication and does not copy source credentials.
+
+## Documentation
+
+- Updated the command table to document Codex and Claude handoff targets, including cross-provider handoff.
+- Updated the README badge and pinned installer example to `v0.5.3`.
+
+## Validation and Regression Coverage
+
+- Added CLI coverage for Claude-to-Claude transcript handoff.
+- Added CLI coverage for Codex-to-Claude handoff.
+- Added CLI coverage proving non-JSON Claude handoff launches Claude with the resume prompt.
+- Updated existing Claude launch coverage to verify transcript-wrapped launches.
+
+## Validation and Regression Evidence
+
+- `python3 -m pytest test/test_cli_py.py test/test_runtime_py.py`
+- `python3 -m pytest`
+- `npm run lint`
+- `npm test`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Terminal session manager for Codex and Claude accounts.",
   "license": "MIT",
   "author": "Alexandre Agostini",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cdx-manager"
-version = "0.5.1"
+version = "0.5.3"
 description = "Terminal session manager for Codex and Claude accounts."
 readme = "README.md"
 requires-python = ">=3.9"

package/src/cli.py

@@ -49,7 +49,7 @@ from .status_view import (
 )
 from .update_check import check_for_update
 
-VERSION = "0.5.1"
+VERSION = "0.5.3"
 
 
 # ---------------------------------------------------------------------------
@@ -68,6 +68,7 @@ def _print_help(use_color=False):
         f"  {_style('cdx status <name> [--json] [--refresh]', '36', use_color)}",
         f"  {_style('cdx context show|path|init|edit|clear|set [text...] [--json]', '36', use_color)}",
         f"  {_style('cdx handoff <name> [--json]', '36', use_color)}",
+        f"  {_style('cdx handoff <source> <target> [--json]', '36', use_color)}",
         f"  {_style('cdx add [provider] <name> [--json]', '36', use_color)}",
         f"  {_style('cdx cp <source> <dest> [--json]', '36', use_color)}",
         f"  {_style('cdx ren <source> <dest> [--json]', '36', use_color)}",

package/src/cli_commands.py

@@ -43,8 +43,9 @@ UPDATE_USAGE = "Usage: cdx update [--check] [--yes] [--json] [--version TAG]"
 EXPORT_USAGE = "Usage: cdx export <file> [--include-auth] [--force] [--json] [--sessions name1,name2] [--passphrase-env VAR]"
 IMPORT_USAGE = "Usage: cdx import <file> [--force] [--json] [--sessions name1,name2] [--passphrase-env VAR]"
 CONTEXT_USAGE = "Usage: cdx context show|path|init|edit|clear|set [text...] [--json]"
-HANDOFF_USAGE = "Usage: cdx handoff <name> [--json]"
+HANDOFF_USAGE = "Usage: cdx handoff <name> [--json] | cdx handoff <source> <target> [--json]"
 API_SCHEMA_VERSION = 1
+HANDOFF_TRANSCRIPT_CHARS = 120000
 
 
 def _local_now_iso():
@@ -67,6 +68,63 @@ def _write_json(ctx, payload):
     ctx["out"](f"{json.dumps(payload, indent=2)}\n")
 
 
+def _latest_launch_transcript_path(session):
+    paths = _list_launch_transcript_paths(session)
+    if not paths:
+        return None
+    return max(paths, key=lambda path: (os.path.getmtime(path), path))
+
+
+def _read_handoff_transcript(path):
+    with open(path, "r", encoding="utf-8", errors="replace") as handle:
+        content = handle.read()
+    if len(content) <= HANDOFF_TRANSCRIPT_CHARS:
+        return content, False
+    return content[-HANDOFF_TRANSCRIPT_CHARS:], True
+
+
+def _build_handoff_context(source, target, transcript_path, transcript, truncated=False):
+    truncation_note = (
+        "Only the tail of the previous transcript is included because the log was large."
+        if truncated else
+        "The previous transcript is included below."
+    )
+    return "\n".join([
+        "# Shared Context",
+        "",
+        "## Goal",
+        f"Resume the work from `{source['name']}` in `{target['name']}` because the source account has no usage left.",
+        "",
+        "## Current State",
+        f"- Source session: `{source['name']}` ({source['provider']})",
+        f"- Target session: `{target['name']}` ({target['provider']})",
+        f"- Transcript source: `{transcript_path}`",
+        f"- {truncation_note}",
+        "",
+        "## Previous Session Transcript",
+        transcript.rstrip(),
+        "",
+        "## Next Steps",
+        "- Read the transcript above.",
+        "- Continue the task from the latest actionable state.",
+        "- Preserve the target account authentication; do not copy source credentials.",
+    ])
+
+
+def _handoff_launch_prompt(session, install=None):
+    if session.get("provider") == "codex":
+        context_ref = "$CODEX_HOME/shared-context.md"
+    else:
+        context_ref = (install or {}).get("target_path") or os.path.join(
+            session.get("authHome") or session.get("sessionRoot") or "~",
+            "shared-context.md",
+        )
+    return (
+        f"Read {context_ref} first, then resume the previous session "
+        "from the latest actionable state. Do not ask me to paste the context again."
+    )
+
+
 def _parse_json_flag(args):
     json_flag = "--json" in args
     cleaned = [arg for arg in args if arg != "--json"]
@@ -914,7 +972,7 @@ def handle_update(rest, ctx):
     return 0
 
 
-def handle_launch(command, ctx):
+def handle_launch(command, ctx, initial_prompt=None):
     json_flag = "--json" in ctx["options"].get("raw_args", [])
     update_notice = ctx.get("update_notice")
     warnings = []
@@ -949,7 +1007,7 @@ def handle_launch(command, ctx):
             ctx["out"](f"{_dim('Tip: cdx status reads Codex rate limits from the local app-server when available.', ctx['use_color'])}\n")
     _run_interactive_provider_command(
         session, "launch", spawn=ctx.get("spawn"), env_override=ctx.get("env"),
-        signal_emitter=ctx.get("signal_emitter")
+        signal_emitter=ctx.get("signal_emitter"), initial_prompt=initial_prompt,
     )
     if json_flag:
         _write_json(ctx, _json_success("launch", message, warnings=warnings, session=ctx["service"]["get_session"](session["name"])))
@@ -958,22 +1016,57 @@ def handle_launch(command, ctx):
 
 def handle_handoff(rest, ctx):
     json_flag, args = _parse_json_flag(rest)
-    if len(args) != 1:
+    if len(args) not in (1, 2):
         raise CdxError(HANDOFF_USAGE)
-    name = args[0]
-    session = ctx["service"]["get_session"](name)
-    if not session:
-        raise CdxError(f"Unknown session: {name}")
-    install = install_context_for_session(ctx["service"]["base_dir"], session, ctx.get("cwd"))
+    if len(args) == 1:
+        name = args[0]
+        session = ctx["service"]["get_session"](name)
+        if not session:
+            raise CdxError(f"Unknown session: {name}")
+        install = install_context_for_session(ctx["service"]["base_dir"], session, ctx.get("cwd"))
+        launch_prompt = _handoff_launch_prompt(session, install)
+        if json_flag:
+            _write_json(ctx, _json_success(
+                "handoff",
+                f"Installed shared context for {name}",
+                context=install,
+                launch_prompt=launch_prompt,
+                session=session,
+            ))
+            return 0
+        text = f"Shared context installed for {name}: {install['target_path']}"
+        ctx["out"](f"{_info(text, ctx['use_color'])}\n")
+        return handle_launch(name, ctx, initial_prompt=launch_prompt)
+
+    source_name, target_name = args
+    if source_name == target_name:
+        raise CdxError("Source and target sessions must be different")
+    source = ctx["service"]["get_session"](source_name)
+    if not source:
+        raise CdxError(f"Unknown session: {source_name}")
+    target = ctx["service"]["get_session"](target_name)
+    if not target:
+        raise CdxError(f"Unknown session: {target_name}")
+    transcript_path = _latest_launch_transcript_path(source)
+    if not transcript_path:
+        raise CdxError(f"No launch transcript found for session: {source_name}")
+    transcript, truncated = _read_handoff_transcript(transcript_path)
+    context = _build_handoff_context(source, target, transcript_path, transcript, truncated=truncated)
+    write_result = write_context(ctx["service"]["base_dir"], context, ctx.get("cwd"))
+    install = install_context_for_session(ctx["service"]["base_dir"], target, ctx.get("cwd"))
+    launch_prompt = _handoff_launch_prompt(target, install)
     if json_flag:
         _write_json(ctx, _json_success(
             "handoff",
-            f"Installed shared context for {name}",
+            f"Prepared handoff from {source_name} to {target_name}",
             context=install,
-            session=session,
+            source_session=source,
+            target_session=target,
+            source_transcript=transcript_path,
+            shared_context=write_result,
+            launch_prompt=launch_prompt,
         ))
         return 0
-    text = f"Shared context installed for {name}: {install['target_path']}"
+    text = f"Handoff prepared from {source_name} to {target_name}: {install['target_path']}"
     ctx["out"](f"{_info(text, ctx['use_color'])}\n")
-    ctx["out"](f"{_dim('Ask the assistant to read shared-context.md if it does not pick it up automatically.', ctx['use_color'])}\n")
-    return handle_launch(name, ctx)
+    return handle_launch(target_name, ctx, initial_prompt=launch_prompt)

package/src/cli_render.py

@@ -129,6 +129,7 @@ def _format_sessions(service, use_color=False):
         f"  {_style('cdx logout <name>', '36', use_color)}",
         f"  {_style('cdx context show', '36', use_color)}",
         f"  {_style('cdx handoff <name>', '36', use_color)}",
+        f"  {_style('cdx handoff <source> <target>', '36', use_color)}",
         f"  {_style('cdx disable <name>', '36', use_color)}",
         f"  {_style('cdx enable <name>', '36', use_color)}",
         f"  {_style('cdx ren <source> <dest>', '36', use_color)}",

package/src/provider_runtime.py

@@ -98,23 +98,29 @@ def _wrap_launch_with_transcript(session, spec, capture_transcript=True, env=Non
     }
 
 
-def _build_launch_spec(session, cwd=None, env_override=None):
+def _build_launch_spec(session, cwd=None, env_override=None, initial_prompt=None):
     cwd = cwd or os.getcwd()
     env_override = env_override or {}
     env = {**os.environ, **env_override}
     if session["provider"] == "claude":
-        return {
+        args = ["--name", session["name"]]
+        if initial_prompt:
+            args.append(initial_prompt)
+        return _wrap_launch_with_transcript(session, {
             "command": "claude",
-            "args": ["--name", session["name"]],
+            "args": args,
             "options": {
                 "cwd": cwd,
                 "env": {**env, **_home_env_overrides(_get_auth_home(session))},
             },
             "label": "claude",
-        }
+        }, env=env)
+    args = ["--no-alt-screen", "--cd", cwd]
+    if initial_prompt:
+        args.append(initial_prompt)
     return _wrap_launch_with_transcript(session, {
         "command": "codex",
-        "args": ["--no-alt-screen", "--cd", cwd],
+        "args": args,
         "options": {
             "env": {**env, "CODEX_HOME": _get_auth_home(session)},
         },
@@ -221,10 +227,11 @@ def _signal_name(sig):
 
 
 def _run_interactive_provider_command(session, action, spawn=None, cwd=None,
-                                      env_override=None, signal_emitter=None):
+                                      env_override=None, signal_emitter=None,
+                                      initial_prompt=None):
     spawn = spawn or subprocess.Popen
     spec = (
-        _build_launch_spec(session, cwd=cwd, env_override=env_override)
+        _build_launch_spec(session, cwd=cwd, env_override=env_override, initial_prompt=initial_prompt)
         if action == "launch"
         else _build_auth_action_spec(session, action, cwd=cwd, env_override=env_override)
     )