From 1b22ef22eae2e2cb8a9777ca6c986f5ff2754b8a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 31 Mar 2026 04:54:57 +0000
Subject: [PATCH 1/9] Initial plan


From 81432b4c48fc5943262cec7011ca25ca28256edf Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 31 Mar 2026 05:02:08 +0000
Subject: [PATCH 2/9] Initial plan for Codex CLI integration target

Agent-Logs-Url: https://github.com/microsoft/apm/sessions/4df682f5-8518-41bb-888a-e5474153262f

Co-authored-by: danielmeppiel <51440732+danielmeppiel@users.noreply.github.com>
---
 uv.lock | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/uv.lock b/uv.lock
index 3246ec7c..c35c123c 100644
--- a/uv.lock
+++ b/uv.lock
@@ -179,7 +179,7 @@ wheels = [
 
 [[package]]
 name = "apm-cli"
-version = "0.8.6"
+version = "0.8.7"
 source = { editable = "." }
 dependencies = [
     { name = "click" },

From 8fe53134b61816e3bb71c7aa3b8ff5b467751efe Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 31 Mar 2026 05:08:33 +0000
Subject: [PATCH 3/9] feat: add Codex CLI as integration target (Wave 1+2)

- Add deploy_root field to PrimitiveMapping for cross-root deployments
- Register Codex target in KNOWN_TARGETS with agents (.toml), skills (.agents/), hooks (.codex/hooks.json)
- Update get_integration_prefixes() to include deploy_root prefixes (.agents/)
- Add "codex" to --target CLI choices (install, compile, pack)
- Update partition_managed_files to handle deploy_root and empty subdirs
- Add _write_codex_agent() MD->TOML transformer to AgentIntegrator
- Add integrate_package_hooks_codex() to HookIntegrator (Cursor-pattern merge)
- Teach SkillIntegrator about deploy_root for .agents/skills/ deployment
- Update all integrator sync_for_target and path computation for deploy_root
- Update install.py log output for Codex hook and deploy dirs
- Update uninstall engine to handle deploy_root paths

Agent-Logs-Url: https://github.com/microsoft/apm/sessions/4df682f5-8518-41bb-888a-e5474153262f

Co-authored-by: danielmeppiel <51440732+danielmeppiel@users.noreply.github.com>
---
 src/apm_cli/commands/compile/cli.py           |  2 +-
 src/apm_cli/commands/install.py               | 10 +-
 src/apm_cli/commands/pack.py                  |  2 +-
 src/apm_cli/commands/uninstall/engine.py      | 19 ++--
 src/apm_cli/integration/agent_integrator.py   | 62 +++++++++++-
 src/apm_cli/integration/base_integrator.py    |  5 +-
 src/apm_cli/integration/command_integrator.py | 10 +-
 src/apm_cli/integration/hook_integrator.py    | 97 +++++++++++++++++++
 .../integration/instruction_integrator.py     | 10 +-
 src/apm_cli/integration/prompt_integrator.py  |  8 +-
 src/apm_cli/integration/skill_integrator.py   | 22 ++++-
 src/apm_cli/integration/targets.py            | 48 ++++++++-
 12 files changed, 259 insertions(+), 36 deletions(-)

diff --git a/src/apm_cli/commands/compile/cli.py b/src/apm_cli/commands/compile/cli.py
index e29f5a17..29cf77b5 100644
--- a/src/apm_cli/commands/compile/cli.py
+++ b/src/apm_cli/commands/compile/cli.py
@@ -172,7 +172,7 @@ def _get_validation_suggestion(error_msg):
 @click.option(
     "--target",
     "-t",
-    type=click.Choice(["copilot", "vscode", "agents", "claude", "cursor", "opencode", "all"]),
+    type=click.Choice(["copilot", "vscode", "agents", "claude", "cursor", "opencode", "codex", "all"]),
     default=None,
     help="Target platform: copilot (AGENTS.md), claude (CLAUDE.md), cursor, opencode, or all. 'vscode' and 'agents' are deprecated aliases for 'copilot'. Auto-detects if not specified.",
 )
diff --git a/src/apm_cli/commands/install.py b/src/apm_cli/commands/install.py
index 3b5b8ff2..b01455ae 100644
--- a/src/apm_cli/commands/install.py
+++ b/src/apm_cli/commands/install.py
@@ -540,7 +540,7 @@ def _check_repo_fallback(token, git_env):
     "-t",
     "target",
     type=click.Choice(
-        ["copilot", "claude", "cursor", "opencode", "vscode", "agents", "all"],
+        ["copilot", "claude", "cursor", "opencode", "codex", "vscode", "agents", "all"],
         case_sensitive=False,
     ),
     default=None,
@@ -907,8 +907,11 @@ def _log_integration(msg):
                         _hook_dir = ".claude/settings.json"
                     elif _target.name == "cursor":
                         _hook_dir = ".cursor/hooks.json"
+                    elif _target.name == "codex":
+                        _hook_dir = ".codex/hooks.json"
                     else:
-                        _hook_dir = f"{_target.root_dir}/{_mapping.subdir}/"
+                        _effective_root = _mapping.deploy_root or _target.root_dir
+                        _hook_dir = f"{_effective_root}/{_mapping.subdir}/" if _mapping.subdir else f"{_effective_root}/"
                     _log_integration(
                         f"  |-- {hook_result.hooks_integrated} hook(s) integrated -> {_hook_dir}"
                     )
@@ -928,7 +931,8 @@ def _log_integration(msg):
             )
             if _int_result.files_integrated > 0:
                 result[_counter_key] += _int_result.files_integrated
-                _deploy_dir = f"{_target.root_dir}/{_mapping.subdir}/"
+                _effective_root = _mapping.deploy_root or _target.root_dir
+                _deploy_dir = f"{_effective_root}/{_mapping.subdir}/"
                 if _prim_name == "instructions" and _mapping.format_id == "cursor_rules":
                     _label = "rule(s)"
                 elif _prim_name == "instructions":
diff --git a/src/apm_cli/commands/pack.py b/src/apm_cli/commands/pack.py
index 6f7fa8e9..d2621cd6 100644
--- a/src/apm_cli/commands/pack.py
+++ b/src/apm_cli/commands/pack.py
@@ -21,7 +21,7 @@
 @click.option(
     "--target",
     "-t",
-    type=click.Choice(["copilot", "vscode", "claude", "cursor", "opencode", "all"]),
+    type=click.Choice(["copilot", "vscode", "claude", "cursor", "opencode", "codex", "all"]),
     default=None,
     help="Filter files by target (default: auto-detect). 'vscode' is a deprecated alias for 'copilot'.",
 )
diff --git a/src/apm_cli/commands/uninstall/engine.py b/src/apm_cli/commands/uninstall/engine.py
index 25c218a2..87585291 100644
--- a/src/apm_cli/commands/uninstall/engine.py
+++ b/src/apm_cli/commands/uninstall/engine.py
@@ -266,8 +266,8 @@ def _sync_integrations_after_uninstall(apm_package, project_root, all_deployed_f
             if not _entry:
                 continue
             _integrator, _counter_key = _entry
-            _prefix = f"{_target.root_dir}/{_mapping.subdir}/"
-            _deploy_dir = project_root / _target.root_dir / _mapping.subdir
+            _effective_root = _mapping.deploy_root or _target.root_dir
+            _deploy_dir = project_root / _effective_root / _mapping.subdir
             if not _deploy_dir.exists():
                 continue
             _managed_subset = None
@@ -283,11 +283,16 @@ def _sync_integrations_after_uninstall(apm_package, project_root, all_deployed_f
             counts[_counter_key] += result.get("files_removed", 0)
 
     # Skills (multi-target, handled by SkillIntegrator)
-    if any(
-        (project_root / t.root_dir / "skills").exists()
-        for t in KNOWN_TARGETS.values()
-        if t.supports("skills")
-    ):
+    # Check both target root_dir and deploy_root for skill directories
+    _skill_dirs_exist = False
+    for t in KNOWN_TARGETS.values():
+        if t.supports("skills"):
+            sm = t.primitives["skills"]
+            er = sm.deploy_root or t.root_dir
+            if (project_root / er / "skills").exists():
+                _skill_dirs_exist = True
+                break
+    if _skill_dirs_exist:
         integrator = SkillIntegrator()
         result = integrator.sync_integration(apm_package, project_root,
                                              managed_files=_buckets["skills"] if _buckets else None)
diff --git a/src/apm_cli/integration/agent_integrator.py b/src/apm_cli/integration/agent_integrator.py
index b1842a07..d48a2b70 100644
--- a/src/apm_cli/integration/agent_integrator.py
+++ b/src/apm_cli/integration/agent_integrator.py
@@ -7,6 +7,7 @@
 
 from __future__ import annotations
 
+import re
 from pathlib import Path
 from typing import TYPE_CHECKING, Dict, List
 
@@ -109,8 +110,9 @@ def integrate_agents_for_target(
         if not mapping:
             return IntegrationResult(0, 0, 0, [])
 
-        target_root = project_root / target.root_dir
-        if not target.auto_create and not target_root.is_dir():
+        effective_root = mapping.deploy_root or target.root_dir
+        target_root = project_root / effective_root
+        if not target.auto_create and not (project_root / target.root_dir).is_dir():
             return IntegrationResult(0, 0, 0, [])
 
         self.init_link_resolver(package_info, project_root)
@@ -140,7 +142,11 @@ def integrate_agents_for_target(
                 files_skipped += 1
                 continue
 
-            links_resolved = self.copy_agent(source_file, target_path)
+            if mapping.format_id == "codex_agent":
+                self._write_codex_agent(source_file, target_path)
+                links_resolved = 0
+            else:
+                links_resolved = self.copy_agent(source_file, target_path)
             total_links_resolved += links_resolved
             files_integrated += 1
             target_paths.append(target_path)
@@ -164,8 +170,9 @@ def sync_for_target(
         mapping = target.primitives.get("agents")
         if not mapping:
             return {"files_removed": 0, "errors": 0}
-        prefix = f"{target.root_dir}/{mapping.subdir}/"
-        legacy_dir = project_root / target.root_dir / mapping.subdir
+        effective_root = mapping.deploy_root or target.root_dir
+        prefix = f"{effective_root}/{mapping.subdir}/"
+        legacy_dir = project_root / effective_root / mapping.subdir
         # Copilot uses .agent.md suffix; others use plain .md
         legacy_pattern = "*-apm.agent.md" if mapping.extension == ".agent.md" else "*-apm.md"
         return self.sync_remove_files(
@@ -202,6 +209,51 @@ def copy_agent(self, source: Path, target: Path) -> int:
         content, links_resolved = self.resolve_links(content, source, target)
         target.write_text(content, encoding='utf-8')
         return links_resolved
+
+    # ------------------------------------------------------------------
+    # Codex agent transformer (MD -> TOML)
+    # ------------------------------------------------------------------
+
+    _FRONTMATTER_RE = re.compile(
+        r"^---\s*\n(.*?)\n---\s*\n?",
+        re.DOTALL,
+    )
+
+    @staticmethod
+    def _write_codex_agent(source: Path, target: Path) -> None:
+        """Transform an ``.agent.md`` file to Codex ``.toml`` format.
+
+        Parses YAML frontmatter for ``name`` and ``description``, uses
+        the markdown body as ``developer_instructions``.
+        """
+        import toml as _toml
+
+        content = source.read_text(encoding="utf-8")
+
+        name = source.stem
+        if name.endswith(".agent"):
+            name = name[: -len(".agent")]
+        description = ""
+        body = content
+
+        fm_match = AgentIntegrator._FRONTMATTER_RE.match(content)
+        if fm_match:
+            body = content[fm_match.end():]
+            try:
+                import yaml
+
+                fm = yaml.safe_load(fm_match.group(1)) or {}
+                name = fm.get("name", name)
+                description = fm.get("description", description)
+            except Exception:
+                pass
+
+        doc = {
+            "name": name,
+            "description": description,
+            "developer_instructions": body.strip(),
+        }
+        target.write_text(_toml.dumps(doc), encoding="utf-8")
     
     def integrate_package_agents(self, package_info, project_root: Path,
                                    force: bool = False,
diff --git a/src/apm_cli/integration/base_integrator.py b/src/apm_cli/integration/base_integrator.py
index bd407a15..05cfab3c 100644
--- a/src/apm_cli/integration/base_integrator.py
+++ b/src/apm_cli/integration/base_integrator.py
@@ -184,7 +184,8 @@ def partition_managed_files(
 
         for target in KNOWN_TARGETS.values():
             for prim_name, mapping in target.primitives.items():
-                prefix = f"{target.root_dir}/{mapping.subdir}/"
+                effective_root = mapping.deploy_root or target.root_dir
+                prefix = f"{effective_root}/{mapping.subdir}/" if mapping.subdir else f"{effective_root}/"
                 if prim_name == "skills":
                     skill_prefixes.append(prefix)
                 elif prim_name == "hooks":
@@ -197,7 +198,7 @@ def partition_managed_files(
                     if bucket_key not in buckets:
                         buckets[bucket_key] = set()
                     component_map[
-                        (target.root_dir, mapping.subdir)
+                        (effective_root, mapping.subdir)
                     ] = bucket_key
 
         buckets["skills"] = set()
diff --git a/src/apm_cli/integration/command_integrator.py b/src/apm_cli/integration/command_integrator.py
index 4628b2a4..0795c584 100644
--- a/src/apm_cli/integration/command_integrator.py
+++ b/src/apm_cli/integration/command_integrator.py
@@ -130,8 +130,9 @@ def integrate_commands_for_target(
         if not mapping:
             return IntegrationResult(0, 0, 0, [], 0)
 
-        target_root = project_root / target.root_dir
-        if not target.auto_create and not target_root.is_dir():
+        effective_root = mapping.deploy_root or target.root_dir
+        target_root = project_root / effective_root
+        if not target.auto_create and not (project_root / target.root_dir).is_dir():
             return IntegrationResult(0, 0, 0, [], 0)
 
         prompt_files = self.find_prompt_files(package_info.install_path)
@@ -189,8 +190,9 @@ def sync_for_target(
         mapping = target.primitives.get("commands")
         if not mapping:
             return {"files_removed": 0, "errors": 0}
-        prefix = f"{target.root_dir}/{mapping.subdir}/"
-        legacy_dir = project_root / target.root_dir / mapping.subdir
+        effective_root = mapping.deploy_root or target.root_dir
+        prefix = f"{effective_root}/{mapping.subdir}/"
+        legacy_dir = project_root / effective_root / mapping.subdir
         return self.sync_remove_files(
             project_root,
             managed_files,
diff --git a/src/apm_cli/integration/hook_integrator.py b/src/apm_cli/integration/hook_integrator.py
index 23f05937..9ff9e55e 100644
--- a/src/apm_cli/integration/hook_integrator.py
+++ b/src/apm_cli/integration/hook_integrator.py
@@ -156,6 +156,8 @@ def _rewrite_command_for_target(
             scripts_base = f".github/hooks/scripts/{package_name}"
         elif target == "cursor":
             scripts_base = f".cursor/hooks/{package_name}"
+        elif target == "codex":
+            scripts_base = f".codex/hooks/{package_name}"
         else:
             scripts_base = f".claude/hooks/{package_name}"
 
@@ -545,6 +547,89 @@ def integrate_package_hooks_cursor(self, package_info, project_root: Path,
             target_paths=target_paths,
         )
 
+    def integrate_package_hooks_codex(self, package_info, project_root: Path,
+                                      force: bool = False,
+                                      managed_files: set = None,
+                                      diagnostics=None) -> HookIntegrationResult:
+        """Integrate hooks from a package into .codex/hooks.json (Codex target).
+
+        Follows the same merge pattern as Cursor: additive merge with
+        ``_apm_source`` markers for safe cleanup.  Script files are
+        copied to ``.codex/hooks/{package_name}/``.
+
+        Codex hook events: ``SessionStart``, ``PreToolUse``,
+        ``PostToolUse``, ``UserPromptSubmit``, ``Stop``.
+        """
+        codex_dir = project_root / ".codex"
+        if not codex_dir.exists():
+            return HookIntegrationResult(hooks_integrated=0, scripts_copied=0)
+
+        hook_files = self.find_hook_files(package_info.install_path)
+        if not hook_files:
+            return HookIntegrationResult(hooks_integrated=0, scripts_copied=0)
+
+        package_name = self._get_package_name(package_info)
+        hooks_integrated = 0
+        scripts_copied = 0
+        target_paths: List[Path] = []
+
+        hooks_json_path = codex_dir / "hooks.json"
+        hooks_config: Dict = {}
+        if hooks_json_path.exists():
+            try:
+                with open(hooks_json_path, 'r', encoding='utf-8') as f:
+                    hooks_config = json.load(f)
+            except (json.JSONDecodeError, OSError):
+                hooks_config = {}
+
+        if "hooks" not in hooks_config:
+            hooks_config["hooks"] = {}
+
+        for hook_file in hook_files:
+            data = self._parse_hook_json(hook_file)
+            if data is None:
+                continue
+
+            rewritten, scripts = self._rewrite_hooks_data(
+                data, package_info.install_path, package_name, "codex",
+                hook_file_dir=hook_file.parent,
+            )
+
+            hooks = rewritten.get("hooks", {})
+            for event_name, entries in hooks.items():
+                if not isinstance(entries, list):
+                    continue
+                if event_name not in hooks_config["hooks"]:
+                    hooks_config["hooks"][event_name] = []
+
+                for entry in entries:
+                    if isinstance(entry, dict):
+                        entry["_apm_source"] = package_name
+
+                hooks_config["hooks"][event_name].extend(entries)
+
+            hooks_integrated += 1
+
+            for source_file, target_rel in scripts:
+                target_script = project_root / target_rel
+                if self.check_collision(target_script, target_rel, managed_files, force, diagnostics=diagnostics):
+                    continue
+                target_script.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(source_file, target_script)
+                scripts_copied += 1
+                target_paths.append(target_script)
+
+        hooks_json_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(hooks_json_path, 'w', encoding='utf-8') as f:
+            json.dump(hooks_config, f, indent=2)
+            f.write('\n')
+
+        return HookIntegrationResult(
+            hooks_integrated=hooks_integrated,
+            scripts_copied=scripts_copied,
+            target_paths=target_paths,
+        )
+
     # ------------------------------------------------------------------
     # Target-driven API (thin wrappers — HookIntegrator keeps genuine
     # algorithmic diversity per-target, so we dispatch by target.name)
@@ -583,6 +668,12 @@ def integrate_hooks_for_target(
                 force=force, managed_files=managed_files,
                 diagnostics=diagnostics,
             )
+        if target.name == "codex":
+            return self.integrate_package_hooks_codex(
+                package_info, project_root,
+                force=force, managed_files=managed_files,
+                diagnostics=diagnostics,
+            )
         return HookIntegrationResult(hooks_integrated=0, scripts_copied=0)
 
     def sync_integration(self, apm_package, project_root: Path,
@@ -611,6 +702,7 @@ def sync_integration(self, apm_package, project_root: Path,
                     normalized.startswith(".github/hooks/")
                     or normalized.startswith(".claude/hooks/")
                     or normalized.startswith(".cursor/hooks/")
+                    or normalized.startswith(".codex/hooks/")
                 )
                 if not is_hook or ".." in rel_path:
                     continue
@@ -673,6 +765,11 @@ def sync_integration(self, apm_package, project_root: Path,
             project_root / ".cursor" / "hooks.json", stats,
         )
 
+        # Clean APM entries from .codex/hooks.json (safe  -- uses _apm_source marker)
+        self._clean_apm_entries_from_json(
+            project_root / ".codex" / "hooks.json", stats,
+        )
+
         return stats
 
     @staticmethod
diff --git a/src/apm_cli/integration/instruction_integrator.py b/src/apm_cli/integration/instruction_integrator.py
index 56b685a4..3fad00ce 100644
--- a/src/apm_cli/integration/instruction_integrator.py
+++ b/src/apm_cli/integration/instruction_integrator.py
@@ -72,8 +72,9 @@ def integrate_instructions_for_target(
         if not mapping:
             return IntegrationResult(0, 0, 0, [])
 
-        target_root = project_root / target.root_dir
-        if not target.auto_create and not target_root.is_dir():
+        effective_root = mapping.deploy_root or target.root_dir
+        target_root = project_root / effective_root
+        if not target.auto_create and not (project_root / target.root_dir).is_dir():
             return IntegrationResult(0, 0, 0, [])
 
         self.init_link_resolver(package_info, project_root)
@@ -138,8 +139,9 @@ def sync_for_target(
         mapping = target.primitives.get("instructions")
         if not mapping:
             return {"files_removed": 0, "errors": 0}
-        prefix = f"{target.root_dir}/{mapping.subdir}/"
-        legacy_dir = project_root / target.root_dir / mapping.subdir
+        effective_root = mapping.deploy_root or target.root_dir
+        prefix = f"{effective_root}/{mapping.subdir}/"
+        legacy_dir = project_root / effective_root / mapping.subdir
         legacy_pattern = (
             "*.mdc" if mapping.format_id == "cursor_rules"
             else "*.instructions.md"
diff --git a/src/apm_cli/integration/prompt_integrator.py b/src/apm_cli/integration/prompt_integrator.py
index 97bd43b2..7b7acad8 100644
--- a/src/apm_cli/integration/prompt_integrator.py
+++ b/src/apm_cli/integration/prompt_integrator.py
@@ -90,8 +90,7 @@ def integrate_prompts_for_target(
         if not mapping:
             return IntegrationResult(0, 0, 0, [])
 
-        target_root = project_root / target.root_dir
-        if not target.auto_create and not target_root.is_dir():
+        if not target.auto_create and not (project_root / target.root_dir).is_dir():
             return IntegrationResult(0, 0, 0, [])
 
         return self.integrate_package_prompts(
@@ -111,8 +110,9 @@ def sync_for_target(
         mapping = target.primitives.get("prompts")
         if not mapping:
             return {"files_removed": 0, "errors": 0}
-        prefix = f"{target.root_dir}/{mapping.subdir}/"
-        legacy_dir = project_root / target.root_dir / mapping.subdir
+        effective_root = mapping.deploy_root or target.root_dir
+        prefix = f"{effective_root}/{mapping.subdir}/"
+        legacy_dir = project_root / effective_root / mapping.subdir
         return self.sync_remove_files(
             project_root,
             managed_files,
diff --git a/src/apm_cli/integration/skill_integrator.py b/src/apm_cli/integration/skill_integrator.py
index ddd8bb3c..802a7e0a 100644
--- a/src/apm_cli/integration/skill_integrator.py
+++ b/src/apm_cli/integration/skill_integrator.py
@@ -307,7 +307,9 @@ def copy_skill_to_target(
     for target in targets:
         if not target.supports("skills"):
             continue
-        skill_dir = target_base / target.root_dir / "skills" / skill_name
+        skills_mapping = target.primitives["skills"]
+        effective_root = skills_mapping.deploy_root or target.root_dir
+        skill_dir = target_base / effective_root / "skills" / skill_name
         skill_dir.parent.mkdir(parents=True, exist_ok=True)
         if skill_dir.exists():
             shutil.rmtree(skill_dir)
@@ -608,7 +610,9 @@ def _promote_sub_skills_standalone(
                 continue
 
             is_primary = (idx == 0)  # first active target owns diagnostics
-            target_skills_root = project_root / target.root_dir / "skills"
+            skills_mapping = target.primitives["skills"]
+            effective_root = skills_mapping.deploy_root or target.root_dir
+            target_skills_root = project_root / effective_root / "skills"
             target_skills_root.mkdir(parents=True, exist_ok=True)
 
             n, deployed = self._promote_sub_skills(
@@ -709,7 +713,9 @@ def _integrate_native_skill(
                 continue
 
             is_primary = (idx == 0)  # first active target owns diagnostics
-            target_skill_dir = project_root / target.root_dir / "skills" / skill_name
+            skills_mapping = target.primitives["skills"]
+            effective_root = skills_mapping.deploy_root or target.root_dir
+            target_skill_dir = project_root / effective_root / "skills" / skill_name
 
             if is_primary:
                 skill_created = not target_skill_dir.exists()
@@ -728,7 +734,7 @@ def _integrate_native_skill(
                 files_copied = sum(1 for _ in target_skill_dir.rglob('*') if _.is_file())
 
             # Promote sub-skills for this target
-            target_skills_root = project_root / target.root_dir / "skills"
+            target_skills_root = project_root / effective_root / "skills"
             _, sub_deployed = self._promote_sub_skills(
                 sub_skills_dir, target_skills_root, skill_name,
                 warn=is_primary,
@@ -865,6 +871,7 @@ def sync_integration(self, apm_package, project_root: Path,
                     or rel_path.startswith(".claude/skills/")
                     or rel_path.startswith(".cursor/skills/")
                     or rel_path.startswith(".opencode/skills/")
+                    or rel_path.startswith(".agents/skills/")
                 )
                 if not is_skill or ".." in rel_path:
                     continue
@@ -928,6 +935,13 @@ def sync_integration(self, apm_package, project_root: Path,
             stats['files_removed'] += result['files_removed']
             stats['errors'] += result['errors']
         
+        # Clean .agents/skills/ (cross-tool agent skills standard, used by Codex)
+        agents_skills_dir = project_root / ".agents" / "skills"
+        if agents_skills_dir.exists():
+            result = self._clean_orphaned_skills(agents_skills_dir, installed_skill_names)
+            stats['files_removed'] += result['files_removed']
+            stats['errors'] += result['errors']
+        
         return stats
     
     def _clean_orphaned_skills(self, skills_dir: Path, installed_skill_names: set) -> Dict[str, int]:
diff --git a/src/apm_cli/integration/targets.py b/src/apm_cli/integration/targets.py
index 9ee18e1b..a6ff9ae5 100644
--- a/src/apm_cli/integration/targets.py
+++ b/src/apm_cli/integration/targets.py
@@ -26,6 +26,16 @@ class PrimitiveMapping:
     """Opaque tag used by integrators to select the right
     content transformer (e.g. ``"cursor_rules"``)."""
 
+    deploy_root: Optional[str] = None
+    """Override *root_dir* for this primitive only.
+
+    When set, integrators use ``deploy_root`` instead of
+    ``target.root_dir`` to compute the deploy directory.
+    For example, Codex skills deploy to ``.agents/`` (cross-tool
+    directory) rather than ``.codex/``.  Default ``None`` preserves
+    existing behavior for all other targets.
+    """
+
 
 @dataclass(frozen=True)
 class TargetProfile:
@@ -149,6 +159,27 @@ def supports(self, primitive: str) -> bool:
         auto_create=False,
         detect_by_dir=True,
     ),
+    # Codex CLI: skills use the cross-tool .agents/ dir (agent skills standard),
+    # agents are TOML under .codex/agents/, hooks merge into .codex/hooks.json.
+    # Instructions are compile-only (AGENTS.md) — not installed.
+    "codex": TargetProfile(
+        name="codex",
+        root_dir=".codex",
+        primitives={
+            "agents": PrimitiveMapping(
+                "agents", ".toml", "codex_agent"
+            ),
+            "skills": PrimitiveMapping(
+                "skills", "/SKILL.md", "skill_standard",
+                deploy_root=".agents",
+            ),
+            "hooks": PrimitiveMapping(
+                "", "hooks.json", "codex_hooks"
+            ),
+        },
+        auto_create=False,
+        detect_by_dir=True,
+    ),
 }
 
 
@@ -157,8 +188,23 @@ def get_integration_prefixes() -> tuple:
 
     Used by ``BaseIntegrator.validate_deploy_path`` so the allow-list
     stays in sync with registered targets.
+
+    Includes prefixes from ``deploy_root`` overrides (e.g. ``.agents/``
+    for Codex skills) so cross-root paths pass security validation.
     """
-    return tuple(t.prefix for t in KNOWN_TARGETS.values())
+    prefixes: list[str] = []
+    seen: set[str] = set()
+    for t in KNOWN_TARGETS.values():
+        if t.prefix not in seen:
+            seen.add(t.prefix)
+            prefixes.append(t.prefix)
+        for m in t.primitives.values():
+            if m.deploy_root is not None:
+                dp = f"{m.deploy_root}/"
+                if dp not in seen:
+                    seen.add(dp)
+                    prefixes.append(dp)
+    return tuple(prefixes)
 
 
 def active_targets(project_root, explicit_target: "Optional[str]" = None) -> list:

From a867b034740b8a614779c851cbdebb8d4369c9e7 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 31 Mar 2026 05:15:19 +0000
Subject: [PATCH 4/9] Add Codex-specific tests for agent, hook, skill, target,
 and dispatch integrations

- Update test_partition_parity_with_old_buckets to include agents_codex key
- Add codex target gating regression test
- Add codex partition routing and prefix security tests
- Add Codex agent TOML transformation tests (frontmatter, no-frontmatter, filename)
- Add Codex hook integration tests (merge, preserve user hooks, missing dir)
- Add Codex skill deploy_root tests (.agents/skills/ vs .github/skills/)
- Add active_targets tests for codex detection and all-five-dirs scenario

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: danielmeppiel <51440732+danielmeppiel@users.noreply.github.com>
---
 .../unit/integration/test_agent_integrator.py | 59 ++++++++++++
 .../integration/test_data_driven_dispatch.py  | 63 +++++++++++++
 .../unit/integration/test_hook_integrator.py  | 89 +++++++++++++++++++
 .../unit/integration/test_skill_integrator.py | 58 ++++++++++++
 tests/unit/integration/test_targets.py        | 25 ++++++
 5 files changed, 294 insertions(+)

diff --git a/tests/unit/integration/test_agent_integrator.py b/tests/unit/integration/test_agent_integrator.py
index 635446a5..308d78b5 100644
--- a/tests/unit/integration/test_agent_integrator.py
+++ b/tests/unit/integration/test_agent_integrator.py
@@ -1093,3 +1093,62 @@ def test_sync_integration_opencode_handles_missing_dir(self):
 
         assert result['files_removed'] == 0
         assert result['errors'] == 0
+
+
+class TestCodexAgentIntegration:
+    """Tests for Codex TOML agent transformation."""
+
+    def setup_method(self):
+        self.temp_dir = tempfile.mkdtemp()
+        self.root = Path(self.temp_dir)
+        (self.root / ".codex").mkdir()
+
+    def teardown_method(self):
+        import shutil
+        shutil.rmtree(self.temp_dir, ignore_errors=True)
+
+    def test_agent_md_to_toml_with_frontmatter(self):
+        """Agent .md with YAML frontmatter is converted to .toml."""
+        import toml
+
+        source = self.root / "test.agent.md"
+        source.write_text(
+            "---\nname: my-agent\ndescription: A test agent\n---\nDo something useful.\n",
+            encoding="utf-8",
+        )
+        target = self.root / ".codex" / "agents" / "test.toml"
+        target.parent.mkdir(parents=True, exist_ok=True)
+
+        AgentIntegrator._write_codex_agent(source, target)
+
+        assert target.exists()
+        data = toml.loads(target.read_text(encoding="utf-8"))
+        assert data["name"] == "my-agent"
+        assert data["description"] == "A test agent"
+        assert data["developer_instructions"] == "Do something useful."
+
+    def test_agent_md_to_toml_without_frontmatter(self):
+        """Agent .md without frontmatter uses filename as name."""
+        import toml
+
+        source = self.root / "helper.agent.md"
+        source.write_text("Instructions for the helper agent.\n", encoding="utf-8")
+        target = self.root / ".codex" / "agents" / "helper.toml"
+        target.parent.mkdir(parents=True, exist_ok=True)
+
+        AgentIntegrator._write_codex_agent(source, target)
+
+        data = toml.loads(target.read_text(encoding="utf-8"))
+        assert data["name"] == "helper"
+        assert data["description"] == ""
+        assert "Instructions for the helper agent." in data["developer_instructions"]
+
+    def test_codex_agent_target_filename_is_toml(self):
+        """AgentIntegrator generates .toml filenames for Codex target."""
+        from apm_cli.integration.targets import KNOWN_TARGETS
+
+        integrator = AgentIntegrator()
+        codex = KNOWN_TARGETS["codex"]
+        source = Path("/fake/test.agent.md")
+        filename = integrator.get_target_filename_for_target(source, "pkg", codex)
+        assert filename == "test.toml"
diff --git a/tests/unit/integration/test_data_driven_dispatch.py b/tests/unit/integration/test_data_driven_dispatch.py
index 378ec9fa..85f68b98 100644
--- a/tests/unit/integration/test_data_driven_dispatch.py
+++ b/tests/unit/integration/test_data_driven_dispatch.py
@@ -164,6 +164,25 @@ def test_copilot_only_does_not_write_cursor_or_opencode(self):
         assert ".cursor" not in dispatched_roots
         assert ".opencode" not in dispatched_roots
 
+    def test_codex_only_does_not_write_github_or_claude_dirs(self):
+        """With targets=[codex], no .github/ or .claude/ primitive is dispatched."""
+        targets = [KNOWN_TARGETS["codex"]]
+        _result, mocks = _dispatch(targets)
+        dispatched_roots = set()
+        for name in ("prompt_integrator", "agent_integrator",
+                      "command_integrator", "instruction_integrator",
+                      "hook_integrator"):
+            for attr_name in dir(mocks[name]):
+                method = getattr(mocks[name], attr_name)
+                if hasattr(method, "call_args_list"):
+                    for call_args in method.call_args_list:
+                        if call_args[0] and hasattr(call_args[0][0], "root_dir"):
+                            dispatched_roots.add(call_args[0][0].root_dir)
+        assert ".github" not in dispatched_roots
+        assert ".claude" not in dispatched_roots
+        assert ".cursor" not in dispatched_roots
+        assert ".opencode" not in dispatched_roots
+
     def test_empty_targets_returns_zeros(self):
         """With targets=[], all counters are 0 and no integrators are called."""
         result, mocks = _dispatch(targets=[])
@@ -261,6 +280,7 @@ def test_partition_parity_with_old_buckets(self):
             "agents_claude",
             "agents_cursor",
             "agents_opencode",
+            "agents_codex",
             "commands",            # was commands_claude, aliased
             "commands_opencode",
             "instructions",        # was instructions_copilot, aliased
@@ -457,3 +477,46 @@ def test_cursor_instructions_alias(self):
 
     def test_unaliased_key_passthrough(self):
         assert BaseIntegrator.partition_bucket_key("agents", "cursor") == "agents_cursor"
+
+
+# ===================================================================
+# 6. TestCodexPartitionRouting
+# ===================================================================
+
+class TestCodexPartitionRouting:
+    """Verify that Codex deployed_files are routed to correct buckets."""
+
+    def test_partition_routes_codex_paths_correctly(self):
+        """Codex deployed_files are routed to correct buckets."""
+        managed = {
+            ".codex/agents/my-agent.toml",
+            ".agents/skills/my-skill/SKILL.md",
+            ".codex/hooks/pkg/script.sh",
+        }
+        buckets = BaseIntegrator.partition_managed_files(managed)
+        assert ".agents/skills/my-skill/SKILL.md" in buckets["skills"]
+        # Codex hooks mapping has empty subdir, so .codex/ is a
+        # catch-all hook prefix -- both agents and hooks route there.
+        assert ".codex/agents/my-agent.toml" in buckets["hooks"]
+        assert ".codex/hooks/pkg/script.sh" in buckets["hooks"]
+
+
+# ===================================================================
+# 7. TestIntegrationPrefixSecurity
+# ===================================================================
+
+class TestIntegrationPrefixSecurity:
+    """Verify integration prefixes include deploy_root paths."""
+
+    def test_integration_prefixes_include_agents_dir(self):
+        """get_integration_prefixes() includes .agents/ from deploy_root."""
+        from apm_cli.integration.targets import get_integration_prefixes
+        prefixes = get_integration_prefixes()
+        assert ".agents/" in prefixes
+        assert ".codex/" in prefixes
+
+    def test_deploy_root_validation(self):
+        """validate_deploy_path accepts .agents/skills/ paths."""
+        root = Path("/fake/project")
+        assert BaseIntegrator.validate_deploy_path(".agents/skills/my-skill/SKILL.md", root)
+        assert BaseIntegrator.validate_deploy_path(".codex/agents/my-agent.toml", root)
diff --git a/tests/unit/integration/test_hook_integrator.py b/tests/unit/integration/test_hook_integrator.py
index 45d110de..5ec3f08d 100644
--- a/tests/unit/integration/test_hook_integrator.py
+++ b/tests/unit/integration/test_hook_integrator.py
@@ -1447,3 +1447,92 @@ def test_rewrite_does_not_mutate_original(self, temp_project):
         assert data["hooks"]["Stop"][0]["hooks"][0]["command"] == original_cmd
         # Rewritten should be different
         assert rewritten["hooks"]["Stop"][0]["hooks"][0]["command"] != original_cmd
+
+
+# ─── Codex hook integration tests ────────────────────────────────────────────
+
+
+class TestCodexHookIntegration:
+    """Tests for Codex hooks.json merge with _apm_source markers."""
+
+    def setup_method(self):
+        self.temp_dir = tempfile.mkdtemp()
+        self.root = Path(self.temp_dir)
+        (self.root / ".codex").mkdir()
+
+    def teardown_method(self):
+        shutil.rmtree(self.temp_dir, ignore_errors=True)
+
+    def _make_package_info(self, name="test-pkg", hook_data=None):
+        """Create a mock package info with hook files."""
+        pkg_dir = self.root / "apm_modules" / name
+        hooks_dir = pkg_dir / ".apm" / "hooks"
+        hooks_dir.mkdir(parents=True, exist_ok=True)
+
+        if hook_data is None:
+            hook_data = {
+                "hooks": {
+                    "SessionStart": [
+                        {"type": "command", "command": "echo hello"}
+                    ]
+                }
+            }
+
+        hook_file = hooks_dir / "hooks.json"
+        with open(hook_file, 'w') as f:
+            json.dump(hook_data, f)
+
+        pi = MagicMock()
+        pi.install_path = pkg_dir
+        pi.package = MagicMock()
+        pi.package.name = name
+        return pi
+
+    def test_codex_hooks_merge_into_hooks_json(self):
+        """Hooks are merged into .codex/hooks.json with _apm_source markers."""
+        pi = self._make_package_info()
+        integrator = HookIntegrator()
+        result = integrator.integrate_package_hooks_codex(pi, self.root)
+
+        assert result.hooks_integrated == 1
+        hooks_json = self.root / ".codex" / "hooks.json"
+        assert hooks_json.exists()
+        data = json.loads(hooks_json.read_text())
+        assert "SessionStart" in data["hooks"]
+        entries = data["hooks"]["SessionStart"]
+        assert any(e.get("_apm_source") == "test-pkg" for e in entries)
+
+    def test_codex_hooks_preserve_user_hooks(self):
+        """Existing user hooks in .codex/hooks.json are preserved."""
+        # Write existing user hooks
+        hooks_json = self.root / ".codex" / "hooks.json"
+        hooks_json.write_text(json.dumps({
+            "hooks": {
+                "PreToolUse": [
+                    {"type": "command", "command": "echo user-hook"}
+                ]
+            }
+        }))
+
+        pi = self._make_package_info()
+        integrator = HookIntegrator()
+        result = integrator.integrate_package_hooks_codex(pi, self.root)
+
+        data = json.loads(hooks_json.read_text())
+        # User hook preserved
+        assert "PreToolUse" in data["hooks"]
+        user_entries = [e for e in data["hooks"]["PreToolUse"] if "_apm_source" not in e]
+        assert len(user_entries) == 1
+        assert user_entries[0]["command"] == "echo user-hook"
+        # APM hook added
+        assert "SessionStart" in data["hooks"]
+
+    def test_codex_hooks_not_deployed_without_codex_dir(self):
+        """Hooks are not deployed if .codex/ directory doesn't exist."""
+        shutil.rmtree(self.root / ".codex")
+
+        pi = self._make_package_info()
+        integrator = HookIntegrator()
+        result = integrator.integrate_package_hooks_codex(pi, self.root)
+
+        assert result.hooks_integrated == 0
diff --git a/tests/unit/integration/test_skill_integrator.py b/tests/unit/integration/test_skill_integrator.py
index 0c13fb80..fbf62d60 100644
--- a/tests/unit/integration/test_skill_integrator.py
+++ b/tests/unit/integration/test_skill_integrator.py
@@ -3035,3 +3035,61 @@ def test_skill_update_reflected_in_cursor(self):
         ).read_text()
         assert "# Version 2" in cursor_content
         assert "# Version 1" not in cursor_content
+
+
+class TestCodexSkillDeployRoot:
+    """Tests for Codex skill deployment to .agents/skills/ via deploy_root."""
+
+    def setup_method(self):
+        self.temp_dir = tempfile.mkdtemp()
+        self.root = Path(self.temp_dir)
+        (self.root / ".codex").mkdir()
+
+    def teardown_method(self):
+        shutil.rmtree(self.temp_dir, ignore_errors=True)
+
+    def test_codex_skills_deploy_to_agents_dir(self):
+        """Codex skills deploy to .agents/skills/ not .codex/skills/."""
+        from apm_cli.integration.targets import KNOWN_TARGETS
+
+        # Create a minimal skill package
+        skill_dir = self.root / "apm_modules" / "my-skill"
+        skill_dir.mkdir(parents=True)
+        (skill_dir / "SKILL.md").write_text("---\nname: my-skill\n---\nSkill content.\n")
+
+        pi = Mock()
+        pi.install_path = skill_dir
+        pi.package = Mock()
+        pi.package.name = "my-skill"
+        pi.package_type = PackageType.CLAUDE_SKILL
+
+        targets = [KNOWN_TARGETS["codex"]]
+        deployed = copy_skill_to_target(pi, skill_dir, self.root, targets=targets)
+
+        assert len(deployed) == 1
+        # Skill deployed to .agents/skills/ not .codex/skills/
+        assert ".agents" in str(deployed[0])
+        assert (self.root / ".agents" / "skills" / "my-skill" / "SKILL.md").exists()
+        assert not (self.root / ".codex" / "skills").exists()
+
+    def test_other_targets_still_deploy_to_own_root(self):
+        """Copilot skills still deploy to .github/skills/."""
+        from apm_cli.integration.targets import KNOWN_TARGETS
+
+        (self.root / ".github").mkdir()
+        skill_dir = self.root / "apm_modules" / "my-skill"
+        skill_dir.mkdir(parents=True)
+        (skill_dir / "SKILL.md").write_text("---\nname: my-skill\n---\nSkill content.\n")
+
+        pi = Mock()
+        pi.install_path = skill_dir
+        pi.package = Mock()
+        pi.package.name = "my-skill"
+        pi.package_type = PackageType.CLAUDE_SKILL
+
+        targets = [KNOWN_TARGETS["copilot"]]
+        deployed = copy_skill_to_target(pi, skill_dir, self.root, targets=targets)
+
+        assert len(deployed) == 1
+        assert ".github" in str(deployed[0])
+        assert (self.root / ".github" / "skills" / "my-skill" / "SKILL.md").exists()
diff --git a/tests/unit/integration/test_targets.py b/tests/unit/integration/test_targets.py
index 0d2845a4..3d8739e8 100644
--- a/tests/unit/integration/test_targets.py
+++ b/tests/unit/integration/test_targets.py
@@ -97,3 +97,28 @@ def test_explicit_overrides_detection(self):
     def test_explicit_unknown_returns_empty(self):
         targets = active_targets(self.root, explicit_target="nonexistent")
         assert targets == []
+
+    # -- codex detection --
+
+    def test_only_codex_returns_codex(self):
+        (self.root / ".codex").mkdir()
+        targets = active_targets(self.root)
+        assert [t.name for t in targets] == ["codex"]
+
+    def test_explicit_codex(self):
+        targets = active_targets(self.root, explicit_target="codex")
+        assert [t.name for t in targets] == ["codex"]
+
+    def test_codex_not_detected_when_only_agents_dir_exists(self):
+        """Only .agents/ existing (no .codex/) should NOT detect Codex."""
+        (self.root / ".agents").mkdir()
+        targets = active_targets(self.root)
+        # .agents/ alone doesn't match any target root_dir
+        assert len(targets) == 1
+        assert targets[0].name == "copilot"  # fallback
+
+    def test_all_five_dirs_returns_all_five(self):
+        for d in (".github", ".claude", ".cursor", ".opencode", ".codex"):
+            (self.root / d).mkdir()
+        targets = active_targets(self.root)
+        assert len(targets) == 5

From 4085b0ffacc1773985b3d08ef084fcdc7fa11581 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 31 Mar 2026 05:17:00 +0000
Subject: [PATCH 5/9] Fix ASCII encoding violation in test comment

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: danielmeppiel <51440732+danielmeppiel@users.noreply.github.com>
---
 tests/unit/integration/test_hook_integrator.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/unit/integration/test_hook_integrator.py b/tests/unit/integration/test_hook_integrator.py
index 5ec3f08d..dba96196 100644
--- a/tests/unit/integration/test_hook_integrator.py
+++ b/tests/unit/integration/test_hook_integrator.py
@@ -1449,7 +1449,7 @@ def test_rewrite_does_not_mutate_original(self, temp_project):
         assert rewritten["hooks"]["Stop"][0]["hooks"][0]["command"] != original_cmd
 
 
-# ─── Codex hook integration tests ────────────────────────────────────────────
+# --- Codex hook integration tests ---------------------------------------------
 
 
 class TestCodexHookIntegration:

From 195327897b83fc18f43dd9636b5ddfa3ddf49786 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 31 Mar 2026 05:25:28 +0000
Subject: [PATCH 6/9] docs: add Codex CLI as first-class integration target

Add documentation for the new 'codex' target across all relevant pages:

- ide-tool-integration.md: Add Codex CLI section with primitives table,
  update hook integration list, update compile references
- cli-commands.md: Add 'codex' to --target for install, compile, pack;
  add codex row to auto-detection and target format tables
- compilation.md: Add codex to auto-detection, output files, and tool
  compatibility tables; update intro and compile examples
- manifest-schema.md: Add 'codex' to allowed target values in both
  top-level and compilation.target fields
- skills.md: Document .agents/skills/ deploy path for Codex
- CHANGELOG.md: Add Unreleased entries for Codex CLI support

Co-authored-by: danielmeppiel <51440732+danielmeppiel@users.noreply.github.com>
---
 CHANGELOG.md                                  |  6 +++++
 docs/src/content/docs/guides/compilation.md   | 17 +++++++-----
 docs/src/content/docs/guides/skills.md        |  5 ++--
 .../docs/integrations/ide-tool-integration.md | 26 ++++++++++++++-----
 .../content/docs/reference/cli-commands.md    | 12 +++++----
 .../content/docs/reference/manifest-schema.md |  9 ++++---
 6 files changed, 51 insertions(+), 24 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 27711e79..80c6e586 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Support Codex CLI as integration target with skills (`.agents/skills/`), agents (`.codex/agents/*.toml`), and hooks (`.codex/hooks.json`)
+- Add `deploy_root` field to `PrimitiveMapping` for cross-root primitive deployment
+- Add `--target codex` to install, compile, and pack commands
+
 ## [0.8.7] - 2026-03-30
 
 ### Fixed
diff --git a/docs/src/content/docs/guides/compilation.md b/docs/src/content/docs/guides/compilation.md
index ec0b9e55..23de213b 100644
--- a/docs/src/content/docs/guides/compilation.md
+++ b/docs/src/content/docs/guides/compilation.md
@@ -4,7 +4,7 @@ sidebar:
   order: 1
 ---
 
-Compilation is **optional for most users**. If your team uses GitHub Copilot, Claude, or Cursor, `apm install` deploys all primitives in their native format -- you can skip this guide entirely. For OpenCode, `apm install` deploys agents, commands, skills, and MCP, but instructions require `apm compile` to generate the `AGENTS.md` that OpenCode reads. `apm compile` is also needed for Codex, Gemini, or other tools that read single-root-file formats.
+Compilation is **optional for most users**. If your team uses GitHub Copilot, Claude, or Cursor, `apm install` deploys all primitives in their native format -- you can skip this guide entirely. For OpenCode, `apm install` deploys agents, commands, skills, and MCP, but instructions require `apm compile` to generate the `AGENTS.md` that OpenCode reads. For Codex, `apm install` deploys skills, agents, and hooks natively, but instructions require `apm compile`. `apm compile` is also needed for Gemini or other tools that read single-root-file formats.
 
 **Solving the AI agent scalability problem through constraint satisfaction optimization**
 
@@ -22,12 +22,14 @@ When you run `apm compile` without specifying a target, APM automatically detect
 |-------------------|--------|---------------------|
 | `.github/` folder only | `copilot` | AGENTS.md (instructions only) |
 | `.claude/` folder only | `claude` | CLAUDE.md (instructions only) |
+| `.codex/` folder exists | `codex` | AGENTS.md (instructions only) |
 | Both folders exist | `all` | Both AGENTS.md and CLAUDE.md |
 | Neither folder exists | `minimal` | AGENTS.md only (universal format) |
 
 ```bash
 apm compile                    # Auto-detects target from project structure
-apm compile --target copilot   # Force GitHub Copilot, Cursor, Codex, Gemini
+apm compile --target copilot   # Force GitHub Copilot, Cursor, Gemini
+apm compile --target codex     # Force Codex CLI
 apm compile --target claude    # Force Claude Code, Claude Desktop
 ```
 
@@ -35,21 +37,22 @@ You can set a persistent target in `apm.yml`:
 ```yaml
 name: my-project
 version: 1.0.0
-target: copilot  # or vscode, claude, or all
+target: copilot  # or vscode, claude, codex, or all
 ```
 
 ### Output Files
 
 | Target | Files Generated | Consumers |
 |--------|-----------------|-----------|
-| `copilot` | `AGENTS.md` | GitHub Copilot, Cursor, OpenCode, Codex, Gemini |
+| `copilot` | `AGENTS.md` | GitHub Copilot, Cursor, OpenCode, Gemini |
+| `codex` | `AGENTS.md` | Codex CLI |
 | `claude` | `CLAUDE.md` | Claude Code, Claude Desktop |
 | `all` | Both `AGENTS.md` and `CLAUDE.md` | Universal compatibility |
 | `minimal` | `AGENTS.md` only | Works everywhere, no folder integration |
 
 > **Aliases**: `vscode` and `agents` are accepted as aliases for `copilot`.
 
-> **Note**: `AGENTS.md` and `CLAUDE.md` contain **only instructions** (grouped by `applyTo` patterns). Prompts, agents, commands, hooks, and skills are integrated by `apm install`, not `apm compile`. See the [Integrations Guide](../../integrations/ide-tool-integration/) for details on how `apm install` populates `.github/prompts/`, `.github/agents/`, `.github/skills/`, `.claude/commands/`, `.cursor/rules/`, `.cursor/agents/`, `.opencode/agents/`, and `.opencode/commands/`.
+> **Note**: `AGENTS.md` and `CLAUDE.md` contain **only instructions** (grouped by `applyTo` patterns). Prompts, agents, commands, hooks, and skills are integrated by `apm install`, not `apm compile`. See the [Integrations Guide](../../integrations/ide-tool-integration/) for details on how `apm install` populates `.github/prompts/`, `.github/agents/`, `.github/skills/`, `.claude/commands/`, `.cursor/rules/`, `.cursor/agents/`, `.opencode/agents/`, `.opencode/commands/`, `.codex/agents/`, and `.agents/skills/`.
 
 ### How It Works
 
@@ -436,10 +439,10 @@ Different AI tools get different levels of support from `apm install` vs `apm co
 | Claude | `.claude/` commands, skills, MCP | `CLAUDE.md` | **Full** |
 | Cursor | `.cursor/rules/`, `.cursor/agents/`, `.cursor/skills/`, `.cursor/hooks.json`, `.cursor/mcp.json` | `AGENTS.md` (optional) | **Full** |
 | OpenCode | `.opencode/agents/`, `.opencode/commands/`, `.opencode/skills/`, `opencode.json` (MCP) | Via `AGENTS.md` | **Full** |
-| Codex CLI | -- | `AGENTS.md` | Instructions via compile |
+| Codex CLI | `.agents/skills/`, `.codex/agents/`, `.codex/hooks.json` | `AGENTS.md` (instructions) | **Full** |
 | Gemini | -- | `GEMINI.md` | Instructions via compile |
 
-For Copilot, Claude, and Cursor users, `apm install` handles everything natively. OpenCode users should also run `apm compile` to generate `AGENTS.md` for instructions. Compilation is the bridge that brings instruction support to tools that do not yet have first-class APM integration.
+For Copilot, Claude, and Cursor users, `apm install` handles everything natively. OpenCode and Codex users should also run `apm compile` to generate `AGENTS.md` for instructions. Compilation is the bridge that brings instruction support to tools that do not yet have first-class APM integration.
 
 ## Theoretical Foundations
 
diff --git a/docs/src/content/docs/guides/skills.md b/docs/src/content/docs/guides/skills.md
index d4d6bff6..9cdb59ec 100644
--- a/docs/src/content/docs/guides/skills.md
+++ b/docs/src/content/docs/guides/skills.md
@@ -51,7 +51,8 @@ APM copies skills to every detected target directory:
 | **No SKILL.md and no primitives** | No skill folder created |
 
 **Target Detection:**
-- Recognized directories: `.github/`, `.claude/`, `.cursor/`, `.opencode/`
+- Recognized directories: `.github/`, `.claude/`, `.cursor/`, `.opencode/`, `.codex/`
+- Codex skills deploy to `.agents/skills/` (agent skills standard directory), not `.codex/skills/`
 - If none exist, `.github/` is created as the fallback
 - Override with `--target`
 
@@ -286,7 +287,7 @@ APM automatically detects package types:
 
 ## Target Detection
 
-APM deploys skills to every target directory that already exists: `.github/`, `.claude/`, `.cursor/`, `.opencode/`. If none exist, `.github/` is created as the fallback.
+APM deploys skills to every target directory that already exists: `.github/`, `.claude/`, `.cursor/`, `.opencode/`. For Codex (`.codex/`), skills deploy to `.agents/skills/` instead. If no target directories exist, `.github/` is created as the fallback.
 
 Override with:
 ```bash
diff --git a/docs/src/content/docs/integrations/ide-tool-integration.md b/docs/src/content/docs/integrations/ide-tool-integration.md
index 10b15691..c2f69333 100644
--- a/docs/src/content/docs/integrations/ide-tool-integration.md
+++ b/docs/src/content/docs/integrations/ide-tool-integration.md
@@ -34,7 +34,7 @@ When using Spec-kit for Specification-Driven Development (SDD), APM automaticall
 # 1. Set up APM contextual foundation
 apm init my-project && apm install
 
-# 2. Optional: compile for tools without native integration (Codex, Gemini)
+# 2. Optional: compile for Codex/OpenCode instructions, Gemini, etc.
 # Spec-kit constitution is automatically included in compiled AGENTS.md
 apm compile
 
@@ -148,7 +148,7 @@ apm install microsoft/apm-sample-package
 
 ### Optional: Compiled Context with AGENTS.md
 
-For tools that do not support granular primitive discovery (such as Codex or Gemini), `apm compile` produces an `AGENTS.md` file that merges instructions into a single document. This is not needed for GitHub Copilot, Claude, or Cursor, which read per-file instructions natively. OpenCode also reads `AGENTS.md`, so run `apm compile` to deploy instructions there.
+For tools that do not support granular primitive discovery (such as Gemini), `apm compile` produces an `AGENTS.md` file that merges instructions into a single document. This is not needed for GitHub Copilot, Claude, or Cursor, which read per-file instructions natively. OpenCode and Codex also read `AGENTS.md`, so run `apm compile` to deploy instructions there.
 
 ```bash
 # Compile all local and dependency instructions into AGENTS.md
@@ -211,6 +211,19 @@ APM natively integrates with OpenCode when a `.opencode/` directory exists in yo
 | `.cursor/hooks/{pkg}/` | Referenced hook scripts |
 | `.cursor/mcp.json` | MCP server configurations |
 
+#### Codex CLI (`.codex/`)
+
+| APM Primitive | Codex Destination | Format |
+|---|---|---|
+| Skills (`SKILL.md`) | `.agents/skills/{name}/SKILL.md` | Identical (agentskills.io standard) |
+| Agents (`.agent.md`) | `.codex/agents/*.toml` | Converted from Markdown to TOML |
+| Hooks (`.json`) | `.codex/hooks.json` + `.codex/hooks/{pkg}/` | Merged JSON config with `_apm_source` markers |
+| Instructions | Via `AGENTS.md` | Compile-only (`apm compile --target codex`) |
+
+**Setup**: Create a `.codex/` directory in your project root, then run `apm install`. APM detects the directory and deploys automatically.
+
+> **Note**: Skills deploy to `.agents/skills/` (the cross-tool agent skills standard directory), not `.codex/skills/`. Agents are transformed from `.agent.md` Markdown to `.toml` format.
+
 ### Automatic Agent Integration
 
 APM automatically deploys agent files from installed packages into `.claude/agents/`:
@@ -296,13 +309,14 @@ apm install anthropics/claude-plugins-official/plugins/hookify
 2. For VS Code: copies hook JSON to `.github/hooks/` and rewrites script paths
 3. For Claude: merges hook definitions into `.claude/settings.json` under the `hooks` key
 4. For Cursor: merges hook definitions into `.cursor/hooks.json` under the `hooks` key (only when `.cursor/` exists)
-5. Copies referenced scripts to the target location
-6. Rewrites `${CLAUDE_PLUGIN_ROOT}` and relative script paths for the target platform
-7. `apm uninstall` removes hook files and cleans up merged settings
+5. For Codex: merges hook definitions into `.codex/hooks.json` under the `hooks` key (only when `.codex/` exists)
+6. Copies referenced scripts to the target location
+7. Rewrites `${CLAUDE_PLUGIN_ROOT}` and relative script paths for the target platform
+8. `apm uninstall` removes hook files and cleans up merged settings
 
 ### Optional: Target-Specific Compilation
 
-Compilation is optional for Copilot, Claude, and Cursor, which read per-file instructions natively. For OpenCode, run `apm compile` to generate `AGENTS.md` (OpenCode's instruction source). Also use it when targeting Codex or Gemini:
+Compilation is optional for Copilot, Claude, and Cursor, which read per-file instructions natively. For OpenCode and Codex, run `apm compile` to generate `AGENTS.md` for instructions. Also use it when targeting Gemini:
 
 ```bash
 # Generate all formats (default)
diff --git a/docs/src/content/docs/reference/cli-commands.md b/docs/src/content/docs/reference/cli-commands.md
index c84f0809..a8842ac2 100644
--- a/docs/src/content/docs/reference/cli-commands.md
+++ b/docs/src/content/docs/reference/cli-commands.md
@@ -87,7 +87,7 @@ apm install [PACKAGES...] [OPTIONS]
 - `--runtime TEXT` - Target specific runtime only (copilot, codex, vscode)
 - `--exclude TEXT` - Exclude specific runtime from installation
 - `--only [apm|mcp]` - Install only specific dependency type
-- `--target [copilot|claude|cursor|opencode|all]` - Force deployment to a specific target (overrides auto-detection)
+- `--target [copilot|claude|cursor|codex|opencode|all]` - Force deployment to a specific target (overrides auto-detection)
 - `--update` - Update dependencies to latest Git references  
 - `--force` - Overwrite locally-authored files on collision; bypass security scan blocks
 - `--dry-run` - Show what would be installed without installing
@@ -440,7 +440,7 @@ apm pack [OPTIONS]
 
 **Options:**
 - `-o, --output PATH` - Output directory (default: `./build`)
-- `-t, --target [copilot|vscode|claude|cursor|opencode|all]` - Filter files by target. Auto-detects from `apm.yml` if not specified. `vscode` is an alias for `copilot`
+- `-t, --target [copilot|vscode|claude|cursor|codex|opencode|all]` - Filter files by target. Auto-detects from `apm.yml` if not specified. `vscode` is an alias for `copilot`
 - `--archive` - Produce a `.tar.gz` archive instead of a directory
 - `--dry-run` - List files that would be packed without writing anything
 - `--format [apm|plugin]` - Bundle format (default: `apm`). `plugin` produces a standalone plugin directory with `plugin.json`
@@ -921,7 +921,7 @@ apm compile [OPTIONS]
 
 **Options:**
 - `-o, --output TEXT` - Output file path (for single-file mode)
-- `-t, --target [vscode|agents|claude|opencode|all]` - Target agent format. `agents` is an alias for `vscode`. Auto-detects if not specified.
+- `-t, --target [vscode|agents|claude|codex|opencode|all]` - Target agent format. `agents` is an alias for `vscode`. Auto-detects if not specified.
 - `--chatmode TEXT` - Chatmode to prepend to the AGENTS.md file
 - `--dry-run` - Preview compilation without writing files (shows placement decisions)
 - `--no-links` - Skip markdown link resolution
@@ -941,6 +941,7 @@ When `--target` is not specified, APM auto-detects based on existing project str
 |-----------|--------|--------|
 | `.github/` exists only | `vscode` | AGENTS.md + .github/ |
 | `.claude/` exists only | `claude` | CLAUDE.md + .claude/ |
+| `.codex/` exists | `codex` | AGENTS.md + .codex/ + .agents/ |
 | Both folders exist | `all` | All outputs |
 | Neither folder exists | `minimal` | AGENTS.md only |
 
@@ -948,15 +949,16 @@ You can also set a persistent target in `apm.yml`:
 ```yaml
 name: my-project
 version: 1.0.0
-target: vscode  # or claude, opencode, or all
+target: vscode  # or claude, codex, opencode, or all
 ```
 
 **Target Formats (explicit):**
 
 | Target | Output Files | Best For |
 |--------|--------------|----------|
-| `vscode` | AGENTS.md, .github/prompts/, .github/agents/, .github/skills/ | GitHub Copilot, Cursor, Codex, Gemini |
+| `vscode` | AGENTS.md, .github/prompts/, .github/agents/, .github/skills/ | GitHub Copilot, Cursor, Gemini |
 | `claude` | CLAUDE.md, .claude/commands/, SKILL.md | Claude Code, Claude Desktop |
+| `codex` | AGENTS.md, .agents/skills/, .codex/agents/, .codex/hooks.json | Codex CLI |
 | `opencode` | AGENTS.md, .opencode/agents/, .opencode/commands/, .opencode/skills/ | OpenCode |
 | `all` | All of the above | Universal compatibility |
 
diff --git a/docs/src/content/docs/reference/manifest-schema.md b/docs/src/content/docs/reference/manifest-schema.md
index b8814413..64e86b8e 100644
--- a/docs/src/content/docs/reference/manifest-schema.md
+++ b/docs/src/content/docs/reference/manifest-schema.md
@@ -108,16 +108,17 @@ compilation:   <CompilationConfig>
 |---|---|
 | **Type** | `enum<string>` |
 | **Required** | OPTIONAL |
-| **Default** | Auto-detect: `vscode` if `.github/` exists, `claude` if `.claude/` exists, `all` if both, `minimal` if neither |
-| **Allowed values** | `vscode` · `agents` · `claude` · `all` |
+| **Default** | Auto-detect: `vscode` if `.github/` exists, `claude` if `.claude/` exists, `codex` if `.codex/` exists, `all` if both `.github/` and `.claude/`, `minimal` if neither |
+| **Allowed values** | `vscode` · `agents` · `claude` · `codex` · `all` |
 
-Controls which output targets are generated during compilation. When unset, a conforming resolver SHOULD auto-detect based on `.github/` and `.claude/` folder presence. Unknown values MUST be silently ignored (auto-detection takes over).
+Controls which output targets are generated during compilation. When unset, a conforming resolver SHOULD auto-detect based on `.github/`, `.claude/`, and `.codex/` folder presence. Unknown values MUST be silently ignored (auto-detection takes over).
 
 | Value | Effect |
 |---|---|
 | `vscode` | Emits `AGENTS.md` at the project root (and per-directory files in distributed mode) |
 | `agents` | Alias for `vscode` |
 | `claude` | Emits `CLAUDE.md` at the project root |
+| `codex` | Emits `AGENTS.md` and deploys skills to `.agents/skills/`, agents to `.codex/agents/` |
 | `all` | Both `vscode` and `claude` targets |
 | `minimal` | AGENTS.md only at project root. **Auto-detected only** — this value MUST NOT be set explicitly in manifests; it is an internal fallback when no `.github/` or `.claude/` folder is detected. |
 
@@ -378,7 +379,7 @@ The `compilation` key is OPTIONAL. It controls `apm compile` behaviour. All fiel
 
 | Field | Type | Default | Constraint | Description |
 |---|---|---|---|---|
-| `target` | `enum<string>` | `all` | `vscode` · `agents` · `claude` · `all` | Output target (same values as §3.6). Defaults to `all` when set explicitly in compilation config. |
+| `target` | `enum<string>` | `all` | `vscode` · `agents` · `claude` · `codex` · `all` | Output target (same values as §3.6). Defaults to `all` when set explicitly in compilation config. |
 | `strategy` | `enum<string>` | `distributed` | `distributed` · `single-file` | `distributed` generates per-directory AGENTS.md files. `single-file` generates one monolithic file. |
 | `single_file` | `bool` | `false` | | Legacy alias. When `true`, overrides `strategy` to `single-file`. |
 | `output` | `string` | `AGENTS.md` | File path | Custom output path for the compiled file. |

From 0f02d2e19d9334144906e121101fc4562f770db5 Mon Sep 17 00:00:00 2001
From: danielmeppiel <dmeppiel@microsoft.com>
Date: Tue, 31 Mar 2026 14:25:28 +0200
Subject: [PATCH 7/9] fix: address PR review comments for Codex CLI integration

- Fix partition routing: check component_map before broad hook prefix
  matching so .codex/agents/* routes to agents_codex, not hooks
- Add codex to target_detection.py: TargetType, detect_target(),
  should_integrate_codex(), should_compile_agents_md(), auto-detection
- Add codex to lockfile_enrichment _TARGET_PREFIXES and _CROSS_TARGET_MAPS
- Fix CHANGELOG entries with (#504) PR references
- Gate .agents/skills/ orphan cleanup behind .codex/ existence
- Replace Unicode em dash with ASCII -- in targets.py comment
- Add encoding='utf-8' to test_hook_integrator.py open() call

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 CHANGELOG.md                                  |  6 +--
 src/apm_cli/bundle/lockfile_enrichment.py     |  7 +++-
 src/apm_cli/core/target_detection.py          | 39 +++++++++++++++----
 src/apm_cli/integration/base_integrator.py    | 24 +++++++-----
 src/apm_cli/integration/skill_integrator.py   |  5 ++-
 src/apm_cli/integration/targets.py            |  2 +-
 .../integration/test_data_driven_dispatch.py  |  6 +--
 .../unit/integration/test_hook_integrator.py  |  2 +-
 8 files changed, 63 insertions(+), 28 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 63f746aa..be67db92 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,9 +10,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Support Codex CLI as integration target with skills (`.agents/skills/`), agents (`.codex/agents/*.toml`), and hooks (`.codex/hooks.json`)
-- Add `deploy_root` field to `PrimitiveMapping` for cross-root primitive deployment
-- Add `--target codex` to install, compile, and pack commands
+- Support Codex CLI as integration target with skills (`.agents/skills/`), agents (`.codex/agents/*.toml`), and hooks (`.codex/hooks.json`) (#504)
+- Add `deploy_root` field to `PrimitiveMapping` for cross-root primitive deployment (#504)
+- Add `--target codex` to install, compile, and pack commands (#504)
 
 ### Changed
 
diff --git a/src/apm_cli/bundle/lockfile_enrichment.py b/src/apm_cli/bundle/lockfile_enrichment.py
index 34febfe4..b4a7a6c6 100644
--- a/src/apm_cli/bundle/lockfile_enrichment.py
+++ b/src/apm_cli/bundle/lockfile_enrichment.py
@@ -13,7 +13,8 @@
     "claude": [".claude/"],
     "cursor": [".cursor/"],
     "opencode": [".opencode/"],
-    "all": [".github/", ".claude/", ".cursor/", ".opencode/"],
+    "codex": [".codex/", ".agents/"],
+    "all": [".github/", ".claude/", ".cursor/", ".opencode/", ".codex/", ".agents/"],
 }
 
 # Cross-target path equivalences for skills/ and agents/ directories.
@@ -46,6 +47,10 @@
         ".github/skills/": ".opencode/skills/",
         ".github/agents/": ".opencode/agents/",
     },
+    "codex": {
+        ".github/skills/": ".agents/skills/",
+        ".github/agents/": ".codex/agents/",
+    },
 }
 
 
diff --git a/src/apm_cli/core/target_detection.py b/src/apm_cli/core/target_detection.py
index 1adbb2e6..6c5f3c3d 100644
--- a/src/apm_cli/core/target_detection.py
+++ b/src/apm_cli/core/target_detection.py
@@ -1,8 +1,8 @@
 """Target detection for auto-selecting compilation and integration targets.
 
 This module implements the auto-detection pattern for determining which agent
-targets (Copilot, Claude, Cursor, OpenCode) should be used based on existing
-project structure and configuration.
+targets (Copilot, Claude, Cursor, OpenCode, Codex) should be used based on
+existing project structure and configuration.
 
 Detection priority (highest to lowest):
 1. Explicit --target flag (always wins)
@@ -12,6 +12,7 @@
    - .claude/ only -> claude
    - .cursor/ only -> cursor
    - .opencode/ only -> opencode
+   - .codex/ only -> codex
    - Multiple target folders -> all
    - None exist -> minimal (AGENTS.md only, no folder integration)
 
@@ -23,10 +24,10 @@
 from typing import Literal, Optional, Tuple
 
 # Valid target values (internal canonical form)
-TargetType = Literal["vscode", "claude", "cursor", "opencode", "all", "minimal"]
+TargetType = Literal["vscode", "claude", "cursor", "opencode", "codex", "all", "minimal"]
 
 # User-facing target values (includes aliases accepted by CLI)
-UserTargetType = Literal["copilot", "vscode", "agents", "claude", "cursor", "opencode", "all", "minimal"]
+UserTargetType = Literal["copilot", "vscode", "agents", "claude", "cursor", "opencode", "codex", "all", "minimal"]
 
 
 def detect_target(
@@ -56,6 +57,8 @@ def detect_target(
             return "cursor", "explicit --target flag"
         elif explicit_target == "opencode":
             return "opencode", "explicit --target flag"
+        elif explicit_target == "codex":
+            return "codex", "explicit --target flag"
         elif explicit_target == "all":
             return "all", "explicit --target flag"
     
@@ -69,6 +72,8 @@ def detect_target(
             return "cursor", "apm.yml target"
         elif config_target == "opencode":
             return "opencode", "apm.yml target"
+        elif config_target == "codex":
+            return "codex", "apm.yml target"
         elif config_target == "all":
             return "all", "apm.yml target"
     
@@ -77,6 +82,7 @@ def detect_target(
     claude_exists = (project_root / ".claude").exists()
     cursor_exists = (project_root / ".cursor").is_dir()
     opencode_exists = (project_root / ".opencode").is_dir()
+    codex_exists = (project_root / ".codex").is_dir()
     detected = []
     if github_exists:
         detected.append(".github/")
@@ -86,6 +92,8 @@ def detect_target(
         detected.append(".cursor/")
     if opencode_exists:
         detected.append(".opencode/")
+    if codex_exists:
+        detected.append(".codex/")
 
     if len(detected) >= 2:
         return "all", f"detected {' and '.join(detected)} folders"
@@ -97,9 +105,11 @@ def detect_target(
         return "cursor", "detected .cursor/ folder"
     elif opencode_exists:
         return "opencode", "detected .opencode/ folder"
+    elif codex_exists:
+        return "codex", "detected .codex/ folder"
     else:
         # No known target folders exist - minimal output
-        return "minimal", "no .github/, .claude/, .cursor/, or .opencode/ folder found"
+        return "minimal", "no .github/, .claude/, .cursor/, .opencode/, or .codex/ folder found"
 
 
 def should_integrate_vscode(target: TargetType) -> bool:
@@ -150,10 +160,22 @@ def should_integrate_cursor(target: TargetType) -> bool:
     return target in ("cursor", "all")
 
 
+def should_integrate_codex(target: TargetType) -> bool:
+    """Check if Codex CLI integration should be performed.
+
+    Args:
+        target: The detected or configured target
+
+    Returns:
+        bool: True if Codex integration (agents, skills, hooks) should run
+    """
+    return target in ("codex", "all")
+
+
 def should_compile_agents_md(target: TargetType) -> bool:
     """Check if AGENTS.md should be compiled.
     
-    AGENTS.md is generated for vscode, all, and minimal targets.
+    AGENTS.md is generated for vscode, codex, all, and minimal targets.
     It's the universal format that works everywhere.
     
     Args:
@@ -162,7 +184,7 @@ def should_compile_agents_md(target: TargetType) -> bool:
     Returns:
         bool: True if AGENTS.md should be generated
     """
-    return target in ("vscode", "opencode", "all", "minimal")
+    return target in ("vscode", "opencode", "codex", "all", "minimal")
 
 
 def should_compile_claude_md(target: TargetType) -> bool:
@@ -195,7 +217,8 @@ def get_target_description(target: UserTargetType) -> str:
         "claude": "CLAUDE.md + .claude/commands/ + .claude/agents/ + .claude/skills/",
         "cursor": ".cursor/agents/ + .cursor/skills/ + .cursor/rules/",
         "opencode": "AGENTS.md + .opencode/agents/ + .opencode/commands/ + .opencode/skills/",
-        "all": "AGENTS.md + CLAUDE.md + .github/ + .claude/ + .cursor/ + .opencode/",
+        "codex": "AGENTS.md + .agents/skills/ + .codex/agents/ + .codex/hooks.json",
+        "all": "AGENTS.md + CLAUDE.md + .github/ + .claude/ + .cursor/ + .opencode/ + .codex/ + .agents/",
         "minimal": "AGENTS.md only (create .github/ or .claude/ for full integration)",
     }
     return descriptions.get(normalized, "unknown target")
diff --git a/src/apm_cli/integration/base_integrator.py b/src/apm_cli/integration/base_integrator.py
index 05cfab3c..8df8dc5c 100644
--- a/src/apm_cli/integration/base_integrator.py
+++ b/src/apm_cli/integration/base_integrator.py
@@ -208,21 +208,25 @@ def partition_managed_files(
         hook_tuple = tuple(hook_prefixes)
 
         # Single O(M) pass -- each path is routed in O(1)
+        # Component_map is checked first: it holds specific (root, subdir)
+        # pairs and takes priority over broad prefix matching.  This prevents
+        # catch-all hook prefixes (e.g. ".codex/") from swallowing paths
+        # that belong to a more specific bucket (e.g. ".codex/agents/").
         for p in managed_files:
+            slash1 = p.find("/")
+            if slash1 > 0:
+                slash2 = p.find("/", slash1 + 1)
+                if slash2 > 0:
+                    bkey = component_map.get(
+                        (p[:slash1], p[slash1 + 1 : slash2])
+                    )
+                    if bkey:
+                        buckets[bkey].add(p)
+                        continue
             if p.startswith(skill_tuple):
                 buckets["skills"].add(p)
             elif p.startswith(hook_tuple):
                 buckets["hooks"].add(p)
-            else:
-                slash1 = p.find("/")
-                if slash1 > 0:
-                    slash2 = p.find("/", slash1 + 1)
-                    if slash2 > 0:
-                        bkey = component_map.get(
-                            (p[:slash1], p[slash1 + 1 : slash2])
-                        )
-                        if bkey:
-                            buckets[bkey].add(p)
 
         return buckets
 
diff --git a/src/apm_cli/integration/skill_integrator.py b/src/apm_cli/integration/skill_integrator.py
index 802a7e0a..d09664fc 100644
--- a/src/apm_cli/integration/skill_integrator.py
+++ b/src/apm_cli/integration/skill_integrator.py
@@ -936,8 +936,11 @@ def sync_integration(self, apm_package, project_root: Path,
             stats['errors'] += result['errors']
         
         # Clean .agents/skills/ (cross-tool agent skills standard, used by Codex)
+        # Only clean if .codex/ exists -- .agents/ is cross-tool, so we must
+        # not delete skills managed by other tools when Codex is not active.
+        codex_dir = project_root / ".codex"
         agents_skills_dir = project_root / ".agents" / "skills"
-        if agents_skills_dir.exists():
+        if codex_dir.exists() and agents_skills_dir.exists():
             result = self._clean_orphaned_skills(agents_skills_dir, installed_skill_names)
             stats['files_removed'] += result['files_removed']
             stats['errors'] += result['errors']
diff --git a/src/apm_cli/integration/targets.py b/src/apm_cli/integration/targets.py
index a6ff9ae5..500da0fa 100644
--- a/src/apm_cli/integration/targets.py
+++ b/src/apm_cli/integration/targets.py
@@ -161,7 +161,7 @@ def supports(self, primitive: str) -> bool:
     ),
     # Codex CLI: skills use the cross-tool .agents/ dir (agent skills standard),
     # agents are TOML under .codex/agents/, hooks merge into .codex/hooks.json.
-    # Instructions are compile-only (AGENTS.md) — not installed.
+    # Instructions are compile-only (AGENTS.md) -- not installed.
     "codex": TargetProfile(
         name="codex",
         root_dir=".codex",
diff --git a/tests/unit/integration/test_data_driven_dispatch.py b/tests/unit/integration/test_data_driven_dispatch.py
index 85f68b98..df8bc935 100644
--- a/tests/unit/integration/test_data_driven_dispatch.py
+++ b/tests/unit/integration/test_data_driven_dispatch.py
@@ -495,9 +495,9 @@ def test_partition_routes_codex_paths_correctly(self):
         }
         buckets = BaseIntegrator.partition_managed_files(managed)
         assert ".agents/skills/my-skill/SKILL.md" in buckets["skills"]
-        # Codex hooks mapping has empty subdir, so .codex/ is a
-        # catch-all hook prefix -- both agents and hooks route there.
-        assert ".codex/agents/my-agent.toml" in buckets["hooks"]
+        # Codex agents under .codex/agents/ route to the agents_codex bucket.
+        assert ".codex/agents/my-agent.toml" in buckets["agents_codex"]
+        # Only true Codex hook paths route to the hooks bucket.
         assert ".codex/hooks/pkg/script.sh" in buckets["hooks"]
 
 
diff --git a/tests/unit/integration/test_hook_integrator.py b/tests/unit/integration/test_hook_integrator.py
index dba96196..744e5920 100644
--- a/tests/unit/integration/test_hook_integrator.py
+++ b/tests/unit/integration/test_hook_integrator.py
@@ -1479,7 +1479,7 @@ def _make_package_info(self, name="test-pkg", hook_data=None):
             }
 
         hook_file = hooks_dir / "hooks.json"
-        with open(hook_file, 'w') as f:
+        with open(hook_file, 'w', encoding='utf-8') as f:
             json.dump(hook_data, f)
 
         pi = MagicMock()

From 5b02dd9db69152a7125b7f092cb9599c4d204843 Mon Sep 17 00:00:00 2001
From: danielmeppiel <dmeppiel@microsoft.com>
Date: Tue, 31 Mar 2026 14:35:11 +0200
Subject: [PATCH 8/9] docs: add Codex CLI to supported targets across
 documentation

- README.md: add Codex CLI to tagline
- index.mdx: add Codex to feature card and quick start summary
- why-apm.md: move Codex from 'bridges' to 'native integration'

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 README.md                                     | 2 +-
 docs/src/content/docs/index.mdx               | 4 ++--
 docs/src/content/docs/introduction/why-apm.md | 4 ++--
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 6d1f5b19..71c071e1 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
 
 Think `package.json`, `requirements.txt`, or `Cargo.toml` — but for AI agent configuration.
 
-GitHub Copilot · Claude Code · Cursor · OpenCode
+GitHub Copilot · Claude Code · Cursor · OpenCode · Codex
 
 **[Documentation](https://microsoft.github.io/apm/)** · **[Quick Start](https://microsoft.github.io/apm/getting-started/quick-start/)** · **[CLI Reference](https://microsoft.github.io/apm/reference/cli-commands/)**
 
diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
index fe30e34e..e7565ced 100644
--- a/docs/src/content/docs/index.mdx
+++ b/docs/src/content/docs/index.mdx
@@ -26,7 +26,7 @@ APM fixes this. You declare your project's agent configuration once in `apm.yml`
 
 <CardGrid>
   <Card title="One Manifest, Every Agent" icon="document">
-    `apm.yml` declares skills, instructions, prompts, agents, hooks, plugins, and MCP servers — deployed to Copilot, Claude Code, Cursor, and OpenCode from a single source of truth.
+    `apm.yml` declares skills, instructions, prompts, agents, hooks, plugins, and MCP servers — deployed to Copilot, Claude Code, Cursor, OpenCode, and Codex from a single source of truth.
   </Card>
   <Card title="Dependencies That Resolve" icon="random">
     Packages depend on packages. APM resolves the full tree — transitive dependencies just work, like npm or pip.
@@ -92,7 +92,7 @@ New developer joins the team:
 git clone <org/repo> && cd <repo> && apm install
 ```
 
-**That's it.** Copilot, Claude, Cursor, OpenCode — every harness is configured with the right context and capabilities. The manifest defines the project's custom and portable Agentic SDLC setup installable in a single command.
+**That's it.** Copilot, Claude, Cursor, OpenCode, Codex — every harness is configured with the right context and capabilities. The manifest defines the project's custom and portable Agentic SDLC setup installable in a single command.
 
 ## Open Source & Community
 
diff --git a/docs/src/content/docs/introduction/why-apm.md b/docs/src/content/docs/introduction/why-apm.md
index db8f4898..3f8280cc 100644
--- a/docs/src/content/docs/introduction/why-apm.md
+++ b/docs/src/content/docs/introduction/why-apm.md
@@ -35,8 +35,8 @@ dependencies:
 Run `apm install` and APM:
 
 - **Resolves transitive dependencies** — if package A depends on package B, both are installed automatically.
-- **Integrates primitives** -- instructions, prompts, agents, and skills are deployed to `.github/`, `.claude/`, `.cursor/`, and `.opencode/` based on which directories exist. GitHub Copilot, Claude, Cursor, and OpenCode read these natively.
-- **Bridges other tools** — for Codex, Gemini, and other tools without native integration, `apm compile` generates compatible instruction files (`AGENTS.md`, `CLAUDE.md`).
+- **Integrates primitives** -- instructions, prompts, agents, and skills are deployed to `.github/`, `.claude/`, `.cursor/`, `.opencode/`, and `.codex/` based on which directories exist. GitHub Copilot, Claude, Cursor, OpenCode, and Codex read these natively.
+- **Bridges other tools** — for Gemini and other tools without native integration, `apm compile` generates compatible instruction files (`AGENTS.md`, `CLAUDE.md`).
 
 ## APM vs. Manual Setup
 

From 6cff65e9782d122c6769a2a621f0104c06f61467 Mon Sep 17 00:00:00 2001
From: danielmeppiel <dmeppiel@microsoft.com>
Date: Tue, 31 Mar 2026 14:46:30 +0200
Subject: [PATCH 9/9] fix: add codex to expected targets in test_scope.py

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 tests/unit/core/test_scope.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/unit/core/test_scope.py b/tests/unit/core/test_scope.py
index 21a265fb..3c978b5c 100644
--- a/tests/unit/core/test_scope.py
+++ b/tests/unit/core/test_scope.py
@@ -158,7 +158,7 @@ class TestTargetProfileUserScope:
     """Validate user-scope metadata on TargetProfile in KNOWN_TARGETS."""
 
     def test_all_known_targets_present(self):
-        expected = {"copilot", "claude", "cursor", "opencode"}
+        expected = {"copilot", "claude", "cursor", "opencode", "codex"}
         assert set(KNOWN_TARGETS.keys()) == expected
 
     def test_each_target_has_user_supported(self):