feat: Support Codex CLI as integration target by Copilot · Pull Request #504 · microsoft/apm

Copilot · 2026-03-31T04:54:57Z

Description

Codex CLI uses a multi-directory config model that breaks APM's single-root_dir assumption: skills deploy to .agents/skills/ (cross-tool agent skills standard), while agents (TOML) and hooks live under .codex/.

Core abstraction: deploy_root: Optional[str] = None on PrimitiveMapping. When set, overrides target.root_dir for path computation. Default None = zero behavior change for existing targets.

"codex": TargetProfile(
    name="codex",
    root_dir=".codex",
    primitives={
        "agents": PrimitiveMapping("agents", ".toml", "codex_agent"),
        "skills": PrimitiveMapping("skills", "/SKILL.md", "skill_standard",
                                   deploy_root=".agents"),  # cross-tool dir
        "hooks": PrimitiveMapping("", "hooks.json", "codex_hooks"),
    },
    auto_create=False,
    detect_by_dir=True,
)

Foundation (targets.py, base_integrator.py): deploy_root field, Codex in KNOWN_TARGETS, get_integration_prefixes() emits .agents/, partition_managed_files() routes cross-root paths
Agent transform (agent_integrator.py): _write_codex_agent() — MD→TOML via format_id == "codex_agent", parsing YAML frontmatter for name/description, body as developer_instructions
Hook merge (hook_integrator.py): integrate_package_hooks_codex() — Cursor-pattern merge into .codex/hooks.json with _apm_source markers, scripts to .codex/hooks/{pkg}/
Skill routing (skill_integrator.py): All skill deploy paths use mapping.deploy_root or target.root_dir — Codex skills land in .agents/skills/, others unchanged
All integrators: sync_for_target() and path computation updated for deploy_root (agent, command, instruction, prompt, skill, hook)
Uninstall (engine.py): Deploy-root-aware sync, .agents/skills/ cleanup
CLI: --target codex on install, compile, pack
Docs: Integration guide, CLI reference, compilation guide, manifest schema, skills guide, CHANGELOG

Type of change

Bug fix
New feature
Documentation
Maintenance / refactor

Testing

Tested locally
All existing tests pass
Added tests for new functionality (if applicable)

16 new tests across 5 files (3197 total passing): target auto-detection (.codex/ yes, .agents/ alone no), dispatch gating, partition routing, MD→TOML transform, hook merge with _apm_source markers, skill deploy_root routing, security prefix validation.

Agent-Logs-Url: https://github.com/microsoft/apm/sessions/4df682f5-8518-41bb-888a-e5474153262f Co-authored-by: danielmeppiel <[email protected]>

- 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 <[email protected]>

… 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 <[email protected]> Co-authored-by: danielmeppiel <[email protected]>

Co-authored-by: Copilot <[email protected]> Co-authored-by: danielmeppiel <[email protected]>

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 <[email protected]>

Copilot

Pull request overview

Adds Codex CLI as a first-class APM integration target by introducing per-primitive deploy_root overrides (to support Codex's split .codex/ + .agents/ layout) and extending integrators, CLI flags, tests, and docs accordingly.

Changes:

Introduce PrimitiveMapping.deploy_root and propagate “effective root” pathing through integrators, uninstall sync, and prefix validation/partitioning.
Add Codex target profile and Codex-specific integrations (MD->TOML agent transform, hooks merge into .codex/hooks.json, skills routed to .agents/skills/).
Add Codex-related tests and update CLI/docs/changelog to surface the new target.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
`src/apm_cli/integration/targets.py`	Adds `deploy_root` and registers the `codex` target; expands integration prefix allowlist.
`src/apm_cli/integration/base_integrator.py`	Makes managed-file partitioning deploy-root-aware (but currently misroutes some Codex paths).
`src/apm_cli/integration/agent_integrator.py`	Uses deploy-root-aware target roots; adds Codex MD->TOML agent writer.
`src/apm_cli/integration/skill_integrator.py`	Routes skills via deploy_root and extends sync cleanup to `.agents/skills/`.
`src/apm_cli/integration/hook_integrator.py`	Adds Codex hook merge + script copy support and sync cleanup for `.codex/hooks.json`.
`src/apm_cli/integration/prompt_integrator.py`	Updates sync prefix/path computation for deploy_root-aware layouts.
`src/apm_cli/integration/command_integrator.py`	Updates install + sync to use deploy_root-aware paths.
`src/apm_cli/integration/instruction_integrator.py`	Updates install + sync to use deploy_root-aware paths.
`src/apm_cli/commands/uninstall/engine.py`	Makes uninstall sync deploy-root-aware and checks for skill dirs under deploy_root.
`src/apm_cli/commands/install.py`	Adds `--target codex` and updates integration logging paths.
`src/apm_cli/commands/compile/cli.py`	Adds `--target codex` option (but underlying target detection/compiler logic is not yet updated).
`src/apm_cli/commands/pack.py`	Adds `--target codex` option (but pack-time target filtering/detection is not yet updated).
`tests/unit/integration/test_targets.py`	Adds Codex auto-detection tests.
`tests/unit/integration/test_agent_integrator.py`	Adds Codex agent MD->TOML transformation tests and filename expectations.
`tests/unit/integration/test_hook_integrator.py`	Adds Codex hook merge tests for `.codex/hooks.json`.
`tests/unit/integration/test_skill_integrator.py`	Adds tests asserting Codex skills deploy to `.agents/skills/`.
`tests/unit/integration/test_data_driven_dispatch.py`	Adds Codex dispatch gating + partition routing + prefix security tests.
`docs/src/content/docs/reference/manifest-schema.md`	Documents `codex` as a target and mentions `.codex/` auto-detection.
`docs/src/content/docs/reference/cli-commands.md`	Updates CLI reference to include codex in command options.
`docs/src/content/docs/integrations/ide-tool-integration.md`	Documents Codex destinations and behavior across primitives.
`docs/src/content/docs/guides/skills.md`	Updates skills guide for Codex routing to `.agents/skills/`.
`docs/src/content/docs/guides/compilation.md`	Updates compilation guide to include Codex behavior.
`CHANGELOG.md`	Adds Unreleased entries for Codex support and `deploy_root`.

Comments suppressed due to low confidence (1)

src/apm_cli/integration/base_integrator.py:192

partition_managed_files() adds hook prefixes using effective_root + '/' when mapping.subdir is empty. With Codex hooks mapped as subdir="", this makes the hook prefix ".codex/", which causes all ".codex/..." paths (including ".codex/agents/") to be bucketed under "hooks". That breaks uninstall/sync for Codex agents because AgentIntegrator.sync_for_target will get an empty managed_files subset while HookIntegrator won't delete ".codex/agents/" paths. Narrow the Codex hooks routing to only ".codex/hooks/" and ".codex/hooks.json" (or change the Codex hooks mapping to avoid an empty subdir) so ".codex/agents/*" routes to the agents_codex bucket.

                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":
                    hook_prefixes.append(prefix)

- 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 <[email protected]>

- 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 <[email protected]>

Co-authored-by: Copilot <[email protected]>

Initial plan

1b22ef2

Copilot AI assigned Copilot and danielmeppiel Mar 31, 2026

Copilot started work on behalf of danielmeppiel March 31, 2026 04:55 View session

Copilot AI linked an issue Mar 31, 2026 that may be closed by this pull request

Support Codex CLI as integration target #502

Closed

32 tasks

Copilot AI and others added 4 commits March 31, 2026 05:02

Initial plan for Codex CLI integration target

81432b4

Agent-Logs-Url: https://github.com/microsoft/apm/sessions/4df682f5-8518-41bb-888a-e5474153262f Co-authored-by: danielmeppiel <[email protected]>

Fix ASCII encoding violation in test comment

4085b0f

Co-authored-by: Copilot <[email protected]> Co-authored-by: danielmeppiel <[email protected]>

danielmeppiel added the enhancement Deprecated: use type/feature. Kept for issue history; will be removed in milestone 0.10.0. label Mar 31, 2026

Copilot AI changed the title ~~[WIP] Add support for Codex CLI as integration target~~ feat: Support Codex CLI as integration target Mar 31, 2026

Copilot finished work on behalf of danielmeppiel March 31, 2026 05:30

Copilot AI requested a review from danielmeppiel March 31, 2026 05:30

Merge branch 'main' into copilot/support-codex-cli-integration

09f1bfb

danielmeppiel marked this pull request as ready for review March 31, 2026 06:52

Copilot AI review requested due to automatic review settings March 31, 2026 06:52

Copilot started reviewing on behalf of danielmeppiel March 31, 2026 06:53 View session

Copilot AI reviewed Mar 31, 2026

View reviewed changes

danielmeppiel and others added 2 commits March 31, 2026 14:25

docs: add Codex CLI to supported targets across documentation

5b02dd9

- 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 <[email protected]>

danielmeppiel force-pushed the copilot/support-codex-cli-integration branch from 78f3422 to 5b02dd9 Compare March 31, 2026 12:41

danielmeppiel and others added 3 commits March 31, 2026 14:43

Merge branch 'main' into copilot/support-codex-cli-integration

0a8ed90

Merge branch 'main' into copilot/support-codex-cli-integration

6303687

fix: add codex to expected targets in test_scope.py

6cff65e

Co-authored-by: Copilot <[email protected]>

danielmeppiel merged commit 22ad585 into main Mar 31, 2026
8 checks passed

danielmeppiel deleted the copilot/support-codex-cli-integration branch March 31, 2026 12:55

danielmeppiel mentioned this pull request Mar 31, 2026

chore: prepare v0.8.8 release #508

Merged

OKKU-Okuda mentioned this pull request Apr 19, 2026

apm compile --target codex is a silent no-op in distributed mode, leaving stale AGENTS.md with missing dependency instructions #766

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Support Codex CLI as integration target#504

feat: Support Codex CLI as integration target#504
danielmeppiel merged 12 commits intomainfrom
copilot/support-codex-cli-integration

Copilot AI commented Mar 31, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Copilot AI commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Mar 31, 2026 •

edited

Loading