APC Keeps the Project Portable. APX Keeps It Alive.

Most AI toolchains fail for the same reason: they mix durable project context with local runtime state. The result is brittle. One machine has the right prompt history, another has a different agent config, and nobody can tell what belongs in the repo versus what belongs on the laptop.

APC and APX split that problem cleanly.

APC is the portable context layer. It gives a project one neutral place for shared rules and agent definitions: AGENTS.md, .apc/project.json, .apc/agents/*.md, and shared MCP hints in .apc/mcps.json. APX is the daily-use runtime and tooling layer. It reads that project context, runs agents, manages sessions, and keeps local activity outside the repo in ~/.apx/.

That split sounds small. It is not. It changes how a team works.

What belongs in APC

APC is for facts that should travel with the repository.

If a teammate clones the repo, they should immediately see the same project contract. In APX, that means things like:

• AGENTS.md for the root project rules
• .apc/project.json for stable project metadata and identity
• .apc/agents/<name>.md for reusable agent definitions
• .apc/mcps.json for shared MCP entries that do not contain secrets

These files are portable because they describe the project, not one machine.

APC is also intentionally boring. That is good. It is the thing every compatible tool can read without needing the rest of your personal runtime setup.

What belongs in APX

APX is what makes APC usable every day.

The APX README is explicit: APX is a daemon plus CLI. The daemon manages projects, agents, sessions, and logs. The CLI gives you commands like apx init, apx run, apx exec, apx memory, and apx messages tail.

Runtime state stays local. That means sessions, conversations, messages, caches, and similar ephemeral data live under ~/.apx/, not in the repo. That choice matters because runtime state is personal, noisy, and often private.

APX also adds the plumbing APC does not try to own:

• runtimes for Claude Code, Codex, OpenCode, and Aider
• direct engine calls through Anthropic, OpenAI, Gemini, Ollama, or a mock
• Telegram plugin support
• MCP scope handling

So APC defines the project contract, while APX executes it.

Why the split matters

If you put runtime logs in the repo, you create merge noise and leak local history. If you put shared project rules only in a personal app config, you lose portability. APC and APX avoid both mistakes.

The split gives you three practical wins:

1. Reproducibility. The same repo carries the same durable context.
2. Privacy. Local sessions and message logs stay on the machine that created them.
3. Cleaner collaboration. Reviewers inspect project rules, not accidental runtime debris.

The MCP model shows the same pattern. Shared MCP hints belong in .apc/mcps.json when they are safe to commit. Secret-bearing MCPs belong in APX runtime scope under ~/.apx/projects/<apxId>/mcps.json. Same feature family, different storage, because secrecy and portability are not the same problem.

Telegram uses the same logic too. APX can route a channel to a project or a master agent, but that channel wiring is runtime behavior. The project context still lives in APC; APX just applies it at the edge.

A simple workflow

A clean APC/APX workflow looks like this:

apx init
apx agent list
apx run cody --runtime claude-code "Review the open PRs and summarize them"
apx memory cody
apx messages tail

In that flow, APC gives APX the stable project shape. APX then does the work: it runs the agent, stores the session locally, and exposes the message trail for later inspection.

That is the real design idea here. APC is the portable contract. APX is the executor.

When those roles stay separate, the project stays readable, the runtime stays local, and the system stays easier to reason about.