claudekit-codex-sync 0.1.0

package/AGENTS.md

@@ -0,0 +1,45 @@
+# AGENTS.md
+
+Codex working profile for this workspace, adapted from ClaudeKit rules and workflows.
+
+## Operating Principles
+
+- Follow `YAGNI`, `KISS`, `DRY`.
+- Prefer direct, maintainable solutions over speculative abstraction.
+- Do not claim completion without evidence (tests, checks, or concrete validation).
+- Never use fake implementations just to make tests/build pass.
+
+## Default Workflow
+
+1. Read context first: `README.md` and relevant docs under `./docs/`.
+2. For non-trivial work, create/update a plan in `./plans/` before coding.
+3. Implement in existing files unless new files are clearly needed.
+4. Validate with project compile/lint/test commands.
+5. Run code-review mindset before finalizing (bugs, regressions, missing tests first).
+6. Update docs when behavior, architecture, contracts, or operations change.
+
+## Quality Gates
+
+- Handle edge cases and error paths explicitly.
+- Keep security and performance implications visible in design decisions.
+- Keep code readable and intention-revealing; add comments only when needed for non-obvious logic.
+
+## Documentation Rules
+
+- `./docs` is the source of truth for project docs.
+- Keep docs synchronized with code and implementation decisions.
+- When summarizing/reporting, be concise and list unresolved questions at the end.
+
+## Skill Usage
+
+- Activate relevant skills intentionally per task.
+- For legacy ClaudeKit command intents (`/ck-help`, `/coding-level`, `/ask`, `/docs/*`, `/journal`, `/watzup`), use `$claudekit-command-bridge`.
+
+## Reference Material (Imported from ClaudeKit)
+
+- `~/.codex/claudekit/CLAUDE.md`
+- `~/.codex/claudekit/rules/development-rules.md`
+- `~/.codex/claudekit/rules/primary-workflow.md`
+- `~/.codex/claudekit/rules/orchestration-protocol.md`
+- `~/.codex/claudekit/rules/documentation-management.md`
+- `~/.codex/claudekit/rules/team-coordination-rules.md`

package/README.md

@@ -0,0 +1,131 @@
+# claudekit-codex-sync
+
+Sync [ClaudeKit](https://github.com/anthropics/claudekit) skills, agents, prompts, and configuration to [Codex CLI](https://developers.openai.com/codex).
+
+## Problem
+
+ClaudeKit stores agent definitions (`.md` with YAML frontmatter), skills, prompts, and config under `~/.claude/`. Codex CLI uses a different layout under `~/.codex/` with `.toml` agents, GPT model names, and TOML-based config. Manually migrating is tedious and error-prone.
+
+## What It Does
+
+| Step | Action |
+|---|---|
+| **Source resolve** | Detects `~/.claude/` (live) or ClaudeKit export zip |
+| **Asset sync** | Copies agents, commands, rules, scripts → `~/.codex/claudekit/` |
+| **Skill sync** | Copies 54+ skills → `~/.codex/skills/` |
+| **Path normalize** | Rewrites `.claude` → `.codex` in all synced files |
+| **Agent convert** | `.md` (YAML frontmatter) → `.toml` with model mapping |
+| **Model mapping** | `opus → gpt-5.3-codex`, `haiku → gpt-5.3-codex-spark` |
+| **Config enforce** | Sets `multi_agent`, `child_agents_md`, registers `[agents.*]` |
+| **Prompt export** | Generates Codex-compatible prompt files |
+| **Dep bootstrap** | Installs Python/Node deps for skills requiring them |
+| **Runtime verify** | Health-checks the synced environment |
+
+## Installation
+
+```bash
+# Clone and install globally
+git clone https://github.com/vinhawk-66/claudekit-codex-sync.git
+cd claudekit-codex-sync
+npm install -g .
+```
+
+## Usage
+
+```bash
+# Sync from live ~/.claude/ directory
+ck-codex-sync --source-mode live
+
+# Sync from exported zip
+ck-codex-sync --zip claudekit-export.zip
+
+# Preview without changes
+ck-codex-sync --source-mode live --dry-run
+
+# Include MCP skills
+ck-codex-sync --source-mode live --include-mcp
+```
+
+## CLI Options
+
+```
+--source-mode live|zip|auto   Source selection (default: auto)
+--source-dir PATH             Custom source directory
+--zip PATH                    Specific zip file
+--codex-home PATH             Codex home (default: ~/.codex)
+--include-mcp                 Include MCP skills
+--include-hooks               Include hooks
+--skip-bootstrap              Skip dependency installation
+--skip-verify                 Skip runtime verification
+--skip-agent-toml             Skip agent TOML normalization
+--respect-edits               Backup user-edited files
+--dry-run                     Preview mode
+```
+
+## Agent Model Mapping
+
+Per [official Codex docs](https://developers.openai.com/codex/multi-agent), each agent role can override `model`, `model_reasoning_effort`, and `sandbox_mode`:
+
+| Claude Model | Codex Model | Reasoning | Used By |
+|---|---|---|---|
+| `opus` | `gpt-5.3-codex` | xhigh | planner, code_simplifier |
+| `sonnet` | `gpt-5.3-codex` | high | debugger, fullstack_developer |
+| `haiku` | `gpt-5.3-codex-spark` | medium | researcher, tester, docs_manager |
+
+Read-only agents (brainstormer, code_reviewer, researcher, project_manager, journal_writer) get `sandbox_mode = "read-only"`.
+
+## Related Tools
+
+- **[ccs](https://www.npmjs.com/package/@kaitranntt/ccs)** (`@kaitranntt/ccs`) — Claude Code Profile & Model Switcher. Allows running Claude Code with different model backends including Codex models via CLIProxy. Example: `ccs codex` launches Claude Code using Codex as the backend model.
+- **[Codex CLI](https://github.com/openai/codex)** (`@openai/codex`) — OpenAI's coding agent CLI.
+
+## Project Structure
+
+```
+├── bin/ck-codex-sync.js           # npm CLI entry point
+├── src/claudekit_codex_sync/      # Python modules (13 files, ~1500 LOC)
+│   ├── cli.py                     # Main orchestrator
+│   ├── source_resolver.py         # Source detection (live/zip/auto)
+│   ├── asset_sync_dir.py          # Directory-based sync
+│   ├── asset_sync_zip.py          # Zip-based sync
+│   ├── path_normalizer.py         # Path rewriting + agent .md→.toml
+│   ├── config_enforcer.py         # Config, multi-agent, agent registration
+│   ├── prompt_exporter.py         # Prompt file generation
+│   ├── bridge_generator.py        # Bridge skill for Codex
+│   ├── dep_bootstrapper.py        # Dependency installation
+│   ├── runtime_verifier.py        # Health checks
+│   ├── sync_registry.py           # Backup/registry (SHA-256)
+│   ├── constants.py               # Replacements, model maps
+│   └── utils.py                   # Shared utilities
+├── templates/                     # Template files for generated content
+├── tests/                         # pytest suite
+├── scripts/                       # Legacy standalone scripts
+└── docs/                          # Documentation
+```
+
+## Development
+
+```bash
+# Run tests
+PYTHONPATH=src python3 -m pytest tests/ -v
+
+# Lint
+python3 -m py_compile src/claudekit_codex_sync/*.py
+
+# Run sync locally
+PYTHONPATH=src python3 -m claudekit_codex_sync.cli --source-mode live --dry-run
+```
+
+## Documentation
+
+- [System Architecture](./docs/system-architecture.md)
+- [Code Standards](./docs/code-standards.md)
+- [Codebase Summary](./docs/codebase-summary.md)
+- [Project Roadmap](./docs/project-roadmap.md)
+- [Installation Guide](./docs/installation-guide.md)
+- [Codex vs Claude Agents](./docs/codex-vs-claude-agents.md)
+- [Project Overview (PDR)](./docs/project-overview-pdr.md)
+
+## License
+
+MIT

package/bin/ck-codex-sync

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+import sys
+from pathlib import Path
+
+# Add src to path
+src_dir = Path(__file__).parent.parent / "src"
+sys.path.insert(0, str(src_dir))
+
+from claudekit_codex_sync.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bin/ck-codex-sync.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+const { execSync } = require('child_process');
+const path = require('path');
+const script = path.join(__dirname, 'ck-codex-sync');
+try {
+  execSync(`python3 "${script}" ${process.argv.slice(2).join(' ')}`, { stdio: 'inherit' });
+} catch (e) {
+  process.exit(e.status || 1);
+}

package/docs/code-standards.md

@@ -0,0 +1,62 @@
+# Code Standards
+
+## Language & Runtime
+
+- **Python 3.12+** — Core sync logic
+- **Node.js** — CLI wrapper only (`bin/ck-codex-sync.js`)
+- No external Python dependencies in core (stdlib only: `pathlib`, `re`, `shutil`, `json`, `zipfile`, `argparse`, `hashlib`)
+
+## File Organization
+
+- **Kebab-case** for filenames: `asset-sync-dir.py` (Python uses snake_case for modules, so `asset_sync_dir.py`)
+- **Max 200 LOC** per module — enforced; largest is `path_normalizer.py` at 248 (due to agent conversion addition, refactor candidate)
+- **One concern per module** — each `.py` file handles exactly one phase of the sync pipeline
+- Constants separated into `constants.py`; utilities into `utils.py`
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---|---|---|
+| Modules | `snake_case` | `config_enforcer.py` |
+| Functions | `snake_case` | `enforce_multi_agent_flag()` |
+| Constants | `UPPER_SNAKE_CASE` | `CLAUDE_TO_CODEX_MODELS` |
+| Classes | `PascalCase` (none yet) | — |
+| Template files | `kebab-case` | `bridge-skill.md` |
+
+## Function Signatures
+
+All public functions follow the pattern:
+```python
+def function_name(*, codex_home: Path, dry_run: bool) -> int:
+    """One-line docstring."""
+```
+
+- Keyword-only args (`*` marker) for clarity
+- `dry_run` flag on all write operations
+- Return `int` (count of changed files) or `bool` (whether changes made)
+- `Dict[str, Any]` for stats output
+
+## Error Handling
+
+- Custom `SyncError` exception for user-facing errors
+- `eprint()` for stderr output
+- CLI catches `SyncError` → exits with code 2
+- No silent failures — all operations log what they change
+
+## Testing
+
+- Framework: **pytest**
+- Location: `tests/`
+- Naming: `test_<module>.py`
+- Run: `PYTHONPATH=src python3 -m pytest tests/ -v`
+- Current coverage: `config_enforcer` (4 tests), `path_normalizer` (7 tests)
+
+## Path Conventions
+
+All paths use `Path` objects (not strings). Environment-based paths use `${CODEX_HOME:-$HOME/.codex}` pattern.
+
+## Git Conventions
+
+- Conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
+- No AI references in commit messages
+- `.gitignore`: `__pycache__/`, `*.pyc`, `node_modules/`, `.pytest_cache/`

package/docs/codebase-summary.md

@@ -0,0 +1,83 @@
+# Codebase Summary
+
+## Overview
+
+**claudekit-codex-sync** bridges ClaudeKit (`~/.claude/`) to Codex CLI (`~/.codex/`) by syncing skills, agents, prompts, and configuration. Written primarily in Python with a Node.js CLI wrapper.
+
+## Stats
+
+| Component | Files | LOC | Purpose |
+|---|---|---|---|
+| `src/claudekit_codex_sync/` | 13 | ~1500 | Core Python modules |
+| `templates/` | 5 | ~280 | Generated file templates |
+| `tests/` | 2 | ~106 | pytest-based test suite |
+| `scripts/` | 4 | ~1780 | Legacy standalone scripts |
+| `bin/` | 2 | ~20 | npm CLI entry point |
+
+## Module Map
+
+### Core Orchestration
+
+- **`cli.py`** (199 LOC) — Main entry point. Parses args, coordinates all sync phases, outputs JSON summary. Supports `live` (directory) and `zip` source modes.
+
+### Source Resolution
+
+- **`source_resolver.py`** (78 LOC) — Detects ClaudeKit source: `~/.claude/` for live mode, finds latest zip for zip mode. Validates source has required structure.
+
+### Asset Sync
+
+- **`asset_sync_dir.py`** (125 LOC) — Copies assets and skills from a live `~/.claude/` directory to `~/.codex/`. Handles `ASSET_DIRS` (agents, commands, rules, scripts) and `ASSET_FILES`.
+- **`asset_sync_zip.py`** (140 LOC) — Same as above but from a ClaudeKit export zip file.
+
+### Path Normalization
+
+- **`path_normalizer.py`** (248 LOC) — Rewrites `.claude` → `.codex` paths in all synced files. Also converts ClaudeKit agent `.md` files (with YAML frontmatter) to Codex `.toml` format with correct model mapping.
+- **`constants.py`** (104 LOC) — All replacement patterns (`SKILL_MD_REPLACEMENTS`, `AGENT_TOML_REPLACEMENTS`, `CLAUDE_SYNTAX_ADAPTATIONS`), model mapping tables, and read-only role sets.
+
+### Configuration
+
+- **`config_enforcer.py`** (140 LOC) — Ensures `config.toml` has correct structure, enforces `multi_agent` + `child_agents_md` feature flags, auto-registers `[agents.*]` sections from TOML files.
+
+### Prompt & Bridge
+
+- **`prompt_exporter.py`** (89 LOC) — Exports ClaudeKit prompts to Codex-compatible format.
+- **`bridge_generator.py`** (33 LOC) — Creates a bridge skill in `~/.codex/skills/claudekit-command-bridge/`.
+
+### Support
+
+- **`dep_bootstrapper.py`** (73 LOC) — Installs Python/Node dependencies for skills that require them.
+- **`runtime_verifier.py`** (32 LOC) — Verifies synced environment health (codex help, copywriting, prompt count, skill count).
+- **`sync_registry.py`** (77 LOC) — SHA-256 checksum registry for tracking synced files and detecting user edits.
+- **`utils.py`** (130 LOC) — Shared utilities: `apply_replacements()`, `load_template()`, `write_text_if_changed()`, `SyncError`.
+
+## Data Flow
+
+```
+Source (~/.claude/ or zip)
+    ↓
+source_resolver.py → detect source type
+    ↓
+asset_sync_dir/zip.py → copy agents, skills, commands
+    ↓
+path_normalizer.py → rewrite paths + convert .md→.toml agents
+    ↓
+config_enforcer.py → update config.toml + register agents
+    ↓
+prompt_exporter.py → generate prompt files
+    ↓
+dep_bootstrapper.py → install skill dependencies
+    ↓
+runtime_verifier.py → health check
+    ↓
+Output: ~/.codex/ fully configured for Codex CLI
+```
+
+## Test Coverage
+
+| File | Tests | Coverage |
+|---|---|---|
+| `config_enforcer.py` | 4 | Feature flag enforcement |
+| `path_normalizer.py` | 7 | Path replacement patterns |
+| **Total** | **11** | Core functionality |
+
+Untested modules (need coverage): `cli.py`, `asset_sync_dir.py`, `asset_sync_zip.py`, `source_resolver.py`, `prompt_exporter.py`, `dep_bootstrapper.py`, `runtime_verifier.py`, `sync_registry.py`, `bridge_generator.py`, `utils.py`.

package/docs/codex-vs-claude-agents.md

@@ -0,0 +1,74 @@
+# Codex vs Claude Agents
+
+This document outlines the differences between Claude Code agents and Codex agents, and what is lost or preserved during sync.
+
+## Key Differences
+
+| Feature | Claude Code | Codex CLI |
+|---------|-------------|-----------|
+| **Agent Definition** | TOML files with `[[agents]]` sections | TOML files with `[[agents]]` sections |
+| **Model Selection** | `model` frontmatter field | No per-agent model selection |
+| **Tool Restrictions** | `tools` frontmatter field | No tool restrictions (all tools available) |
+| **Memory** | `memory` frontmatter field | `developer_instructions` text only |
+| **Delegation** | `Task()` tool for explicit delegation | Auto-spawn via `multi_agent = true` |
+
+## What Transfers
+
+The following are preserved during ClaudeKit -> Codex sync:
+
+- **Agent name and description** - Basic identity
+- **Developer instructions** - Core behavior guidance
+- **Sandbox mode settings** - Security constraints
+- **Agent file structure** - Organized in `~/.codex/agents/`
+
+## What's Lost
+
+The following Claude-specific features are stripped or adapted:
+
+1. **Explicit Task() delegation syntax**
+   - Claude: `Task(subagent_type="researcher", ...)`
+   - Codex: Auto-spawn based on context
+
+2. **Tool restrictions**
+   - Claude: `tools = ["Read", "Grep", "Edit"]` limits available tools
+   - Codex: All tools available to all agents
+
+3. **Model selection**
+   - Claude: `model = "haiku"` for cost/performance tuning
+   - Codex: Single model for all operations
+
+4. **Memory configuration**
+   - Claude: `memory` section with context management
+   - Codex: Instructions embedded in developer text
+
+## Path Normalization
+
+Agent TOMLs are automatically normalized during sync:
+
+```diff
+- $HOME/.claude/skills/
++ ${CODEX_HOME:-$HOME/.codex}/skills/
+
+- ~/.claude/
++ ~/.codex/
+```
+
+## Multi-Agent Configuration
+
+After sync, enable multi-agent mode:
+
+```toml
+[features]
+multi_agent = true
+```
+
+This allows Codex to auto-spawn sub-agents based on task context, similar to Claude's `Task()` delegation but without explicit syntax.
+
+## Recommendation
+
+For maximum compatibility:
+
+1. Write agent instructions assuming all tools are available
+2. Use natural language for delegation intent (e.g., "use the researcher agent")
+3. Keep agent instructions under 2000 tokens
+4. Test agents after sync to verify behavior

package/docs/installation-guide.md

@@ -0,0 +1,64 @@
+# Installation Guide
+
+## Prerequisites
+
+- Python 3.9+
+- Node.js 18+ (for npm installation)
+- Codex CLI installed
+
+## Install from Source
+
+```bash
+cd /home/vinhawk/claudekit-codex-sync
+npm install -g .
+```
+
+## Verify Installation
+
+```bash
+ck-codex-sync --help
+```
+
+## Usage
+
+### Basic Sync (from zip)
+
+```bash
+ck-codex-sync
+```
+
+### Live Source Mode (from ~/.claude/)
+
+```bash
+ck-codex-sync --source-mode live
+```
+
+### Include MCP Skills
+
+```bash
+ck-codex-sync --include-mcp
+```
+
+### Dry Run
+
+```bash
+ck-codex-sync --dry-run
+```
+
+## Configuration
+
+The tool automatically configures:
+
+- `~/.codex/config.toml` - Codex configuration
+- `~/.codex/agents/` - Agent definitions
+- `~/.codex/skills/` - Skill definitions
+- `~/.codex/prompts/` - Custom prompts
+
+## Post-Install Verification
+
+```bash
+# Check multi-agent is enabled
+codex features list | grep multi_agent
+
+# Should show: multi_agent    experimental    true
+```

package/docs/project-overview-pdr.md

@@ -0,0 +1,44 @@
+# Project Overview — PDR
+
+## Product
+
+**claudekit-codex-sync** — CLI tool that syncs ClaudeKit configuration to OpenAI Codex CLI.
+
+## Problem Statement
+
+ClaudeKit users who also use Codex CLI face duplicate setup: re-configuring agents, skills, prompts, and paths. The two platforms use incompatible formats (ClaudeKit: Markdown agents with YAML frontmatter, Claude model names; Codex: TOML agents, GPT model names).
+
+## Solution
+
+A single-command sync tool that:
+1. Copies all assets from `~/.claude/` → `~/.codex/`
+2. Rewrites paths (`.claude` → `.codex`)
+3. Converts agent definitions (`.md` → `.toml`)
+4. Maps model names (`opus` → `gpt-5.3-codex`, `haiku` → `gpt-5.3-codex-spark`)
+5. Configures multi-agent features and registers agent roles
+
+## Target Users
+
+ClaudeKit power-users who also use or are migrating to Codex CLI.
+
+## Key Metrics
+
+- Zero manual configuration needed after sync
+- All synced agents load correctly in Codex
+- No `.claude` path references remain in synced files
+- 14+ agent roles with correct model assignments
+
+## Status
+
+**v0.1.0** — Functional. All core features implemented:
+- [x] Live directory sync
+- [x] Zip archive sync
+- [x] Path normalization (37+ files per sync)
+- [x] Agent .md → .toml conversion with model mapping
+- [x] Multi-agent config (multi_agent + child_agents_md)
+- [x] Agent registration (14 roles)
+- [x] Prompt export (20+ prompts)
+- [x] Dependency bootstrap
+- [x] Runtime verification
+- [ ] Full test coverage (11/~40 target tests)
+- [ ] Idempotent re-sync (partial — registry exists but not fully wired)

package/docs/project-roadmap.md

@@ -0,0 +1,51 @@
+# Project Roadmap
+
+## v0.1.0 — Initial Release ✅
+
+**Status:** Complete
+
+- [x] Project structure (modular Python, npm wrapper)
+- [x] Dual source support (live directory + zip archive)
+- [x] Path normalization (`.claude` → `.codex`)
+- [x] Asset sync (agents, commands, rules, scripts)
+- [x] Skill sync (54+ skills)
+- [x] Agent .md → .toml conversion
+- [x] Claude → Codex model mapping
+- [x] Multi-agent config enforcement
+- [x] Agent registration in config.toml
+- [x] Prompt export
+- [x] Dependency bootstrap
+- [x] Runtime verification
+- [x] Basic test suite (11 tests)
+- [x] Documentation (README, architecture, code standards)
+
+## v0.2.0 — Quality & Coverage
+
+**Status:** Planned
+
+- [ ] Full test coverage for all 13 modules
+- [ ] Integration tests (end-to-end sync flow)
+- [ ] Idempotent re-sync (skip unchanged files)
+- [ ] `--respect-edits` fully wired (detect user modifications via SHA-256)
+- [ ] Proper error messages for common failures
+- [ ] `path_normalizer.py` refactor (currently 248 LOC, split conversion out)
+
+## v0.3.0 — Distribution
+
+**Status:** Planned
+
+- [ ] PyPI package (alongside npm)
+- [ ] CI/CD pipeline (GitHub Actions)
+- [ ] Versioned releases with changelog
+- [ ] Community contribution guide
+- [ ] Cross-platform testing (Linux, macOS, WSL)
+
+## v0.4.0 — Advanced Features
+
+**Status:** Future
+
+- [ ] Incremental sync (only changed files)
+- [ ] Watch mode (auto-sync on file changes)
+- [ ] Custom model mapping config (user-defined model overrides)
+- [ ] MCP server migration support
+- [ ] Bi-directional sync (Codex → ClaudeKit)

package/docs/system-architecture.md

@@ -0,0 +1,106 @@
+# System Architecture
+
+## High-Level Design
+
+```
+┌─────────────────────┐    ┌──────────────────────────┐
+│ ClaudeKit Source     │    │ Codex CLI Target          │
+│ ~/.claude/           │───▶│ ~/.codex/                 │
+│   agents/*.md        │    │   agents/*.toml           │
+│   skills/*/SKILL.md  │    │   skills/*/SKILL.md       │
+│   commands/          │    │   claudekit/commands/     │
+│   rules/             │    │   claudekit/rules/        │
+│   scripts/           │    │   claudekit/scripts/      │
+│   prompts/           │    │   prompts/                │
+└─────────────────────┘    │   config.toml             │
+                            │   AGENTS.md               │
+                            └──────────────────────────┘
+```
+
+## Component Architecture
+
+### Pipeline Pattern
+
+The sync follows a sequential pipeline with 8 stages:
+
+1. **Source Resolution** (`source_resolver.py`) — Determine input type (live dir or zip)
+2. **Asset Sync** (`asset_sync_dir.py` / `asset_sync_zip.py`) — Copy files with dedup
+3. **Path Normalization** (`path_normalizer.py`) — Text replacement across all files
+4. **Agent Conversion** (`path_normalizer.py`) — `.md` → `.toml` with model mapping
+5. **Config Enforcement** (`config_enforcer.py`) — TOML config + agent registration
+6. **Prompt Export** (`prompt_exporter.py`) — Generate Codex prompt files
+7. **Dependency Bootstrap** (`dep_bootstrapper.py`) — Install Python/Node deps
+8. **Runtime Verification** (`runtime_verifier.py`) — Health check
+
+### Source Modes
+
+| Mode | Input | Detection |
+|---|---|---|
+| `live` | `~/.claude/` directory | `--source-mode live` |
+| `zip` | ClaudeKit export `.zip` | Scans cwd for zips |
+| `auto` | Either | Prefers live if `--source-dir` set |
+
+### Agent Conversion Pipeline
+
+```
+ClaudeKit .md (YAML frontmatter)
+  │  name: planner
+  │  model: opus
+  │  tools: Glob, Grep, Read, ...
+  │  ---
+  │  You are an expert planner...
+  ▼
+convert_agents_md_to_toml()
+  │  Parse YAML frontmatter
+  │  Map model: opus → gpt-5.3-codex
+  │  Set effort: xhigh
+  │  Set sandbox: workspace-write/read-only
+  ▼
+Codex .toml
+  │  model = "gpt-5.3-codex"
+  │  model_reasoning_effort = "xhigh"
+  │  sandbox_mode = "workspace-write"
+  │  developer_instructions = """..."""
+  ▼
+config.toml [agents.planner]
+  │  description = "..."
+  │  config_file = "agents/planner.toml"
+```
+
+### Config.toml Structure
+
+```toml
+# Global settings
+model = "gpt-5.3-codex"
+model_reasoning_effort = "xhigh"
+
+[features]
+multi_agent = true
+child_agents_md = true
+
+[agents.planner]
+description = "Expert planner for architecture and design"
+config_file = "agents/planner.toml"
+
+[agents.researcher]
+description = "Technology researcher with read-only access"
+config_file = "agents/researcher.toml"
+```
+
+## Technology Stack
+
+| Layer | Technology |
+|---|---|
+| CLI wrapper | Node.js (`bin/ck-codex-sync.js`) |
+| Core logic | Python 3.12+ |
+| Config format | TOML |
+| Package manager | npm (distribution), pip (skill deps) |
+| Testing | pytest |
+| Target platform | OpenAI Codex CLI v0.105+ |
+
+## Key Design Decisions
+
+1. **Python core with Node wrapper** — Python for text processing strength; Node wrapper for `npm install -g` distribution via npm ecosystem.
+2. **Text replacement strategy** — Uses ordered replacement tuples (not regex) for predictable, deterministic path rewriting. More specific patterns listed first to prevent partial matches.
+3. **Model mapping at sync time** — Converts Claude model names to Codex equivalents during sync rather than at runtime, so Codex reads native model names.
+4. **Dual source support** — Both live directory and zip modes allow CI/CD sync from exports and local dev sync from live Claude install.