APC Should Stay Clone-Safe, APX Should Stay Machine-Local

#ai #opensource #devtools #tutorial

APC Should Stay Clone-Safe, APX Should Stay Machine-Local

The cleanest way to decide where something belongs in APC/APX is simple: would I want this exact thing to survive a fresh clone on another machine?

If yes, it belongs in APC. If no, it belongs in APX.

That one question keeps the stack honest. APC stays portable. APX stays useful on the machine that is actually running the work. When those two layers blur, projects become harder to share, harder to audit, and harder to recover after a switch in tools or laptops.

The split in one sentence

APC is the project contract. APX is the runtime that executes it.

The APC repo README says the goal is a single neutral directory for project-level agent context. The APX README says the filesystem is the source of truth for project definitions and curated memory, while runtime state lives in ~/.apx/ and is never committed. That is the boundary.

Clone-safe belongs in APC

Clone-safe data is the stuff another developer, another agent runtime, or another machine should be able to read immediately after checkout. It should be reviewable in git and stable enough to travel.

Good APC examples:

AGENTS.md for the repo-wide contract
.apc/project.json for stable project identity
.apc/agents/<slug>.md for agent roles and instructions
.apc/skills/ for reusable project skills
.apc/mcps.json for shared MCP hints without secrets

That is project meaning. It is what should follow the repository, not the laptop.

A quick check helps: if the file still makes sense after a git clone, it probably belongs in APC.

Machine-local belongs in APX

Machine-local data is the stuff that should die with the machine or be rebuilt there. It can be useful, but it should not become shared project truth.

Good APX examples:

runtime configuration under ~/.apx/config.json
permission mode and other local policy
sessions, conversations, and message logs under ~/.apx/
caches and other runtime state
per-machine MCP secrets

That data is real, but it is not portable context. It is execution state.

This matters because a repo should not smuggle one person's local setup into everybody else's clone. A project can say what it needs; the machine can decide how to run it today.

Why the boundary pays off

When APC stays clone-safe, the repo is easier to review. You can see the project shape without opening a hidden store. You can diff instructions instead of chasing side effects. You can clone the repo somewhere else and still understand what it wants.

When APX stays machine-local, the runtime can adapt without contaminating the repo. One machine can use a different permission mode, another can use a different model default, and a third can keep a longer local message history. The project contract does not change.

That is the real win: the project stays stable, while the runtime stays flexible.

A practical decision test

Before you add a new file or setting, ask these three questions:

Does every compatible tool need to read this? Put it in APC.
Does it describe the project, not the machine? Put it in APC.
Does it depend on local trust, local credentials, or recent execution? Put it in APX.

Examples:

A new agent role for code review? APC.
A Telegram bot token? APX.
A durable note about how the project handles reviews? APC.
A log of the last review conversation? APX.

If you are still unsure, use the clone test. If the answer should survive a fresh checkout, keep it portable. If it should not, keep it local.

What APX makes possible

APX is not just storage for local junk. It is the layer that turns clone-safe context into daily use. It registers projects, runs agents, reads memory, tails messages, and bridges to runtimes and MCPs.

A small workflow is enough to feel the split:

apx init
apx memory reviewer
apx messages tail

apx init makes the project legible to the runtime. apx memory shows the durable facts that were curated for an agent. apx messages tail shows the live trail of what the runtime is doing right now. One repo, one runtime, two different jobs.

Bottom line

APC should carry what survives a clone. APX should carry what only matters on the current machine.

That rule is simple, but it keeps the whole system sane. APC stays portable and reviewable. APX stays local and practical. And the line between them stays sharp enough that another runtime can still read the same project without guessing.