claudekit-codex-sync 0.1.0

package/src/claudekit_codex_sync/asset_sync_zip.py

@@ -0,0 +1,140 @@
+"""Asset and skill synchronization from zip files."""
+
+from __future__ import annotations
+
+import shutil
+import zipfile
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+from .constants import (
+    ASSET_DIRS,
+    ASSET_FILES,
+    ASSET_MANIFEST,
+    CONFLICT_SKILLS,
+    EXCLUDED_SKILLS_ALWAYS,
+    MCP_SKILLS,
+)
+from .source_resolver import collect_skill_entries, zip_mode
+from .utils import load_manifest, save_manifest, write_bytes_if_changed
+
+
+def sync_assets(
+    zf: zipfile.ZipFile,
+    *,
+    codex_home: Path,
+    include_hooks: bool,
+    dry_run: bool,
+) -> Dict[str, int]:
+    """Sync non-skill assets from zip to codex_home/claudekit."""
+    claudekit_dir = codex_home / "claudekit"
+    manifest_path = claudekit_dir / ASSET_MANIFEST
+    old_manifest = load_manifest(manifest_path)
+
+    selected: List[Tuple[str, str]] = []
+    for name in zf.namelist():
+        if name.endswith("/") or not name.startswith(".claude/"):
+            continue
+        rel = name[len(".claude/") :]
+        first = rel.split("/", 1)[0]
+        if first == "hooks" and include_hooks:
+            selected.append((name, rel))
+            continue
+        if first in ASSET_DIRS or rel in ASSET_FILES:
+            selected.append((name, rel))
+
+    new_manifest = {rel for _, rel in selected}
+    added = updated = removed = 0
+
+    for rel in sorted(old_manifest - new_manifest):
+        target = claudekit_dir / rel
+        if target.exists():
+            removed += 1
+            print(f"remove: {rel}")
+            if not dry_run:
+                target.unlink()
+
+    for zip_name, rel in sorted(selected, key=lambda x: x[1]):
+        info = zf.getinfo(zip_name)
+        data = zf.read(zip_name)
+        dst = claudekit_dir / rel
+        changed, is_added = write_bytes_if_changed(dst, data, mode=zip_mode(info), dry_run=dry_run)
+        if changed:
+            if is_added:
+                added += 1
+                print(f"add: {rel}")
+            else:
+                updated += 1
+                print(f"update: {rel}")
+
+    if not dry_run:
+        claudekit_dir.mkdir(parents=True, exist_ok=True)
+    save_manifest(manifest_path, new_manifest, dry_run=dry_run)
+
+    if not dry_run:
+        for d in sorted(claudekit_dir.rglob("*"), reverse=True):
+            if d.is_dir():
+                try:
+                    d.rmdir()
+                except OSError:
+                    pass
+
+    return {"added": added, "updated": updated, "removed": removed, "managed_files": len(new_manifest)}
+
+
+def sync_skills(
+    zf: zipfile.ZipFile,
+    *,
+    codex_home: Path,
+    include_mcp: bool,
+    include_conflicts: bool,
+    dry_run: bool,
+) -> Dict[str, int]:
+    """Sync skills from zip to codex_home/skills."""
+    skills_dir = codex_home / "skills"
+    skill_entries = collect_skill_entries(zf)
+    added = updated = skipped = 0
+
+    for skill in sorted(skill_entries):
+        if skill in EXCLUDED_SKILLS_ALWAYS:
+            skipped += 1
+            print(f"skip: {skill}")
+            continue
+        if not include_mcp and skill in MCP_SKILLS:
+            skipped += 1
+            print(f"skip: {skill}")
+            continue
+        if skill in CONFLICT_SKILLS:
+            skipped += 1
+            print(f"skip: {skill}")
+            continue
+        if not include_conflicts and (skills_dir / ".system" / skill).exists():
+            skipped += 1
+            print(f"skip: {skill}")
+            continue
+
+        dst_skill_dir = skills_dir / skill
+        exists = dst_skill_dir.exists()
+        if exists:
+            updated += 1
+            print(f"update: {skill}")
+        else:
+            added += 1
+            print(f"add: {skill}")
+
+        if dry_run:
+            continue
+
+        if exists:
+            shutil.rmtree(dst_skill_dir)
+        dst_skill_dir.mkdir(parents=True, exist_ok=True)
+
+        for zip_name, inner in sorted(skill_entries[skill], key=lambda x: x[1]):
+            info = zf.getinfo(zip_name)
+            data = zf.read(zip_name)
+            dst = dst_skill_dir / inner
+            write_bytes_if_changed(dst, data, mode=zip_mode(info), dry_run=False)
+
+    skills_dir.mkdir(parents=True, exist_ok=True)
+    total_skills = len(list(skills_dir.rglob("SKILL.md")))
+    return {"added": added, "updated": updated, "skipped": skipped, "total_skills": total_skills}

package/src/claudekit_codex_sync/bridge_generator.py

@@ -0,0 +1,33 @@
+"""Bridge skill generation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .utils import load_template, write_text_if_changed
+
+
+def ensure_bridge_skill(*, codex_home: Path, dry_run: bool) -> bool:
+    """Ensure claudekit-command-bridge skill exists."""
+    bridge_dir = codex_home / "skills" / "claudekit-command-bridge"
+    scripts_dir = bridge_dir / "scripts"
+    if not dry_run:
+        scripts_dir.mkdir(parents=True, exist_ok=True)
+    changed = False
+
+    skill_md = load_template("bridge-skill.md")
+    resolve_script = load_template("bridge-resolve-command.py")
+    docs_init = load_template("bridge-docs-init.sh")
+    project_status = load_template("bridge-project-status.sh")
+
+    changed |= write_text_if_changed(bridge_dir / "SKILL.md", skill_md, dry_run=dry_run)
+    changed |= write_text_if_changed(
+        scripts_dir / "resolve-command.py", resolve_script, executable=True, dry_run=dry_run
+    )
+    changed |= write_text_if_changed(
+        scripts_dir / "docs-init.sh", docs_init, executable=True, dry_run=dry_run
+    )
+    changed |= write_text_if_changed(
+        scripts_dir / "project-status.sh", project_status, executable=True, dry_run=dry_run
+    )
+    return changed

package/src/claudekit_codex_sync/cli.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""All-in-one ClaudeKit -> Codex sync CLI."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import zipfile
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .asset_sync_dir import sync_assets_from_dir, sync_skills_from_dir
+from .asset_sync_zip import sync_assets, sync_skills
+from .bridge_generator import ensure_bridge_skill
+from .config_enforcer import ensure_agents, enforce_config, enforce_multi_agent_flag
+from .dep_bootstrapper import bootstrap_deps
+from .path_normalizer import normalize_agent_tomls, normalize_files
+from .prompt_exporter import export_prompts
+from .runtime_verifier import verify_runtime
+from .source_resolver import detect_claude_source, find_latest_zip, validate_source
+from .sync_registry import load_registry, save_registry
+from .utils import SyncError, eprint
+
+
+def print_summary(summary: Dict[str, Any]) -> None:
+    print(json.dumps(summary, indent=2, ensure_ascii=False))
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        description="All-in-one ClaudeKit -> Codex sync script."
+    )
+    p.add_argument("--zip", dest="zip_path", type=Path, help="Specific ClaudeKit zip path")
+    p.add_argument("--codex-home", type=Path, default=None, help="Codex home (default: $CODEX_HOME or ~/.codex)")
+    p.add_argument("--workspace", type=Path, default=Path.cwd(), help="Workspace root for AGENTS.md")
+    p.add_argument("--source-mode", choices=["auto", "live", "zip"], default="auto", help="Source mode")
+    p.add_argument("--source-dir", type=Path, default=None, help="Source directory for live mode")
+    p.add_argument("--include-mcp", action="store_true", help="Include MCP skills/prompts")
+    p.add_argument("--include-hooks", action="store_true", help="Include hooks")
+    p.add_argument("--include-conflicts", action="store_true", help="Include conflicting skills")
+    p.add_argument("--include-test-deps", action="store_true", help="Install test requirements")
+    p.add_argument("--skip-bootstrap", action="store_true", help="Skip dependency bootstrap")
+    p.add_argument("--skip-verify", action="store_true", help="Skip verification")
+    p.add_argument("--skip-agent-toml", action="store_true", help="Skip agent TOML normalization")
+    p.add_argument("--respect-edits", action="store_true", help="Backup user-edited files")
+    p.add_argument("--dry-run", action="store_true", help="Preview changes only")
+    return p.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    codex_home = (args.codex_home or Path(os.environ.get("CODEX_HOME", "~/.codex"))).expanduser().resolve()
+    workspace = args.workspace.expanduser().resolve()
+    workspace.mkdir(parents=True, exist_ok=True)
+
+    # Load registry for backup/respect-edits
+    registry = load_registry(codex_home)
+
+    source_mode = args.source_mode
+    use_live = source_mode == "live" or (source_mode == "auto" and args.source_dir)
+
+    if use_live:
+        source = args.source_dir or detect_claude_source()
+        validation = validate_source(source)
+        print(f"source: {source} (live)")
+        print(f"validation: {validation}")
+        registry["sourceDir"] = str(source)
+    else:
+        zip_path = find_latest_zip(args.zip_path)
+        print(f"zip: {zip_path}")
+        registry["sourceDir"] = None
+
+    print(f"codex_home: {codex_home}")
+    print(f"workspace: {workspace}")
+    print(
+        f"include_mcp={args.include_mcp} include_hooks={args.include_hooks} "
+        f"dry_run={args.dry_run} respect_edits={args.respect_edits}"
+    )
+
+    codex_home.mkdir(parents=True, exist_ok=True)
+
+    if use_live:
+        assets_stats = sync_assets_from_dir(
+            source, codex_home=codex_home, include_hooks=args.include_hooks, dry_run=args.dry_run
+        )
+        skills_stats = sync_skills_from_dir(
+            source,
+            codex_home=codex_home,
+            include_mcp=args.include_mcp,
+            include_conflicts=args.include_conflicts,
+            dry_run=args.dry_run,
+        )
+    else:
+        with zipfile.ZipFile(zip_path) as zf:  # type: ignore
+            assets_stats = sync_assets(
+                zf, codex_home=codex_home, include_hooks=args.include_hooks, dry_run=args.dry_run
+            )
+            skills_stats = sync_skills(
+                zf,
+                codex_home=codex_home,
+                include_mcp=args.include_mcp,
+                include_conflicts=args.include_conflicts,
+                dry_run=args.dry_run,
+            )
+
+    print(
+        f"assets: added={assets_stats['added']} updated={assets_stats['updated']} "
+        f"removed={assets_stats['removed']}"
+    )
+    print(
+        f"skills: added={skills_stats['added']} updated={skills_stats['updated']} "
+        f"skipped={skills_stats['skipped']}"
+    )
+
+    changed = normalize_files(codex_home=codex_home, include_mcp=args.include_mcp, dry_run=args.dry_run)
+    print(f"normalize_changed={changed}")
+
+    # Agent TOML normalization
+    agent_toml_changed = 0
+    if not args.skip_agent_toml:
+        agent_toml_changed = normalize_agent_tomls(codex_home=codex_home, dry_run=args.dry_run)
+        print(f"agent_toml_changed={agent_toml_changed}")
+
+    baseline_changed = 0
+    if ensure_agents(workspace=workspace, dry_run=args.dry_run):
+        baseline_changed += 1
+        print(f"upsert: {workspace / 'AGENTS.md'}")
+    if enforce_config(codex_home=codex_home, include_mcp=args.include_mcp, dry_run=args.dry_run):
+        baseline_changed += 1
+        print(f"upsert: {codex_home / 'config.toml'}")
+    if ensure_bridge_skill(codex_home=codex_home, dry_run=args.dry_run):
+        baseline_changed += 1
+        print(f"upsert: {codex_home / 'skills' / 'claudekit-command-bridge'}")
+
+    # Enable multi_agent flag
+    config_path = codex_home / "config.toml"
+    if enforce_multi_agent_flag(config_path, dry_run=args.dry_run):
+        print(f"upsert: multi_agent = true in {config_path}")
+
+    print(f"baseline_changed={baseline_changed}")
+
+    prompt_stats = export_prompts(codex_home=codex_home, include_mcp=args.include_mcp, dry_run=args.dry_run)
+    print(
+        f"prompts: added={prompt_stats['added']} updated={prompt_stats['updated']} "
+        f"total_generated={prompt_stats['total_generated']}"
+    )
+
+    bootstrap_stats = None
+    if not args.skip_bootstrap:
+        bootstrap_stats = bootstrap_deps(
+            codex_home=codex_home,
+            include_mcp=args.include_mcp,
+            include_test_deps=args.include_test_deps,
+            dry_run=args.dry_run,
+        )
+        print(
+            f"bootstrap: python_ok={bootstrap_stats['python_ok']} "
+            f"python_fail={bootstrap_stats['python_fail']}"
+        )
+        if (bootstrap_stats["python_fail"] or bootstrap_stats["node_fail"]) and not args.dry_run:
+            raise SyncError("Dependency bootstrap reported failures")
+
+    verify_stats = None
+    if not args.skip_verify:
+        verify_stats = verify_runtime(codex_home=codex_home, dry_run=args.dry_run)
+        print(f"verify: {verify_stats}")
+
+    # Save registry
+    if not args.dry_run:
+        save_registry(codex_home, registry)
+
+    summary = {
+        "source": str(source) if use_live else str(zip_path),
+        "source_mode": "live" if use_live else "zip",
+        "codex_home": str(codex_home),
+        "workspace": str(workspace),
+        "dry_run": args.dry_run,
+        "include_mcp": args.include_mcp,
+        "include_hooks": args.include_hooks,
+        "assets": assets_stats,
+        "skills": skills_stats,
+        "normalize_changed": changed,
+        "agent_toml_changed": agent_toml_changed,
+        "baseline_changed": baseline_changed,
+        "prompts": prompt_stats,
+        "bootstrap": bootstrap_stats,
+        "verify": verify_stats,
+    }
+    print_summary(summary)
+    print("done: claudekit all-in-one sync completed")
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except SyncError as exc:
+        eprint(f"error: {exc}")
+        raise SystemExit(2)

package/src/claudekit_codex_sync/config_enforcer.py

@@ -0,0 +1,140 @@
+"""Config enforcement for Codex."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import List
+
+
+def ensure_agents(*, workspace: Path, dry_run: bool) -> bool:
+    """Ensure AGENTS.md exists in workspace."""
+    from .utils import load_template, write_text_if_changed
+    target = workspace / "AGENTS.md"
+    template = load_template("agents-md.md")
+    return write_text_if_changed(target, template, dry_run=dry_run)
+
+
+def enforce_config(*, codex_home: Path, include_mcp: bool, dry_run: bool) -> bool:
+    """Enforce Codex config defaults."""
+    config = codex_home / "config.toml"
+    if config.exists():
+        text = config.read_text(encoding="utf-8")
+    else:
+        text = ""
+    orig = text
+
+    if re.search(r"^project_doc_max_bytes\s*=", text, flags=re.M):
+        text = re.sub(r"^project_doc_max_bytes\s*=.*$", "project_doc_max_bytes = 65536", text, flags=re.M)
+    else:
+        text = (text.rstrip("\n") + "\nproject_doc_max_bytes = 65536\n").lstrip("\n")
+
+    fallback_line = 'project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md", "AGENTS.override.md"]'
+    if re.search(r"^project_doc_fallback_filenames\s*=", text, flags=re.M):
+        text = re.sub(r"^project_doc_fallback_filenames\s*=.*$", fallback_line, text, flags=re.M)
+    else:
+        text = text.rstrip("\n") + "\n" + fallback_line + "\n"
+
+    mcp_management_path = str((codex_home / "skills" / "mcp-management").resolve())
+    mcp_builder_path = str((codex_home / "skills" / "mcp-builder").resolve())
+    mcp_enabled = "true" if include_mcp else "false"
+
+    pattern = re.compile(r"\n\[\[skills\.config\]\]\n(?:[^\n]*\n)*?(?=\n\[\[skills\.config\]\]|\Z)", re.M)
+    blocks = pattern.findall("\n" + text)
+    kept: List[str] = []
+    for block in blocks:
+        if f'path = "{mcp_management_path}"' in block:
+            continue
+        if f'path = "{mcp_builder_path}"' in block:
+            continue
+        kept.append(block.rstrip("\n"))
+
+    base = pattern.sub("", "\n" + text).lstrip("\n").rstrip("\n")
+    for block in kept:
+        if block:
+            base += "\n\n" + block
+
+    base += f'\n\n[[skills.config]]\npath = "{mcp_management_path}"\nenabled = {mcp_enabled}\n'
+    base += f'\n[[skills.config]]\npath = "{mcp_builder_path}"\nenabled = {mcp_enabled}\n'
+
+    if base == orig:
+        return False
+    if not dry_run:
+        config.parent.mkdir(parents=True, exist_ok=True)
+        config.write_text(base, encoding="utf-8")
+    return True
+
+
+def enforce_multi_agent_flag(config_path: Path, dry_run: bool) -> bool:
+    """Ensure multi_agent and child_agents_md flags are set in config."""
+    text = config_path.read_text() if config_path.exists() else ""
+    orig = text
+
+    if "[features]" in text:
+        if "multi_agent" not in text:
+            text = text.replace("[features]", "[features]\nmulti_agent = true")
+        if "child_agents_md" not in text:
+            text = text.replace("[features]", "[features]\nchild_agents_md = true")
+    else:
+        text += "\n[features]\nmulti_agent = true\nchild_agents_md = true\n"
+
+    if text != orig and not dry_run:
+        config_path.write_text(text)
+    return text != orig
+
+
+def _extract_description(toml_text: str) -> str:
+    """Extract first meaningful sentence from developer_instructions."""
+    match = re.search(
+        r'developer_instructions\s*=\s*"""(.*?)"""',
+        toml_text,
+        re.DOTALL,
+    )
+    if not match:
+        return ""
+    body = match.group(1).strip()
+    for line in body.splitlines():
+        line = line.strip()
+        if line.startswith("#") or not line:
+            continue
+        # Strip markdown bold
+        line = re.sub(r"\*\*([^*]+)\*\*", r"\1", line)
+        # Take first sentence
+        dot = line.find(". ")
+        if dot > 0:
+            return line[: dot + 1]
+        return line[:120]
+    return ""
+
+
+def register_agents(*, codex_home: Path, dry_run: bool) -> int:
+    """Register agent TOMLs as [agents.*] roles in config.toml."""
+    agents_dir = codex_home / "agents"
+    config_path = codex_home / "config.toml"
+    if not agents_dir.exists():
+        return 0
+
+    text = config_path.read_text(encoding="utf-8") if config_path.exists() else ""
+    added = 0
+
+    for toml_file in sorted(agents_dir.glob("*.toml")):
+        slug = toml_file.stem
+        section_header = f"[agents.{slug}]"
+        if section_header in text:
+            continue
+
+        content = toml_file.read_text(encoding="utf-8")
+        desc = _extract_description(content) or f"{slug.replace('_', ' ').title()} agent"
+        # Escape quotes in description
+        desc = desc.replace('"', '\\"')
+
+        text += (
+            f"\n{section_header}\n"
+            f'description = "{desc}"\n'
+            f'config_file = "agents/{toml_file.name}"\n'
+        )
+        added += 1
+
+    if added > 0 and not dry_run:
+        config_path.write_text(text, encoding="utf-8")
+    return added

package/src/claudekit_codex_sync/constants.py

@@ -0,0 +1,104 @@
+"""Constants for path normalization and sync operations."""
+
+from typing import List, Set, Tuple
+
+ASSET_DIRS = {"agents", "commands", "output-styles", "rules", "scripts"}
+ASSET_FILES = {
+    "CLAUDE.md",
+    ".ck.json",
+    ".ckignore",
+    ".env.example",
+    ".mcp.json.example",
+    "settings.json",
+    "metadata.json",
+    "statusline.cjs",
+    "statusline.sh",
+    "statusline.ps1",
+}
+ASSET_MANIFEST = ".sync-manifest-assets.txt"
+PROMPT_MANIFEST = ".claudekit-generated-prompts.txt"
+REGISTRY_FILE = ".claudekit-sync-registry.json"
+
+EXCLUDED_SKILLS_ALWAYS: Set[str] = {"template-skill"}
+MCP_SKILLS: Set[str] = {"mcp-builder", "mcp-management"}
+CONFLICT_SKILLS: Set[str] = {"skill-creator"}
+
+SKILL_MD_REPLACEMENTS: List[Tuple[str, str]] = [
+    ("$HOME/.claude/skills/", "${CODEX_HOME:-$HOME/.codex}/skills/"),
+    ("$HOME/.claude/scripts/", "${CODEX_HOME:-$HOME/.codex}/claudekit/scripts/"),
+    ("$HOME/.claude/rules/", "${CODEX_HOME:-$HOME/.codex}/claudekit/rules/"),
+    ("$HOME/.claude/", "${CODEX_HOME:-$HOME/.codex}/"),
+    ("./.claude/skills/", "${CODEX_HOME:-$HOME/.codex}/skills/"),
+    (".claude/skills/", "${CODEX_HOME:-$HOME/.codex}/skills/"),
+    ("./.claude/scripts/", "${CODEX_HOME:-$HOME/.codex}/claudekit/scripts/"),
+    (".claude/scripts/", "${CODEX_HOME:-$HOME/.codex}/claudekit/scripts/"),
+    ("./.claude/rules/", "${CODEX_HOME:-$HOME/.codex}/claudekit/rules/"),
+    (".claude/rules/", "${CODEX_HOME:-$HOME/.codex}/claudekit/rules/"),
+    ("~/.claude/.ck.json", "~/.codex/claudekit/.ck.json"),
+    ("./.claude/.ck.json", "~/.codex/claudekit/.ck.json"),
+    (".claude/.ck.json", "~/.codex/claudekit/.ck.json"),
+    ("~/.claude/", "~/.codex/"),
+    ("./.claude/", "./.codex/"),
+    ("<project>/.claude/", "<project>/.codex/"),
+    (".claude/", ".codex/"),
+    ("`.claude`", "`.codex`"),
+    ("$HOME/${CODEX_HOME:-$HOME/.codex}/", "${CODEX_HOME:-$HOME/.codex}/"),
+]
+
+PROMPT_REPLACEMENTS: List[Tuple[str, str]] = [
+    ("$HOME/.claude/skills/", "${CODEX_HOME:-$HOME/.codex}/skills/"),
+    ("$HOME/.claude/scripts/", "${CODEX_HOME:-$HOME/.codex}/claudekit/scripts/"),
+    ("$HOME/.claude/rules/", "${CODEX_HOME:-$HOME/.codex}/claudekit/rules/"),
+    ("$HOME/.claude/", "${CODEX_HOME:-$HOME/.codex}/"),
+    ("./.claude/skills/", "~/.codex/skills/"),
+    (".claude/skills/", "~/.codex/skills/"),
+    ("./.claude/scripts/", "~/.codex/claudekit/scripts/"),
+    (".claude/scripts/", "~/.codex/claudekit/scripts/"),
+    ("./.claude/rules/", "~/.codex/claudekit/rules/"),
+    (".claude/rules/", "~/.codex/claudekit/rules/"),
+    ("~/.claude/.ck.json", "~/.codex/claudekit/.ck.json"),
+    ("./.claude/.ck.json", "~/.codex/claudekit/.ck.json"),
+    (".claude/.ck.json", "~/.codex/claudekit/.ck.json"),
+    ("$HOME/${CODEX_HOME:-$HOME/.codex}/", "${CODEX_HOME:-$HOME/.codex}/"),
+]
+
+AGENT_TOML_REPLACEMENTS: List[Tuple[str, str]] = [
+    ("$HOME/.claude/skills/", "${CODEX_HOME:-$HOME/.codex}/skills/"),
+    ("$HOME/.claude/scripts/", "${CODEX_HOME:-$HOME/.codex}/claudekit/scripts/"),
+    ("$HOME/.claude/rules/", "${CODEX_HOME:-$HOME/.codex}/claudekit/rules/"),
+    ("$HOME/.claude/.ck.json", "${CODEX_HOME:-$HOME/.codex}/claudekit/.ck.json"),
+    ("$HOME/.claude/.mcp.json", "${CODEX_HOME:-$HOME/.codex}/claudekit/.mcp.json"),
+    ("$HOME/.claude/", "${CODEX_HOME:-$HOME/.codex}/"),
+    ("~/.claude/", "~/.codex/"),
+]
+
+CLAUDE_SYNTAX_ADAPTATIONS: List[Tuple[str, str]] = [
+    ("Task(Explore)", "the explore agent"),
+    ("Task(researcher)", "the researcher agent"),
+    ("Task(", "delegate to "),
+    ("$HOME/.claude/skills/*", "${CODEX_HOME:-$HOME/.codex}/skills/*"),
+]
+
+# Claude model → Codex model mapping (per developers.openai.com/codex/multi-agent)
+CLAUDE_TO_CODEX_MODELS: dict[str, str] = {
+    "opus": "gpt-5.3-codex",
+    "sonnet": "gpt-5.3-codex",
+    "haiku": "gpt-5.3-codex-spark",
+    "inherit": "",
+}
+
+# Reasoning effort per Claude model tier
+CLAUDE_MODEL_REASONING_EFFORT: dict[str, str] = {
+    "opus": "xhigh",
+    "sonnet": "high",
+    "haiku": "medium",
+}
+
+# Agents that should be read-only (no file writes needed)
+READ_ONLY_AGENT_ROLES: Set[str] = {
+    "brainstormer",
+    "code_reviewer",
+    "researcher",
+    "project_manager",
+    "journal_writer",
+}