IDE & tool integration

APM ships agent context (instructions, prompts, agents, skills, MCP servers) into the directories your AI coding tools read at runtime. Each tool has its own slot layout; APM detects which slots exist and writes the right files in the right places.

This page is a hub. It tells you which tools are supported, how detection works, and where to read the per-tool details.

Supported tools

The full slot-by-slot capability table lives in Targets matrix. At a glance, APM currently writes for:

Target	Marker / signal	Notes
VS Code + Copilot	`.github/copilot-instructions.md`	Native instructions, prompts, agents
Claude Code	`.claude/`	Skills, agents, commands, MCP
Cursor	`.cursor/`	Rules, commands, MCP
Codex CLI	`.codex/`	Skills, MCP
Gemini CLI	`.gemini/` or `GEMINI.md`	Single-file or distributed
OpenCode	`.opencode/`	Skills, MCP
Windsurf	`.windsurf/`	Rules + Skills + Workflows + MCP
Agent-Skills (cross)	`.agents/skills/`	Vendor-neutral skill sharing

For exact per-target capabilities (which primitives are supported, transformer used, file layout), see Targets matrix.

How target detection works

When you run apm install or apm compile without --target, APM auto-detects which tools your project uses by looking for the markers above. Multiple targets can be active simultaneously.

apm targets                    # list detected and supported targets
apm install --target claude    # force a specific target

If no marker is present, APM emits the [x] No harness detected error - see Common errors.

To pin targets in the manifest:

target:
  - claude
  - copilot
  - cursor

The target: field accepts either a YAML list or a CSV string. See Manifest schema.

Primitive flow per target

Each primitive type maps to a target-specific slot:

.apm/instructions/   ->   per target: rules / instructions / system prompts
.apm/prompts/        ->   per target: prompt files / commands
.apm/agents/         ->   per target: agent definitions (or skill conversion)
.apm/skills/         ->   per target: skills directory (Claude, Codex, OpenCode, .agents)
.apm/hooks/          ->   per target: lifecycle hooks (Claude only today)
mcp: in apm.yml      ->   per target: .mcp.json / settings.json / equivalent

Not every target supports every primitive type. When a primitive can’t land on a target, APM emits a warning at install time. Skim Targets matrix to set expectations before adding a primitive.

Deduplication: When .claude/rules/ already contains .md files (deployed by apm install), apm compile --target claude omits the instructions section from CLAUDE.md to avoid duplicate context. CLAUDE.md is still generated if it carries a constitution or dependency imports.

Common workflows

Add a target to an existing project

# Add Cursor alongside an existing Copilot setup
mkdir .cursor
apm install            # auto-detects the new marker
apm compile            # writes Cursor-specific output

Or pin in apm.yml and rerun install.

Remove a target

Edit apm.yml to drop the target from target:.
apm prune to remove APM-managed files for the dropped target.
apm install && apm compile to verify.

See Migration paths -> target migration.

For team projects where contributors use different IDEs, the agent-skills target writes a vendor-neutral .agents/skills/ tree that Claude Code, Codex, OpenCode, and others read directly. This avoids per-tool duplication when your team is multi-vendor.

apm install --target agent-skills

MCP server integration

MCP servers declared in apm.yml (under dependencies.mcp: or devDependencies.mcp:) are wired into each target’s MCP config on install:

.mcp.json at the repo root when .claude/ exists (Claude Code project scope)
.cursor/mcp.json (Cursor)
.codex/config.toml (Codex)
.vscode/mcp.json (VS Code)
opencode.json at the repo root when .opencode/ exists (OpenCode)
.gemini/settings.json (Gemini)
~/.codeium/windsurf/mcp_config.json (Windsurf)

For server installation patterns, registry resolution, and trust model, see MCP servers guide and apm mcp.

Per-tool reference pages

Pinpoint behaviour, slot layout, and known limits per target:

Targets matrix - capability grid
apm targets - detection and listing
apm install - target selection flags
apm compile - per-target output
apm mcp - MCP wiring per target

Troubleshooting

Symptom	Where to look
`[x] No harness detected`	Common errors
Compile produced no output	Compile zero-output
Wrong target picked, multiple harnesses	`apm targets`
MCP server not appearing in tool	MCP servers guide
Cursor command file dropped	Targets matrix - `claude_command` transformer