apm compile

Compile your instructions primitives into the AGENTS.md / CLAUDE.md / GEMINI.md root context files (and per-harness rules trees) that each agent harness reads at startup.

Synopsis

apm compile [OPTIONS]

Description

apm compile reads instructions/*.instructions.md from .apm/ (your project) and apm_modules/ (installed dependencies), then writes one set of root context files plus per-harness rules per resolved target.

Discovery and output are bounded to the active Git checkout. Nested Git repositories and linked worktrees below it are excluded, including when includes: auto is set. Run apm compile from a nested checkout to compile it.

Compile only handles instructions (and optionally a single chatmode to prepend via --chatmode). Other primitive types – prompts, skills, agents, hooks, commands, MCP – are deployed by apm install directly into the harness directories that consume them and are not touched by apm compile’s own deployment step. See Primitives and targets for the full reach map.

After a successful non-dry-run compile, APM also reconciles deployed-file ownership with the current targets: declaration. If the declared target set contracts, artifacts and lockfile entries owned by the removed target are cleaned up with the same hash and user-edit safeguards as apm install – this also includes merge-hook config/sidecar entries (see Hooks and commands for what those files are) even though compile does not itself deploy hooks.

When you actually need it: compile is optional for the copilot target – GitHub Copilot natively reads .github/instructions/*.instructions.md (with their applyTo: frontmatter) that apm install already deploys. Compile is recommended for every other context-producing target (claude, cursor, codex, gemini, grok-build, opencode, antigravity, windsurf, kiro, hermes, intellij), which load instructions through a root context file or harness-specific rules folder that compile generates.

Resolution order for which targets to compile:

--target / --all on the command line
targets: field in apm.yml
Auto-detection from the documented filesystem signals

Use apm targets to preview what auto-detection resolves to before compiling.

The compiled output is scanned for hidden Unicode before any file is written. Critical findings cause the command to exit non-zero. See Drift and secure by default.

Options

Target selection

Flag	Description
`-t, --target VALUE`	Target(s) to compile. Comma-separated. The help text derives its values from the same catalog used for validation, including `intellij`.
`--all`	Compile for all canonical targets. Equivalent to `--target all` and mutually exclusive with `--target`. Preferred form.

vscode and agents are accepted as deprecated aliases for copilot and emit a one-line warning. --target all also emits a deprecation warning – prefer --all.

Every accepted project target is also accepted by compile. grok-build produces AGENTS.md. Targets without root-context output, including agent-skills and the experimental grok-cloud target, are successful no-ops. antigravity and hermes are explicit-only, while intellij is MCP-only. None is included in all. For intellij, file primitives use the Copilot profile and produce AGENTS.md; IntelliJ-specific integration remains MCP-only. Use apm install or apm deps update when you want shared .agents/skills/ output.

Output control

Flag	Description
`--root DIR`	Redirect generated artifacts (AGENTS.md and per-target files) under `DIR` while `apm.yml`, `.apm/`, and `apm_modules/` still resolve from the current working directory. Mirrors `pip install --target`. `DIR` is created if missing. Not valid with `--watch`.
`-o, --output PATH`	Output file path. Only applies in single-file mode (`--single-agents`). Default: `AGENTS.md`.
`--single-agents`	Force single-file compilation (legacy). Writes one combined file at `--output` instead of a distributed per-directory target-file tree. Applies to every target that uses distributed placement.
`--clean`	Remove orphaned AGENTS.md files no longer produced by the current primitive set. Nested Git repositories and linked worktrees below the cleanup root are excluded; to clean one, make that checkout the cleanup root, usually by running `apm compile --clean` there. For `--target claude`, also removes a stale APM-generated CLAUDE.md once instructions live in `.claude/rules/`. Hand-authored CLAUDE.md files (files without the `<!-- Generated by APM CLI -->` marker) are never deleted.
`--no-dedup` / `--no-force-instructions`	Keep the instructions section in the compiled output even when target-native rule files such as `.claude/rules/`, `.github/instructions/`, or `.agents/rules/` are populated. Hidden alias: `--force-instructions`.

Project compilation protects root AGENTS.md and CLAUDE.md files, including destinations selected with --root. If an existing root file has no exact APM-generated marker line among its first five lines, full-file compilation retains it and prints a warning. Live compiles leave the file unchanged; dry runs report that it would be retained without writing it. Delete or rename that file before compiling if generated output should replace it. For section-scoped AGENTS.md updates, see compilation.agents_md.

If a constitution or dependency imports still require CLAUDE.md, --clean regenerates an APM-generated file instead of removing it. An unmarked, hand-authored root CLAUDE.md remains unchanged.

--clean is a file-deleting operation. Before running it live, pass --dry-run to preview exactly what would be removed without touching the filesystem:

apm compile --clean --dry-run --target claude

The dry-run output shows [dry-run] would remove stale CLAUDE.md -- instructions now live in .claude/rules/ when an APM-generated file would be deleted, or [dry-run] would skip removal of CLAUDE.md: hand-authored file will not be deleted. Delete or rename it manually if duplicate context is unwanted. when a hand-authored file is found. No files are written or deleted during dry-run.

Content

Flag	Description
`--chatmode NAME`	Prepend the named chatmode to the generated AGENTS.md.
`--no-links`	Skip markdown link resolution.
`--with-constitution` / `--no-constitution`	Include or omit the Spec Kit `memory/constitution.md` block at the top. Default: included. When disabled, an existing block is preserved but not regenerated.
`--local-only`	Ignore `apm_modules/`; compile only `.apm/` primitives.
`--force-instructions` / `--no-force-instructions`	Include the instructions section in CLAUDE.md and AGENTS.md even when `.claude/rules/`, `.github/instructions/`, or `.agents/rules/` already covers that content (overrides the default deduplication). `--no-dedup` is a hidden backward-compat alias for `--force-instructions`.
`--legacy-skill-paths`	Accepted for compatibility; skill deployment happens in `apm install` / `apm deps update`, not `apm compile`.

Modes

Flag	Description
`--watch`	Re-run compilation on file changes. See Watch mode.
`--validate`	Validate primitives and exit. No files written.
`--dry-run`	Show placement decisions without writing files.
`-v, --verbose`	Show source attribution and optimizer analysis.

Global compilation

Global compilation keeps supported user-scope root-context targets in sync with globally installed instruction packages – one command, no per-tool setup.

Flag	Description
`-g, --global`	Compile user-scope root context files from `~/.apm/apm_modules`. Writes targets declared by `target:` or `targets:` in `~/.apm/apm.yml`, or every supported user-scope target when neither field is declared. Not valid with project-output flags such as `--target`, `--all`, `--watch`, `--root`, or `--output`. Exits non-zero if `~/.apm/apm_modules` does not exist.

apm compile --global is explicit. apm install -g does not run it; instead, when global instructions land on a root-context-only target, install prints a one-line hint pointing at apm compile -g. Run it manually after adding or removing global packages. Hand-authored files (files that do not carry the APM-generated marker) are never overwritten.

Because --target is rejected alongside --global, target: or targets: in ~/.apm/apm.yml is how you narrow user-scope output. When it declares a target set, apm compile -g writes only those targets. If you install with an explicit apm install -g --target, update the manifest declaration before compiling; the explicit install flag does not replace it. Declare nothing and every applicable user-scope root context file is written. The manifest must be a regular, non-symlink file. Malformed or unreadable YAML, a non-mapping document, or an invalid target declaration stops compilation before any target output is written; fix the reported manifest problem and rerun the command.

targets: [claude, codex]

apm compile -g --dry-run

For OpenCode, apm compile -g writes ~/.config/opencode/AGENTS.md and retains scoped applyTo sections.

apm compile -g

Pin committed output with targets:

apm compile generates root context files: AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md (see Output layout per target below for the full per-target breakdown). Teams that commit these files into source control face a consistency problem: without target: or targets: set in apm.yml, auto-detection decides which files to produce based on which tool folders exist on the current machine. A contributor with only .claude/ locally produces claude output only; a developer who also has .github/ triggers the two-or-more-folders rule and gets the full all expansion – producing AGENTS.md, CLAUDE.md, GEMINI.md, and .github/copilot-instructions.md. The committed set silently tracks whoever last ran apm compile.

Set targets: in apm.yml to declare exactly which agent formats the project supports. Every run of apm compile – local developer, CI, cloud agent – then writes the same files regardless of which tool folders exist on that machine:

targets: [claude, cursor]   # compile writes exactly these two sets; nothing else

This makes the committed generated files deterministic for humans, cloud agents, and contributors who do not run apm compile locally and rely on the checked-in artifacts.

For the full list of accepted targets: values, see manifest schema – targets.

Examples

Compile for whatever the project is set up for:

apm compile

Compile for one target:

apm compile --target claude
apm compile --target copilot
apm compile --target cursor

Compile for several targets in one pass:

apm compile -t claude,copilot
apm compile -t claude,gemini

Compile for every canonical target:

apm compile --all

Validate without writing:

apm compile --validate

Preview placement:

apm compile --dry-run
apm compile -t claude,codex --dry-run -v

Skip dependencies and compile only local primitives:

apm compile --local-only

Remove stale AGENTS.md files after deleting primitives (also removes a stale APM-generated CLAUDE.md once .claude/rules/ owns the instructions):

apm compile --clean
apm compile --clean --target claude
apm compile --clean --target claude --dry-run

Redirect generated files to a scratch directory (sources stay in $PWD):

apm compile --root /tmp/agents-out --target copilot
ls /tmp/agents-out   # AGENTS.md / per-target files; the source tree stays clean

Watch mode

apm compile --watch monitors the project for source changes and re-runs compilation automatically.

Watched directories (when present): .apm/, .github/instructions/, .github/agents/.
Triggers on changes to .md files and apm.yml.
Editing apm.yml’s target: / targets: mid-session takes effect on the next file event; no need to restart the watcher. The CLI --target flag, when passed to apm compile --watch, still outranks apm.yml.
--clean is ignored in watch mode (a [!] warning is printed at startup). Run apm compile --clean separately between watch sessions to remove orphaned outputs.
1-second debounce to coalesce rapid edits.
Press Ctrl+C to stop.
Combine with --dry-run to validate placement on every save without writing.
When root files are retained, each recompile reports both the retained count and any other outputs generated (or planned in dry-run mode).

apm compile --watch
apm compile --watch --dry-run

Watch mode uses the same target resolution and compilation strategy as one-shot apm compile; --output only applies in single-file mode.

Output layout per target

apm compile writes root context files only; apm install manages prompts, agents, commands, hooks, MCP, and skill deployment directories.

Target	Compile outputs
`copilot`	`AGENTS.md`, `.github/copilot-instructions.md`
`claude`	`CLAUDE.md`
`grok-build`	`AGENTS.md`
`cursor`	`AGENTS.md`
`codex`	`AGENTS.md`
`opencode`	`AGENTS.md`
`gemini`	`AGENTS.md`, `GEMINI.md`
`antigravity`	`AGENTS.md`
`windsurf`	`AGENTS.md`
`kiro`	`AGENTS.md`
`hermes`	`AGENTS.md`
`intellij`	`AGENTS.md`
`agent-skills`	none
`grok-cloud`	none
`all`	`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`

.github/copilot-instructions.md is only managed by APM when its first line is the marker . Catalog root context files such as AGENTS.md, CLAUDE.md, and GEMINI.md are only managed by APM when they carry a generated marker. A hand-authored file is left untouched on both write and cleanup paths. To hand off an existing file to APM, prepend the marker (or delete the file) and re-run apm compile.

Strategy modes

There is no --strategy flag. Compilation runs in one of two modes:

Distributed (default) – writes a tree of focused target files (e.g. AGENTS.md, CLAUDE.md) next to the code they apply to, plus per-target subdirectories. This is the recommended mode and follows the Minimal Context Principle. Set compilation.strategy: single-file (or compilation.single_file: true) in apm.yml to opt out.
Single-file (--single-agents) – writes one combined file at --output (default AGENTS.md). Use when a harness or workflow requires a single context file. With multiple targets, target-specific root content remains separate and is not appended to AGENTS.md.

Distributed layout example

For a project with two scoped instructions (applyTo: "scripts/**" and applyTo: "tests/**") plus a generic one (no applyTo:), apm compile writes:

AGENTS.md            # generic instructions only
scripts/AGENTS.md    # instructions scoped to scripts/**
tests/AGENTS.md      # instructions scoped to tests/**

Each agent harness then loads only the file nearest the code it is working in. If you did not expect new AGENTS.md / CLAUDE.md files in subdirectories, this is the distributed default in effect; see Where compiled context files land for the rationale, or pass --single-agents for a single-file output.

Exit codes

Code	Meaning
0	Compilation succeeded (or `--validate` passed).
1	No `apm.yml`, no primitives to compile, validation failure, hidden-Unicode finding, or compilation error.
2	Conflicting flags (e.g. `--all` combined with `--target`, or `--root` combined with `--watch`).

apm install – fetches dependencies into apm_modules/ so compile can read them.
apm targets – shows what targets resolve to in the current project.
Concepts: primitives and targets
Concepts: lifecycle
Producer: compile – author workflow that calls compile with packaging-specific defaults.