APX Agent Vault Should Reuse Agents Without Replacing APC
Reusable agent templates are useful. A second source of truth for project agents is not.
That is why APX's Agent Vault is a good idea only if it stays in the right layer.
APC is the portable context layer. It keeps the repo-owned contract in AGENTS.md, .apc/, agent files, skills, and other durable artifacts. APX is the daily-use runtime and tooling layer on top of that contract. It gives you the CLI, daemon, web admin, runtimes, and machine-local state that make APC practical every day.
The Agent Vault belongs on the APX side.
What the vault actually is
APX documents the vault as a machine-wide library of reusable agent templates. Bundled templates live inside the APX package, while user templates and overrides live in ~/.apx/agents/<slug>.md.
That split matters.
The vault is not part of the repository. It is a local convenience layer for reuse across projects on one machine. You can list it with apx agent vault list, add a new reusable template with apx agent vault add reviewer ..., and hide bundled defaults with tombstones that APX stores in ~/.apx/agents/.removed.json.
In other words, the vault is runtime furniture. Useful, local, and intentionally not portable.
What should stay in APC
Project agents are different.
APX's own docs say the canonical project definition is .apc/agents/<slug>.md. That is the file that belongs to the repo, can be reviewed in git, and can travel to Codex, Claude Code, Cursor, or any other APC-aware runtime.
That is the boundary worth protecting.
If a team starts treating ~/.apx/agents/ as the real home of project agents, APC loses authority. The same repository can behave differently on two laptops, and the portable layer becomes only a partial hint instead of the contract.
That would be a regression.
APC should own what the project means. APX should help you work faster with it.
The practical workflow that keeps both layers clean
The vault model works well because APX gives you two import paths.
If a shared template is already good enough, apx agent import cody-developer lets the project use it without pretending that every reusable default belongs in the repo.
If the project needs its own variation, apx agent import tessa-qa --copy copies the template into .apc/agents/ so the project can change it locally.
That second path is the important one.
--copy turns reuse into a starting point, not a hidden dependency. Once the file lives in .apc/agents/, the project owns it. Reviewers can see the diff. Another machine can clone the repo and get the same agent definition. Another APC-compatible runtime can read the same contract.
That is exactly the APC/APX split working as intended:
- APC stores the durable project-owned agent definition.
- APX stores the reusable machine-local template catalog.
- Import bridges them without collapsing them.
Why copy-on-write and tombstones are good signs
Two design details in APX reinforce this boundary.
First, editing a bundled vault template is copy-on-write. APX materializes a user-layer file in ~/.apx/agents/ instead of mutating the bundled default inside the package. That keeps the reusable layer explicit.
Second, removing a bundled template does not delete package files. APX tombstones the slug and lets you restore it later. That shows the vault is a managed local catalog, not project state.
Both decisions push in the same direction: reuse should be flexible, but the location and ownership of state should stay clear.
The deeper lesson
Agent systems get messy when convenience starts owning identity.
A global vault is convenient. A repo contract is portable. APX works because it does not confuse those jobs.
Use the vault to bootstrap work faster across projects. Use .apc/agents/ when the project itself needs to define, review, or preserve an agent. That keeps APC clean as the portable context layer and lets APX stay what it should be: the runtime and tooling layer that makes daily agent work usable without quietly taking ownership away from the repo.
Top comments (1)
Reuse only works if the agent carries the right boundaries with it. Otherwise a vault becomes a collection of convenient personalities with unclear assumptions. I like the idea of preserving project context as the contract, not replacing it with a generic reusable agent.