Project Config Should Travel With APC

The APC/APX Boundary

When a team decides how an agent should behave in one repository, that decision should travel with the repository. That is why project config should live in APC.

APC is the portable context layer. It keeps repository-owned agent context in AGENTS.md and .apc/. APX is the daily-use runtime and tooling layer. It reads that portable context, merges it with machine-local runtime settings, and keeps sessions, messages, and secrets outside the repo.

That split becomes especially useful with configuration. APX documents two config layers:

• Global config lives in ~/.apx/config.json
• Project config lives in .apc/config.json

The rule is simple: machine-local settings stay machine-local, but repo-owned behavior travels with the project. This is stronger than convenience. It is a boundary that prevents silent drift.

Why the Boundary Matters

Imagine a team wants one project to route Telegram messages to a reviewer agent and to use a different super-agent model than the default machine setting. If that choice lives only in one developer's ~/.apx/config.json, the behavior is no longer really part of the project. Another clone on another machine can register the same APC project and get different operational behavior without noticing.

Putting that override in .apc/config.json fixes the problem. A small example from the APX docs looks like this:

{
  "super_agent": {
    "model": "groq:llama-3.3-70b-versatile",
    "permission_mode": "total"
  },
  "telegram": {
    "route_to_agent": "reviewer"
  }
}

That file belongs in the repo because it expresses project intent. APX then applies it only for that project.

The CLI makes the workflow explicit:

apx project config set my-app super_agent.model groq:llama-3.3-70b-versatile
apx project config set my-app telegram.route_to_agent reviewer
apx project config show my-app --effective

This is the right division of labor. APC owns the durable contract. APX owns the runtime merge.

What Not to Commit

The same docs also draw the line that matters most: never put secrets in .apc/config.json. API keys, provider credentials, daemon settings for your machine, and other private runtime details belong in ~/.apx/config.json, not in the repository.

APC should carry safe, reviewable project behavior. APX should keep private operational state local. That gives teams a clean model:

• Commit project overrides
• Keep credentials local
• Let APX merge both at runtime

Common Pitfalls

Without this split, teams usually fall into one of two bad patterns.

The first bad pattern is hiding project behavior in one laptop. The project becomes harder to reproduce because important agent settings are no longer visible in code review.

The second bad pattern is committing too much. People start placing keys, local provider endpoints, or one-off machine tweaks into shared files because there is no clear boundary between project config and runtime config.

APC and APX avoid both mistakes by naming the boundary directly.

The Portability Advantage

There is also a portability advantage here. APC does not need to know how APX stores sessions, messages, or caches. It only needs to preserve the project-owned facts another runtime could understand later.

A committed .apc/config.json is part of that project contract. Even if another APC-compatible runtime eventually reads only part of it, the repository still has a visible, reviewable source of truth for its intended behavior.

The Practical Thesis

If a setting describes how this repository should behave, put it in APC. If a setting describes your machine, your credentials, or your local runtime state, keep it in APX.

Portable context should travel. Private runtime state should not. Project config is one of the clearest places where that APC/APX boundary pays off every day.