Why I Keep APX as a Reference Runtime, Not a Second Standard

I do not want APC to become a nice spec that looks clean on paper and stays vague in practice.

That is the real reason I keep building APX. APC defines the portable project contract. APX is the thing that forces that contract to survive real work.

A protocol or convention is easy to admire from a distance. It is much harder to use every day. The moment you try to wire it into a daemon, a CLI, a web admin, runtime state, sessions, messages, agents, and skills, the fuzzy parts show up fast. That is useful. The friction is the point.

I think a lot of tool ecosystems fail because they stop at the specification layer. They write down what should exist, but they never build the thing that has to deal with the ugly edges: startup order, file layout, local caches, identity, and what happens when a runtime restarts mid-task.

APX exists to make those edges visible.

APC says what the project is

APC is the project-owned layer. It gives a repository one neutral place for durable context: agent definitions, reusable skills, project rules, curated memory, and MCP hints.

The important part is that APC is not trying to be a runtime. It does not define a daemon, a session store, or a vendor-specific app model. That boundary is deliberate. If APC starts carrying runtime behavior, it stops being portable and starts becoming another tool-specific blob.

So APC has to stay small enough to share across tools, and strict enough to remain readable after the third integration you add.

APX says what the machine does

APX is the reference runtime that makes APC real today.

The README says the quiet part plainly: APX is a daemon plus CLI. It reads project context, runs agents, manages sessions, and keeps runtime state local under ~/.apx/. It also bridges to runtimes like Claude Code, Codex, OpenCode, Aider, and others.

That split matters because APX is where I can test the contract against actual behavior.

If I add a command like apx init, apx run, apx exec, apx memory, or apx messages tail, I am not just adding a convenience wrapper. I am asking a harder question: does this make the APC model clearer, or does it tempt me to smuggle runtime state into the repo?

That question keeps the design honest.

Why I want one reference runtime

I do not want a second standard.

I want one implementation that I can push against until the boundary stops moving in silly ways.

A reference runtime is useful for the same reason a reference implementation matters in any protocol work. It turns abstract language into behavior you can break, inspect, and improve. Without that, the spec can stay too broad. Different tools interpret the same idea in slightly different ways, and after a while nobody agrees on what the words mean.

APX gives me a concrete place to answer questions like:

• Where does project memory live?
• What belongs in APC and what belongs in runtime state?
• What gets projected into a compatible runtime, and what stays local?
• How do I keep the project portable without pretending the machine does not exist?

Those questions are not academic. They show up when a real agent session starts, when a daemon restarts, when a message log gets tailed, or when a skill needs to be installed into a runtime that was never designed around APC.

The uncomfortable part is useful

Building APX has taught me that some ambiguity only disappears after you ship code.

For example, the repo can say “APC is portable” as many times as it wants. That sentence only becomes useful when APX has to live with the consequences:

• project files stay in the repo
• sessions stay outside the repo
• skills have a clear home
• MCP hints do not become secret storage
• local runtime data does not leak back into the shared contract

That separation is easy to describe. It is harder to keep intact once a tool starts growing features.

That is why I like APX as a reference runtime instead of treating it as just another application layer. It gives me a forcing function. If a new feature makes the contract harder to explain, it is probably the wrong feature or the wrong home.

The daily workflow changed because of that split

The best sign that APX is doing useful work is not that it adds more automation. It is that it makes the next step obvious.

A clean flow looks more like this:

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

The commands are not the story. The story is that the repository keeps the durable context, while the runtime keeps the noisy execution trail.

That removes a lot of guesswork. When I return to a project later, I do not have to dig through whatever the last tool decided to cache in its own format. I can inspect the project contract directly, then ask APX to do the machine-local work around it.

That is a better mental model for me than “the agent remembered something.” It is more explicit. It is more debuggable. It is less romantic, which is usually a good sign.

What APX should not become

I also have to keep APX from becoming too important.

That sounds contradictory, but it is the main risk of building the reference runtime itself. Once the runtime gets useful, it becomes tempting to put every new idea into it. Then the runtime starts to swallow the protocol, and the protocol starts to depend on the runtime for meaning.

That is the failure mode I am trying to avoid.

APX should keep proving APC, not redefining it. It should be opinionated enough to expose the real mechanics of daily work, but not so opinionated that the project contract only makes sense inside one machine.

What I am really optimizing for

I am optimizing for clarity under stress.

A project with AI tooling will eventually hit the same problems every other system hits: drift, local state, hidden assumptions, and features that look clean until they need to survive collaboration.

APC is my answer for the shared contract.
APX is my answer for the local runtime that has to live with that contract.

I keep both because each one makes the other harder to lie about.

That is the part I trust most. The spec stays smaller because the runtime exists. The runtime stays useful because the spec exists. And every time I have to make a real decision between them, I get a better model of the system I am actually building.