Skip to content

Dianel555/DSkills / skills/codex-cc

codex-cc

Unverified

Delegates coding tasks from Codex to local Claude Code in print mode while preserving Claude's normal runtime customizations by default. Use when: (1) You want Codex to call Claude Code locally, (2) You need Claude-side skills, plugins, MCP servers, custom commands, CLAUDE.md rules, or workspace settings to stay active, (3) You want resumable Claude sessions from Codex via SESSION_ID, (4) You need thin `claude mcp` / `claude plugin` passthrough from the same bridge.

FileKindSize
README.mdmarkdown4.0 KB
SKILL.mdskill md3.6 KB
ruff.tomlconfig656 B
scripts/claude_bridge.pyscript21.0 KB
tests/test_claude_bridge.pyscript24.7 KB

scripts/claude_bridge.py

View on GitHub
"""Claude Bridge Script for Codex-facing DSkills.

Wraps the local Claude Code CLI in a stable JSON envelope so Codex can
delegate work while preserving Claude's normal runtime customizations.
"""

from __future__ import annotations

import argparse
import contextlib
import json
import os
import queue
import shutil
import subprocess
import sys
import tempfile
import threading
import time
import uuid
from collections.abc import Iterator, Sequence
from pathlib import Path

PERMISSION_MODES = [
    "acceptEdits",
    "auto",
    "bypassPermissions",
    "manual",
    "dontAsk",
    "plan",
]


def _is_windows() -> bool:
    """Platform seam: patched in tests so no test mutates the shared os.name."""
    return os.name == "nt"


def _windows_bin_dir_candidates(home: str, env: dict) -> list[str]:
    """Candidate launcher directories for Windows, native installer first.

    Returns plain strings so the ordering contract stays testable on any platform.
    """
    candidates = [os.path.join(home, ".local", "bin")]
    if prefix := env.get("NPM_CONFIG_PREFIX") or env.get("npm_config_prefix"):
        candidates.append(prefix)
    if appdata := env.get("APPDATA"):
        candidates.append(os.path.join(appdata, "npm"))
    if localappdata := env.get("LOCALAPPDATA"):
        candidates.append(os.path.join(localappdata, "npm"))
    if programfiles := env.get("ProgramFiles"):
        candidates.append(os.path.join(programfiles, "nodejs"))
    return candidates


def _get_windows_bin_paths() -> list[Path]:
    """Resolve the Windows launcher candidate directories to existing paths."""
    if not _is_windows():
        return []
    return [Path(entry) for entry in _windows_bin_dir_candidates(str(Path.home()), os.environ)]


def _augment_path_env(env: dict) -> None:
    """Prepend known Claude Code install directories to PATH if missing."""
    if not _is_windows():
        return
    path_key = next((key for key in env if key.upper() == "PATH"), "PATH")
    path_entries = [entry for entry in env.get(path_key, "").split(os.pathsep) if entry]
    lower_set = {entry.lower() for entry in path_entries}
    for candidate in _get_windows_bin_paths():
        if candidate.is_dir() and str(candidate).lower() not in lower_set:
            path_entries.insert(0, str(candidate))
            lower_set.add(str(candidate).lower())
    env[path_key] = os.pathsep.join(path_entries)


def _resolve_executable(name: str, env: dict) -> str:
    """Resolve executable path, checking npm dirs for .cmd/.bat on Windows."""
    if os.path.isabs(name) or os.sep in name or (os.altsep and os.altsep in name):
        return name
    path_key = next((key for key in env if key.upper() == "PATH"), "PATH")
    path_val = env.get(path_key)
    win_exts = {".exe", ".cmd", ".bat", ".com"}
    if resolved := shutil.which(name, path=path_val):
        if _is_windows():
            suffix = Path(resolved).suffix.lower()
            if not suffix:
                resolved_dir = str(Path(resolved).parent)
                for ext in (".cmd", ".bat", ".exe", ".com"):
                    candidate = Path(resolved_dir) / f"{name}{ext}"
                    if candidate.is_file():
                        return str(candidate)
            elif suffix not in win_exts:
                return resolved
        return resolved
    if _is_windows():
        for base in _get_windows_bin_paths():
            for ext in (".cmd", ".bat", ".exe", ".com"):
                candidate = base / f"{name}{ext}"
                if candidate.is_file():
                    return str(candidate)
    return name


def windows_escape(value: str) -> str:
    """Escape control characters that cmd.exe would otherwise mangle."""
    value = value.replace("\n", "\\n")
    value = value.replace("\r", "\\r")
    value = value.replace("\t", "\\t")
    return value


def _prepare_popen_cmd(cmd: Sequence[str], env: dict):
    """Resolve executable and wrap Windows .cmd/.bat via cmd.exe."""
    popen_cmd = list(cmd)
    exe_path = _resolve_executable(popen_cmd[0], env)
    popen_cmd[0] = exe_path

    if _is_windows() and Path(exe_path).suffix.lower() in {".cmd", ".bat"}:
        popen_cmd = [windows_escape(arg) for arg in popen_cmd]

        def _cmd_quote(arg: str) -> str:
            # Port of Rust std append_bat_arg (CVE-2024-24576 fix), adapted to the
            # npm .cmd shim re-parsing (%* then node/MSVC CRT rules). Always quote;
            # "" for an embedded quote, double backslash runs around quotes, and
            # %%cd:~,% for % so no %VAR% can form. ^ needs no escaping inside quotes.
            if not arg:
                return '""'
            out = ['"']
            backslashes = 0
            for ch in arg:
                if ch == "\\":
                    backslashes += 1
                    continue
                if ch == '"':
                    out.append("\\" * (backslashes * 2))
                    out.append('""')
                elif ch == "%":
                    out.append("\\" * backslashes)
                    out.append("%%cd:~,%")
                else:
                    out.append("\\" * backslashes)
                    out.append(ch)
                backslashes = 0
            out.append("\\" * (backslashes * 2))
            out.append('"')
            return "".join(out)

        cmdline = " ".join(_cmd_quote(arg) for arg in popen_cmd)
        comspec = env.get("COMSPEC", "cmd.exe")
        return f'"{comspec}" /d /s /c "{cmdline}"'
    return popen_cmd


def configure_windows_stdio() -> None:
    """Configure stdout/stderr to use UTF-8 encoding on Windows."""
    if not _is_windows():
        return
    for stream in (sys.stdout, sys.stderr):
        reconfigure = getattr(stream, "reconfigure", None)
        if callable(reconfigure):
            with contextlib.suppress(ValueError, OSError):
                reconfigure(encoding="utf-8")


def emit(result: dict) -> None:
    print(json.dumps(result, indent=2, ensure_ascii=False))


def _normalize_workspace(path_value) -> Path:
    return Path(path_value).expanduser().resolve()


def build_claude_cmd(args) -> tuple[list[str], str]:
    """Build `claude -p ...` argv from parsed run args."""
    workspace = str(_normalize_workspace(args.cd))
    session_id = args.SESSION_ID or str(uuid.uuid4())

    cmd = [
        "claude",
        "-p",
        "--output-format",
        "stream-json",
        "--verbose",
        "--add-dir",
        workspace,
    ]

    if args.model:
        cmd.extend(["--model", args.model])
    if args.permission_mode:
        cmd.extend(["--permission-mode", args.permission_mode])
    if args.dangerously_skip_permissions:
        cmd.append("--dangerously-skip-permissions")

    if args.SESSION_ID:
        cmd.extend(["--resume", args.SESSION_ID])
    else:
        cmd.extend(["--session-id", session_id])

    cmd.append(args.PROMPT)
    return cmd, session_id


def _resumable_session_id(args, session_id: str, events_seen: bool) -> str:
    """Advertise SESSION_ID only when the conversation actually exists.

    A caller-supplied --SESSION_ID always names a real conversation. A
    pre-generated uuid (--session-id) names one only once claude has emitted at
    least one stream record; with none, claude never started, so returning the
    uuid would advertise a session that can never resume.
    """
    return session_id if (args.SESSION_ID or events_seen) else ""


def _coerce_stream_text(value) -> str:
    if value is None:
        return ""
    if isinstance(value, bytes):
        return value.decode("utf-8", "replace")
    return str(value)


def _stop_process(process: subprocess.Popen) -> None:
    """Stop a bridge-owned process without waiting indefinitely.

    On the Windows .cmd/.bat path the direct child is a cmd.exe wrapper;
    terminate() would kill only the shell and orphan the node launcher and
    claude.exe while they hold the stdout pipe open. Kill the whole tree.
    """
    if process.poll() is not None:
        return
    if _is_windows():
        subprocess.run(
            ["taskkill", "/T", "/F", "/PID", str(process.pid)],
            stdin=subprocess.DEVNULL,
            stdout=subprocess.DEVNULL,
            stderr=subprocess.DEVNULL,
            check=False,
        )
    else:
        process.terminate()
    try:
        process.wait(timeout=5)
    except subprocess.TimeoutExpired:
        process.kill()
        with contextlib.suppress(subprocess.TimeoutExpired):
            process.wait(timeout=5)


def _stream_claude_output(
    popen_cmd,
    workspace: str,
    env: dict,
    timeout: float | None,
    stderr_sink: list[str],
    stdin_prompt: str | None = None,
) -> Iterator[str]:
    """Yield Claude JSONL records while draining stderr concurrently."""
    process = subprocess.Popen(
        popen_cmd,
        shell=False,
        cwd=workspace,
        stdin=subprocess.PIPE if stdin_prompt is not None else subprocess.DEVNULL,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        text=True,
        encoding="utf-8",
        errors="replace",
        env=env,
    )
    if stdin_prompt is not None and process.stdin is not None:

        def write_prompt() -> None:
            with contextlib.suppress(BrokenPipeError, OSError, ValueError):
                process.stdin.write(stdin_prompt)
            with contextlib.suppress(BrokenPipeError, OSError, ValueError):
                process.stdin.close()

        threading.Thread(target=write_prompt, daemon=True).start()

    stdout_queue: queue.Queue[str | None] = queue.Queue()

    def read_stdout() -> None:
        assert process.stdout is not None
        try:
            for line in process.stdout:
                stdout_queue.put(line.rstrip("\r\n"))
        finally:
            stdout_queue.put(None)

    def read_stderr() -> None:
        assert process.stderr is not None
        for line in process.stderr:
            text = line.rstrip("\r\n")
            if text:
                stderr_sink.append(text)

    stdout_thread = threading.Thread(target=read_stdout, daemon=True)
    stderr_thread = threading.Thread(target=read_stderr, daemon=True)
    stdout_thread.start()
    stderr_thread.start()
    deadline = time.monotonic() + timeout if timeout is not None else None

    try:
        while True:
            wait_for = None
            if deadline is not None:
                wait_for = deadline - time.monotonic()
                if wait_for <= 0:
                    raise subprocess.TimeoutExpired(popen_cmd, timeout)
            try:
                line = stdout_queue.get(timeout=wait_for)
            except queue.Empty as exc:
                raise subprocess.TimeoutExpired(popen_cmd, timeout) from exc
            if line is None:
                break
            yield line

        try:
            process.wait(timeout=5)
        except subprocess.TimeoutExpired:
            _stop_process(process)
        stderr_thread.join(timeout=1)
    except (KeyboardInterrupt, subprocess.TimeoutExpired):
        _stop_process(process)
        raise
    finally:
        if process.poll() is None:
            _stop_process(process)


def _create_stream_file(requested_path: str) -> Path:
    if requested_path:
        return Path(requested_path).expanduser().resolve()
    descriptor, path = tempfile.mkstemp(prefix="claude_stream_", suffix=".jsonl")
    os.close(descriptor)
    return Path(path)


def _event_text(value) -> str:
    if value is None:
        return ""
    if isinstance(value, str):
        return value.strip()
    return json.dumps(value, ensure_ascii=False)


def _describe_retry_events(retry_events: list[dict]) -> str:
    """Summarize the last transport-level retry so a timeout is diagnosable."""
    if not retry_events:
        return ""
    last = retry_events[-1]
    status = last.get("error_status")
    detail = _event_text(last.get("error"))
    attempt = last.get("attempt")
    max_retries = last.get("max_retries")
    parts = []
    if status is not None:
        parts.append(f"HTTP {status}")
    if detail:
        parts.append(detail)
    summary = " ".join(parts) or "unknown transport error"
    if attempt is not None and max_retries is not None:
        summary += f", attempt {attempt}/{max_retries}"
    return f"last transport error: {summary}"


def run_passthrough(subcommand: str, extra: list[str], timeout: float = 120.0) -> None:
    """Thin passthrough to `claude <subcommand> ...` for management flows."""
    env = os.environ.copy()
    _augment_path_env(env)
    cmd = ["claude", subcommand] + extra
    popen_cmd = _prepare_popen_cmd(cmd, env)
    try:
        cp = subprocess.run(
            popen_cmd,
            shell=False,
            stdin=subprocess.DEVNULL,
            capture_output=True,
            check=False,
            timeout=timeout,
            text=True,
            encoding="utf-8",
            errors="replace",
            env=env,
        )
        emit(
            {
                "success": cp.returncode == 0,
                "output": cp.stdout or "",
                "error": cp.stderr or "",
                "returncode": cp.returncode,
            }
        )
    except subprocess.TimeoutExpired:
        emit(
            {
                "success": False,
                "output": "",
                "error": f"claude {subcommand} timed out",
                "returncode": -1,
            }
        )
    except FileNotFoundError:
        emit(
            {
                "success": False,
                "output": "",
                "error": "claude binary not found in PATH",
                "returncode": 127,
            }
        )


def cmd_run(args) -> None:
    workspace = Path(args.cd).expanduser()
    if not workspace.exists():
        emit(
            {
                "success": False,
                "error": f"The workspace root directory `{workspace.resolve(strict=False)}` does not exist. Please check the path and try again.",
            }
        )
        return
    if not workspace.is_dir():
        emit(
            {
                "success": False,
                "error": f"The workspace root `{workspace.resolve()}` is not a directory.",
            }
        )
        return

    workspace = workspace.resolve()
    cmd, session_id = build_claude_cmd(args)
    env = os.environ.copy()
    _augment_path_env(env)
    # On the Windows .cmd/.bat shim path the whole prompt would ride inside the
    # cmd.exe command line, which breaks at ~8k chars and re-parses quoting.
    # claude -p has no `-` positional convention: piping text with no positional
    # prompt argument makes stdin the prompt. Deliver it there instead, which
    # also preserves real newlines. Passthrough (mcp/plugin) is never `-p`.
    stdin_prompt = None
    if _is_windows() and len(cmd) > 2 and cmd[0] == "claude" and cmd[1] == "-p":
        resolved = _resolve_executable(cmd[0], env)
        if Path(resolved).suffix.lower() in {".cmd", ".bat"}:
            stdin_prompt = cmd.pop()
    popen_cmd = _prepare_popen_cmd(cmd, env)
    try:
        stream_file = _create_stream_file(getattr(args, "stream_file", ""))
        stream = stream_file.open("w", encoding="utf-8", newline="\n")
    except OSError as exc:
        emit({"success": False, "error": f"Could not open Claude stream file: {exc}"})
        return
    stderr_lines: list[str] = []
    all_messages: list[dict] = []
    parse_errors: list[str] = []
    retry_events: list[dict] = []
    result_seen = False
    result_success = False
    result_text = ""

    try:
        with stream:
            for line in _stream_claude_output(
                popen_cmd,
                str(workspace),
                env,
                args.timeout,
                stderr_lines,
                stdin_prompt,
            ):
                stream.write(f"{line}\n")
                stream.flush()
                if not line.strip():
                    continue
                try:
                    event = json.loads(line)
                except json.JSONDecodeError as exc:
                    parse_errors.append(f"line {exc.lineno}: {exc.msg}")
                    continue
                if not isinstance(event, dict):
                    parse_errors.append("stream record was not a JSON object")
                    continue
                all_messages.append(event)
                event_session_id = event.get("session_id")
                if isinstance(event_session_id, str) and event_session_id:
                    session_id = event_session_id
                if event.get("subtype") == "api_retry":
                    retry_events.append(event)
                if event.get("type") == "result":
                    result_seen = True
                    result_success = event.get("subtype") == "success" and not event.get("is_error", False)
                    result_text = _event_text(event.get("result"))
    except subprocess.TimeoutExpired as exc:
        error = f"claude timed out after {args.timeout}s"
        if retry_detail := _describe_retry_events(retry_events):
            error += f" ({retry_detail})"
        result = {
            "success": False,
            "SESSION_ID": _resumable_session_id(args, session_id, bool(all_messages)),
            "error": error,
            "stream_file": str(stream_file),
        }
        stderr = "\n".join(stderr_lines).strip()
        if not stderr:
            stderr = _coerce_stream_text(getattr(exc, "stderr", None)).strip()
        if getattr(args, "return_all_messages", False):
            result["all_messages"] = all_messages
        if stderr:
            result["stderr"] = stderr
        emit(result)
        return
    except KeyboardInterrupt:
        result = {
            "success": False,
            "SESSION_ID": _resumable_session_id(args, session_id, bool(all_messages)),
            "error": "claude interrupted",
            "stream_file": str(stream_file),
        }
        if getattr(args, "return_all_messages", False):
            result["all_messages"] = all_messages
        emit(result)
        return
    except FileNotFoundError:
        emit(
            {
                "success": False,
                "error": "claude binary not found in PATH",
                "stream_file": str(stream_file),
            }
        )
        return

    stderr = "\n".join(stderr_lines).strip()
    if result_seen and result_success and result_text:
        result = {
            "success": True,
            "SESSION_ID": _resumable_session_id(args, session_id, bool(all_messages)),
            "agent_messages": result_text,
            "stream_file": str(stream_file),
        }
        if getattr(args, "return_all_messages", False):
            result["all_messages"] = all_messages
        if stderr:
            result["stderr"] = stderr
        emit(result)
        return

    if result_seen:
        error = result_text or "Claude result contained no assistant text."
    else:
        error = "Claude stream ended without a result event."
        if parse_errors:
            error += f" Parse errors: {'; '.join(parse_errors)}"
    result = {
        "success": False,
        "SESSION_ID": _resumable_session_id(args, session_id, bool(all_messages)),
        "error": error,
        "stream_file": str(stream_file),
    }
    if getattr(args, "return_all_messages", False):
        result["all_messages"] = all_messages
    if stderr:
        result["stderr"] = stderr
    emit(result)


def main() -> None:
    configure_windows_stdio()

    if len(sys.argv) > 1 and sys.argv[1] in ("mcp", "plugin"):
        run_passthrough(sys.argv[1], sys.argv[2:])
        return

    parser = argparse.ArgumentParser(description="Claude Bridge")
    parser.add_argument(
        "--PROMPT",
        required=True,
        help="Instruction for the task to send to Claude Code.",
    )
    parser.add_argument(
        "--cd",
        required=True,
        type=Path,
        help="Workspace root for Claude Code (cwd + --add-dir).",
    )
    parser.add_argument("--SESSION_ID", default="", help="Resume a conversation by session UUID.")
    parser.add_argument(
        "--model",
        default="",
        help="Claude model override. Omit to inherit the configured default.",
    )
    parser.add_argument(
        "--permission-mode",
        default="",
        choices=[""] + PERMISSION_MODES,
        help="Claude permission mode override. Omit to preserve the configured default.",
    )
    parser.add_argument(
        "--dangerously-skip-permissions",
        action="store_true",
        help="Bypass Claude permission checks. Use only when the caller explicitly requests it.",
    )
    parser.add_argument(
        "--timeout",
        type=float,
        default=None,
        help="Bridge-level timeout in seconds. Omit to wait without a bridge deadline.",
    )
    parser.add_argument(
        "--stream-file",
        default="",
        help="Path for raw Claude stream-json records. Omit to create a temporary JSONL file.",
    )
    parser.add_argument(
        "--return-all-messages",
        action="store_true",
        help="Include parsed stream-json records in the returned JSON envelope.",
    )

    sub = parser.add_subparsers(dest="subcommand")
    sub.add_parser("mcp", help="Thin passthrough to `claude mcp`.")
    sub.add_parser("plugin", help="Thin passthrough to `claude plugin`.")

    args = parser.parse_args()
    cmd_run(args)


if __name__ == "__main__":
    main()
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall