DEV Community: Agent Project Context

APX MCP Resolution Should Start With Runtime, Not Global Defaults

Manuel Bruña — Tue, 25 Aug 2026 12:04:13 +0000

APX MCP Resolution Should Start With Runtime, Not Global Defaults

When one MCP name exists in more than one place, APX should not guess.

It should prefer the most local, most operationally specific definition first.

That is why APX resolves MCP servers in this order: runtime, then shared, then foreign IDE configs, then global last.

This is not a small storage detail. It is one of the practical boundaries between APC and APX.

APC is the portable context layer. It keeps committed project context such as AGENTS.md, .apc/agents/, .apc/skills/, and .apc/mcps.json.

APX is the daily-use runtime and tooling layer. It decides what actually runs on one machine: CLI behavior, daemon state, local sessions, message logs, engines, MCP discovery, and runtime files under ~/.apx/.

MCP resolution belongs on the APX side.

Why `runtime` should win first

The core rule is documented directly in apx/src/core/mcp/sources.js.

That file defines three APX-owned writable scopes:

runtime: ~/.apx/projects/<apxId>/mcps.json
apc / shared: .apc/mcps.json
global: ~/.apx/mcps.json

It also defines the merge priority by name conflict:

runtime
apc
foreign IDE configs such as Claude, Cursor, VS Code, Roo, and Gemini
global

The code comment explains the reason in plain terms: per-project local secrets should win.

That is correct.

If the same MCP server name appears in both .apc/mcps.json and a machine-local runtime file, the runtime copy is usually the one that knows the real endpoint, token, or local command path for this machine right now.

A global fallback should not silently override that.

What APC should keep

APC should keep team-safe, durable MCP definitions.

For example, a repository can commit a shared MCP entry that tells collaborators which server name the project expects, whether it is stdio or HTTP, and which command shape or URL pattern belongs to the project.

That is project context.

It is reviewable, portable, and appropriate for .apc/mcps.json.

But APC should not try to own the last-mile operational truth for each laptop.

A token-bearing HTTP header, a user-specific local path, or a localhost port forwarded by one developer is not portable context. That belongs to APX runtime state.

What APX should keep

APX should keep the effective local override.

The same sources.js file writes runtime MCP state under ~/.apx/projects/<apxId>/mcps.json, and writeRuntimeMcps() protects that file with chmod 0600.

That is a strong signal about intended ownership.

Runtime scope is not just "another place to store MCPs." It is the place for MCP definitions that may carry secrets or machine-local details and must never leak into the repository.

That also matches the repo guidance in apx/AGENTS.md: tokens belong in runtime scope, not in committed APC files.

Why `global` should lose last

A machine-wide default is useful, but it should be a fallback, not a winner.

Suppose you use a github MCP server across many projects. A global definition in ~/.apx/mcps.json can save setup time.

But if one repository needs a different endpoint, different headers, or a safer project-local override, that repo should not have to fight the machine default.

Putting global last solves that.

The project can keep a shared .apc/mcps.json entry for collaborators, and one developer can still place a runtime override on top without changing committed project truth.

That is the useful split:

APC describes shared project intent.
APX resolves local operational reality.

The CLI reflects the same rule

The CLI in apx/src/interfaces/cli/commands/mcp.js exposes shared, runtime, global, and all as explicit scopes.

Read operations can inspect them all. Write operations default differently depending on context, but runtime remains first-class because APX expects real setups to need local overrides.

That matters for practical work.

If a team commits a safe shared MCP definition and one operator needs a secret-bearing variant, that operator can add it in runtime scope and APX will resolve that one first. No repo churn. No fake portability. No accidental secret commit.

Bigger lesson

Portable context becomes fragile when it tries to own machine-local execution details.

APC stays useful when committed files remain small, durable, and broadly true for anyone who clones the repo.

APX stays useful when it handles the messy part honestly: merge order, local secrets, active machine paths, and effective runtime resolution.

MCP resolution is where that philosophy becomes concrete.

So the rule should stay simple:

keep shared project-safe MCP definitions in APC
keep secret or machine-local overrides in APX runtime scope
let global act as fallback, not authority
resolve runtime first when names conflict

That keeps APC portable.

And it keeps APX trustworthy in daily use.

A Project Command Can Travel With APC. Its Execution Should Stay Local.

Manuel Bruña — Mon, 24 Aug 2026 12:03:13 +0000

A Project Command Can Travel With APC. Its Execution Should Stay Local.

A useful command definition is part of project context.

Its execution environment is not.

That is a small distinction, but it matters if you want APC and APX to stay clean.

APC is the portable context layer. It is where a repository can keep durable agent-facing files like AGENTS.md, .apc/agents/, .apc/skills/, and .apc/commands/.

APX is the daily-use runtime and tooling layer. It is what turns that context into real work on one machine: CLI sessions, web admin actions, Telegram turns, MCP calls, engines, and runtime state under ~/.apx/.

Project commands sit right on that boundary.

What should travel

A command body that explains a repeatable workflow belongs with the project.

For example, a repo might ship a markdown command in .apc/commands/release-checklist.md or .apc/commands/bug-triage.md.

That file is portable context. It tells any compatible tool, "when someone asks for this named workflow, here is the project-specific instruction body."

That is exactly the kind of thing APC should carry.

It is durable, reviewable, and tied to the repository rather than one operator's laptop.

What should not travel

The way that command gets resolved and executed should stay local.

APX's CLI code makes that boundary explicit.

apx command list and apx command show read markdown files from .apc/commands/, but they do not treat execution state as part of APC. First APX resolves which project you mean. In resolveCommandRoot(), it can use an explicit --project, the nearest APC root found from the current working directory, or a registered project path resolved through APX.

That path resolution is runtime behavior, not repository contract.

The project file travels.

The machine-specific answer to "which registered project does this command refer to right now?" does not.

That second part depends on local registration, current cwd, and APX runtime state.

Why this split matters

If you collapse those two layers, command systems get brittle fast.

One bad design is to store only runtime aliases and assume the command body lives in some hidden local database. Then the workflow stops being part of the project contract.

The opposite bad design is to push runtime details into APC, such as local execution history, channel bindings, machine-specific paths, or per-user resolution caches. Then the repository starts carrying private or unstable state it should never own.

The cleaner rule is simpler:

APC stores the command definition.
APX decides how to find the active project and run work from the current machine.

That keeps project intent portable without pretending execution context is portable too.

Practical example

The APX command implementation is deliberately modest.

listCommandFiles() scans .apc/commands/ for markdown files. cmdCommandShow() prints the requested file. And resolveProjectId() handles runtime-friendly lookup rules such as project id, exact path, exact name, fuzzy match, current APC root, or auto-registration.

That is a good division of labor.

The repository owns the workflow text.

APX owns the local question of which project instance the operator is currently talking about.

So if two developers clone the same repository, they can share the same command body through APC while APX still resolves each clone locally on each machine.

APC portable, APX practical

This is the deeper APC/APX pattern in miniature.

APC should carry durable project meaning.

APX should supply local resolution, execution, logging, and runtime coordination.

A project command can travel with the repo because the instruction body is part of project truth.

Its execution should stay local because runtimes, registrations, channels, and machine paths are not.

That separation is what keeps portable context useful instead of leaky.

A Visible Agent Name Should Not Double as the Agent Profile

Manuel Bruña — Sun, 23 Aug 2026 12:04:52 +0000

A Visible Agent Name Should Not Double as the Agent Profile

One easy way to make an agent system confusing is to let one label do two jobs.

In APX, the visible agent name and the active agent profile should stay separate.

That separation matters because APC and APX solve different problems.

APC is the portable context layer. It gives a project stable files like AGENTS.md, .apc/, agent definitions, skills, and other committed context that can travel with the repository.

APX is the daily-use runtime and tooling layer. It decides how that context runs on a real machine: CLI, web admin, Telegram, ACP, routines, direct engines, or external coding runtimes.

A display name belongs to the runtime identity side. A profile belongs to the runtime behavior side.

If you mix them, both become harder to trust.

What the repo already says

The APX codebase keeps this boundary explicit.

resolveAgentName() reads the super-agent display name from ~/.apx/identity.json, with a fallback to super_agent.name, then to "APX". That is the user-facing label.

The CLI help describes apx profile differently: it installs, activates, and configures the super-agent's "line of work," and says that with no profile active, APX behaves exactly as it always has.

Those are not the same concern.

One answers, "What do users see this agent called?"

The other answers, "What kind of work package is currently shaping the default runtime behavior?"

Why APC makes this easier

APC already keeps project agents separate from runtime identity.

A project agent in APC has a stable slug, role, model, and optional skills. That definition is part of the repository contract. It should not change just because someone wants the default APX assistant to appear as APX, Ops Desk, or another local name in Telegram or the web UI.

That is exactly why APC works as a portable layer: project truth can stay reviewable while runtime presentation stays local.

APX then adds its own runtime-only layer on top:

identity fields for how the default assistant presents itself
profiles for the default assistant's line of work
channels and routines that use those choices on the current machine

What goes wrong when the two collapse

If the visible name also selects behavior, small cosmetic changes become risky.

Imagine renaming the default assistant from APX to Release Desk because that reads better in Telegram. That should change the label users see. It should not silently install a release-management behavior package.

The inverse problem is just as bad.

If you activate a profile like secretary, APX should gain that workflow package without pretending the assistant's public name must also become Secretary on every surface. Otherwise a behavior switch leaks into UI identity, logs, and user expectations.

Keeping the two separate preserves a clean rule:

identity answers who the assistant appears to be
profile answers what line of work it is optimized for right now

Practical example

These two commands should remain independent:

apx identity show
apx profile use secretary

The first is about runtime identity.

The second is about runtime behavior.

Neither should rewrite APC project agent files, because APC owns project context, not local presentation choices for the default runtime assistant.

That is the deeper APC/APX split in miniature.

APC keeps portable project meaning in the repo.

APX keeps local execution choices flexible: display name, active profile, channels, engines, and surfaces.

Small design rule, big payoff

When an agent platform lets one field carry both identity and behavior, debugging gets harder fast.

Users stop knowing whether a rename changed branding, prompts, capabilities, or all three.

APX is stronger when it keeps those concerns apart.

Let APC describe project agents.

Let APX decide how the default assistant should appear today.

And let profiles shape runtime behavior without hijacking the assistant's visible name.

Use `apx exec` for Direct Reasoning. Use `apx run` for Real Work.

Manuel Bruña — Sat, 22 Aug 2026 12:04:28 +0000

Use `apx exec` for Direct Reasoning. Use `apx run` for Real Work.

A lot of confusion around APC and APX comes from two commands that both look like "run an agent," but do very different jobs.

apx exec calls an LLM directly inside APX.

apx run delegates the task to an external coding runtime such as Claude Code, Codex, OpenCode, Aider, Cursor Agent, Gemini CLI, or Qwen Code.

That distinction matters because APC and APX split responsibilities on purpose.

APC is the portable context layer. It keeps project truth in repository files like AGENTS.md, .apc/project.json, agent definitions, skills, and other committed context.

APX is the daily-use runtime and tooling layer. It decides how to execute that context today: direct engine call, external coding CLI, daemon route, web admin, Telegram, or another surface.

apx exec and apx run are one of the clearest examples of that boundary.

What `apx exec` really does

The APX docs define an engine as a direct LLM adapter inside APX. When you call apx exec, APX resolves the model, picks the matching engine, and makes the provider API call itself.

No external coding process is spawned.

That makes apx exec the right tool for things like:

quick questions
summaries
classification
small rewrites
one-shot analysis using APC context

Example:

apx exec -a reviewer "What are the riskiest changes in this PR?"

In that path, APX reads the APC agent definition, builds the system prompt, loads the agent memory it needs, and asks the configured model directly.

The response stays inside APX conversation storage.

What `apx run` really does

The runtimes docs define a runtime differently: it is an external AI coding CLI that APX can invoke headlessly on behalf of an agent.

So apx run is not just "exec, but bigger." It is a different execution lane.

Example:

apx run reviewer --runtime codex "Refactor parseAgentsMd to use a state machine" --timeout 600

Here APX still provides the same APC-based project context. It still reads the same agent definition and builds the same kind of system prompt. But instead of calling an internal engine, it spawns an external tool and records the session envelope around it.

That matters because the external runtime can do things apx exec should not pretend to do:

edit files
run shell commands
use its own coding workflow
keep its own native transcript

The APX docs describe this bluntly in the run vs. exec table: apx run is for full coding-agent capabilities, while apx exec is for quick one-shot reasoning.

Same APC context, different execution surface

This is the important design point.

The agent does not change just because the execution lane changes.

APC still owns the portable part: the agent role, instructions, project contract, and committed context.

APX owns the runtime choice.

That means you can keep one agent identity and switch execution style based on the task:

apx exec when you need judgment
apx run when you need action

That is a cleaner model than creating one "thinking agent" and one separate "coding agent" just because the tool path changed.

Practical rule

Use apx exec when the answer should come back as text and the job mostly fits inside one model call.

Use apx run when the job needs a real coding runtime with filesystem and terminal behavior.

A simple filter works well:

asking, comparing, summarizing, explaining: apx exec
editing, refactoring, reviewing live files, running commands: apx run

If you blur the two, you get bad expectations.

People ask apx exec to behave like a full coding CLI and wonder why it only answers.

Or they use apx run for tiny reasoning tasks and pay the overhead of spawning a whole external runtime for no reason.

Bigger APC/APX lesson

APC should describe what the project means.

APX should decide how that meaning gets executed on the current machine.

apx exec and apx run show that design in a very practical way.

Portable context stays stable.

Execution lane stays flexible.

So if you need one sentence to remember the split, use this:

APC keeps the agent portable. APX chooses whether that agent should think directly or act through a coding runtime.

If You Do Not Restart APX, You Are Testing Old Code

Manuel Bruña — Fri, 21 Aug 2026 12:03:28 +0000

If You Do Not Restart APX, You Are Testing Old Code

One of the most practical APX rules has nothing to do with prompts, models, or MCPs.

It is this: if you change APX code and do not restart the daemon before testing, you are usually testing the old runtime.

That sounds obvious. In practice, it causes a lot of false debugging.

APC and APX split responsibilities on purpose.

APC is the portable context layer. It keeps project truth in repository files such as AGENTS.md, .apc/project.json, agent definitions, skills, and other committed context.

APX is the daily-use runtime and tooling layer. It is the daemon, CLI, web admin, channel handling, sessions, message logs, and other machine-local state under ~/.apx/.

Because APX is a live runtime, code changes do not matter until the running daemon actually reloads them.

Why this matters

The APX project guide says it bluntly: skip restart and your test is a lie.

That is not style advice. The daemon keeps the JavaScript it booted with. Adapters, routes, prompt builders, and tool handlers all stay in memory until the process restarts.

So this sequence is broken:

edit APX code
run a manual check immediately
conclude the fix did not work
debug the wrong problem

The problem is often not the code. The problem is that the daemon is still serving the previous version.

What the docs and repo already say

The APX README describes APX as a daemon plus CLI plus web admin. The daemon starts on first use, and the browser UI talks to that same local process.

The APX repo guide goes further and turns that into a development rule:

know which checkout the daemon is running from
run apx restart after every code change and before manual testing
verify the restart actually happened
only then exercise the path you changed

That same guide warns about another easy mistake: the daemon runs from the main checkout, not from a random worktree. A fix committed somewhere the daemon never reads is not live, even if your branch looks correct.

Where APC fits

This restart rule also shows the APC/APX boundary clearly.

APC does not define a daemon. APC does not define process lifecycle. APC does not define how a local runtime reloads route handlers or tool wiring.

APC only defines portable project context.

APX owns the operational layer that makes that context usable today. The APC docs describe APX exactly that way: the reference runtime that keeps sessions, memory, and messages outside .apc/ under ~/.apx/, while the repository keeps the durable project contract.

So if APC answers, "What does this project mean?" APX answers, "What code is this machine actually running right now?"

Restart belongs on the APX side because live execution belongs on the APX side.

Practical loop

A safe APX edit loop is small:

apx restart
curl -s 127.0.0.1:7430/api/health
apx daemon logs --tail 30

Then test the exact path you changed.

changed a route: hit the route
changed agent or tool behavior: run apx exec or apx run
changed a web flow: restart first, then reload the browser and test end to end

That loop is boring, but it removes a whole class of fake failures.

Bigger lesson

A lot of agent-tool confusion comes from mixing portable context with live runtime behavior.

APC can be perfectly correct while APX is still running stale code.

Your repo may already contain the right project contract, agent files, and rules. But until the APX daemon reloads, the local runtime still reflects yesterday's process image.

That is why this rule matters so much.

Portable context tells every compatible tool what the project is.

APX restart makes sure the local runtime is actually using the code you just changed.

If you want one sentence to keep:

APC can stay stable in git, while APX must be restarted to make a code fix real.

A Channel That Does Not Log Is Invisible to APX

Manuel Bruña — Fri, 14 Aug 2026 12:02:52 +0000

A Channel That Does Not Log Is Invisible to APX

A runtime can claim it supports many surfaces, but that claim breaks fast if each surface keeps its own private history.

APX takes a stricter approach.

If a channel wants cross-channel continuity, it must log its turns into the shared runtime message store. If it does not log, APX cannot search it, retrieve it for memory, or hint that another thread is already active somewhere else.

That sounds like an implementation detail. It is not. It is a design rule.

APC and APX split responsibilities on purpose.

APC is the portable context layer. It keeps project truth in committed files like AGENTS.md, .apc/project.json, agent files, and skills.

APX is the runtime and tooling layer. It owns execution, sessions, channels, local memory, and message history under ~/.apx/.

That is why channel logs belong in APX, not APC.

One global place for cross-channel turns

The APX message store code documents two different lanes.

Project-specific runtime channels such as runtime, a2a, and exec live under:

~/.apx/projects/<project-id>/messages/YYYY-MM-DD.jsonl

Cross-project channels such as Telegram or other daemon-level surfaces live under:

~/.apx/messages/<channel>/YYYY-MM-DD.jsonl

The key function is appendGlobalMessage(). It writes one JSONL line per turn into ~/.apx/messages/<channel>/YYYY-MM-DD.jsonl.

That shared store is not just for archival.

In the APX project guide, the rule is explicit: the cross-channel message store is the spine. Every surface that wants to participate in shared awareness logs through that path. A channel that does not log is invisible cross-channel.

What APX gets from that rule

Three concrete features depend on this.

First, active thread awareness.

buildActiveThreadsBlock() reads recent turns from other channel folders under the global messages directory and injects a short block like “Recent chatter on other surfaces.” It skips the current channel, looks for recent meaningful turns, and tells the agent what may already be happening somewhere else.

That means a web conversation can notice that Telegram recently asked for a deploy, or a desktop voice session can notice that another surface already started the same task.

Second, retrieval.

The memory indexer walks ~/.apx/messages/<channel>/YYYY-MM-DD.jsonl for every channel, turns relevant records into chunks, and embeds them into the vector store. User and agent turns become retrievable context. Tool output can also be indexed in capped form.

No log, no chunk. No chunk, no recall.

Third, explicit search.

The search_messages tool resolves a project and runs full-text search over project messages so an agent can answer questions like “what did we decide yesterday?” without pretending to remember. Cross-channel awareness stays lightweight, while exact recovery stays searchable.

Why this should stay out of APC

It would be tempting to put all of this into the repository and call it “shared context.” That would be a mistake.

Raw channel traffic is runtime state. It can contain noise, private details, ephemeral commands, and local operational history. APC should stay portable, reviewable, and durable. It should not become a dumping ground for every chat surface.

So the boundary stays clean.

APC carries project contract.

APX carries live traffic.

Then APX can build useful runtime behavior on top: active thread hints, retrieval, search, compaction, and audit trails across surfaces.

That is deeper reason this logging rule matters.

Without one shared runtime log, “multi-channel” mostly means several disconnected inboxes.

With it, APX can treat channels as different entry points into one working system, while APC remains the portable layer that any compatible tool can read.

APX Web Features Should Reuse the Daemon, Not Fork the CLI

Manuel Bruña — Thu, 13 Aug 2026 12:04:44 +0000

APX Web Features Should Reuse the Daemon, Not Fork the CLI

A local web admin looks tempting: once you have buttons, tabs, and forms, it becomes easy to slip extra behavior into the browser and call it a feature.

APX explicitly rejects that path.

The rule in the APX project guide is blunt: the web is a GUI over the system, not a second implementation of the system. If a feature already exists in APX core or the daemon, the browser should call that. If it does not exist there yet, the answer is not to invent a web-only shortcut. The answer is to add the capability to the shared runtime first.

That design matters because APC and APX solve different problems.

APC is the portable context layer. It carries repository-owned truth such as AGENTS.md, .apc/project.json, agent files, skills, and other committed project context.

APX is the daily-use runtime and tooling layer. It runs the daemon, exposes the CLI and web admin, manages sessions, messages, routes, and local machine state under ~/.apx/.

Once you accept that split, the web admin has a clear job: present APX runtime capabilities in a browser without creating a parallel source of truth.

Same behavior, different surface

The APX architecture decision for core / host / interfaces makes this explicit.

core/ owns reusable logic
host/daemon/ exposes that logic over HTTP
interfaces/ are just surfaces such as CLI, web, desktop, or ACP

That is why the project guide also says: one domain function, one home.

If a behavior exists in both an API route and a CLI command, the logic belongs in core/, while the route and the command stay thin adapters.

The browser follows the same rule.

For example, the web hook useProjects() calls Projects.list(), and that client calls GET /projects. On the daemon side, src/host/daemon/api/projects.js answers that route by returning projects.list(). No browser-specific project registry exists. No duplicated model exists. The web surface asks the same runtime that the rest of APX uses.

That sounds small, but it prevents a lot of drift.

If the web panel kept its own project cache, project rules, or rebuild logic, it could slowly stop matching the CLI. Then users would have to ask a bad question: "which APX is correct, terminal or browser?"

A runtime should never force that question.

Why this protects APC too

The benefit is not only architectural neatness. It also protects APC.

APC works because the repository stays declarative and portable. Project context lives on disk in committed files that different tools can read.

If the web admin started adding browser-only behavior, hidden state, or mutations that bypass shared runtime logic, the practical contract would move away from APC files and into one surface. That would make the browser quietly more authoritative than the repo.

APX is supposed to do the opposite.

It should read APC, apply runtime rules, and expose those results consistently across surfaces.

So when the web panel fetches a bearer token and sends requests through src/interfaces/web/src/lib/http.ts, it is not becoming its own system. It is authenticating into the same daemon. When buildApi() mounts projects, agents, messages, routines, voice, desktop, and admin routes, the browser becomes one client among several, not a privileged fork.

Practical payoff

This rule makes daily work better in ordinary ways.

First, bugs get fixed once. If the daemon behavior changes, both CLI and web improve together.

Second, tests stay meaningful. APX project rules require behavior tests around shared functionality, not separate logic branches that only the browser understands.

Third, new surfaces stay easier to add. Desktop, ACP, CLI, and web can keep reusing the same APX runtime because the behavior lives underneath them.

That is the deeper APC/APX lesson.

APC should keep project truth portable.

APX should keep execution centralized.

And every surface, including the web admin, should stay honest about its role.

Not a second brain.

Not a forked implementation.

Just another window into the same runtime.

Use `apx setup` for Machine State. Use `apx init` for Project State.

Manuel Bruña — Wed, 12 Aug 2026 12:04:24 +0000

Use `apx setup` for Machine State. Use `apx init` for Project State.

A lot of confusion around APC and APX starts with two commands that look similar but do different jobs.

apx setup configures your machine.

apx init scaffolds your project.

That split is not cosmetic. It is one of the cleanest examples of the APC/APX boundary.

APC is the portable context layer. It defines project truth that should travel with the repository: AGENTS.md, .apc/project.json, agent files, skills, commands, and shared MCP hints.

APX is the daily-use runtime and tooling layer. It owns machine-local configuration, daemon behavior, runtime channels, engines, sessions, conversations, and message logs.

If you keep those two jobs separate, the system stays understandable.

What `apx setup` actually owns

The APX quick start and CLI docs describe apx setup as an interactive wizard for provider, model, channels, and daemon startup.

The implementation in src/interfaces/cli/commands/setup.js makes that concrete. The wizard asks for:

AI provider and model
optional API keys or Ollama base URL
Telegram bot settings
language
optional voice settings
optional Claude Code permission tweaks

Then it writes config to ~/.apx/config.json and starts the daemon.

That is machine state.

None of those choices belong in committed APC files by default. Your laptop may use Ollama. Another teammate may use OpenAI. One operator may wire Telegram. Another may not. Those differences are operational, not project truth.

So apx setup lives on the APX side because APX is supposed to own local runtime reality.

What `apx init` actually owns

apx init does almost the opposite job.

In src/interfaces/cli/commands/init.js, the command calls initApf() and reports the files it created. The scaffolding code in src/core/apc/scaffold.js creates AGENTS.md, .apc/, .apc/project.json, and the APC gitignore guard. It also generates the stable apx_id that links the committed project definition to runtime storage under ~/.apx/projects/<id>/.

That is project state.

It belongs in the repository because it describes the project, not one machine.

The APX docs say the same thing in plain language: the .apc/ tree holds committed project context, while ~/.apx/projects/<id>/ holds sessions, conversations, messages, caches, and other local runtime state.

That is the APC/APX contract in one sentence.

Why the distinction matters in practice

Imagine a fresh clone.

If a teammate gets the repo, they should inherit the project definition after checkout:

apx init --name "My Project"

That leaves durable context on disk in a form other tools can read too.

But the same teammate should not inherit your personal runtime choices just because they cloned your repo. They should choose those locally:

apx setup

That is why setup and init should not collapse into one command or one storage location.

If setup data leaks into APC, the repo starts carrying machine assumptions: provider keys, Telegram choices, localhost URLs, voice settings, or editor-specific permission tweaks.

If project scaffolding stays only in APX runtime state, the opposite problem appears: the repo stops being self-describing.

Both failures make APC less portable and APX harder to trust.

Useful mental model

Use this rule:

if the file should survive clone, review, and multi-tool use, it belongs in APC
if the setting depends on one machine, one operator, or one local runtime, it belongs in APX

That rule explains these two commands perfectly.

apx init creates the portable contract.

apx setup prepares the local executor.

One tells any compatible agent system what this project is.

The other tells APX how this machine should run it today.

Small detail that proves the design

apx init also detects scattered existing context and can write .apc/migrate.md when migration work is needed.

That only makes sense on the project side, because migration is about curating durable context into APC.

apx setup, by contrast, ends by saving local config and starting a local daemon.

That only makes sense on the runtime side.

The commands are different because the ownership is different.

Bigger lesson

APC and APX work well together when the repository stays declarative and the runtime stays operational.

APC should answer: what is this project, which agents exist here, and which committed rules travel with it?

APX should answer: how does this machine run those agents right now?

So if you are explaining the system to a new team member, keep it simple:

run apx init when you need project structure
run apx setup when you need local runtime configuration

Portable context first.

Machine-local execution second.

That is not just good CLI naming. It is the boundary that keeps APC portable and APX useful.

Auto-Registered MCP Servers Should Stay in APX Runtime, Not APC

Manuel Bruña — Tue, 11 Aug 2026 12:03:28 +0000

Auto-Registered MCP Servers Should Stay in APX Runtime, Not APC

An integration can expose an MCP server without meaning that server belongs in the repository.

That boundary matters more than it looks.

APC is the portable context layer. It keeps durable project meaning in committed files such as AGENTS.md, .apc/agents/, skills, and .apc/mcps.json. APX is the daily-use runtime and tooling layer. It owns machine-local state, plugin lifecycle, daemon behavior, and the MCP merge order that turns those files into something runnable.

Auto-registered MCP servers belong on the APX side.

Why this is the right boundary

A plugin-generated MCP definition often points at local facts: a vault path, a localhost endpoint, or a token-bearing environment variable. Those are operational details. They help one machine run a tool today, but they are not safe portable project truth.

APX's MCP source model makes that explicit.

In src/core/mcp/sources.js, APX defines three writable scopes:

shared in .apc/mcps.json for project-wide, committable MCP definitions
runtime in ~/.apx/projects/<apxId>/mcps.json for per-project local definitions, protected with chmod 0600
global in ~/.apx/mcps.json for machine-wide fallbacks

The same file also documents the merge order: runtime wins first, then project-shared APC entries, then foreign IDE configs, then global last.

That tells you what APC and APX each own.

APC can carry stable, reviewable MCP hints. APX decides which local definition actually runs on this machine.

What APX does with auto-MCP integrations

The clearest example is plugin sync.

In src/core/integrations/mcp-sync.js, APX maps integration scope to MCP scope with one deliberate rule:

integration global maps to MCP global
everything else maps to MCP runtime

The comment above that function explains why: auto-registered servers point at machine-local paths, so project integrations should become per-project runtime MCPs, not committed APC MCPs.

That same file says it directly: APX deliberately avoids the committed .apc/mcps.json scope for those generated servers.

That is a good design.

If APX wrote plugin-generated MCPs into .apc/mcps.json, one developer could accidentally commit a local vault path, a machine-only endpoint, or a secret-shaped environment contract into the repo. Another clone on another laptop would inherit a definition that looked official but was only true on the first machine.

That would weaken APC.

Practical example: Obsidian

Today the Obsidian integration is the concrete case.

APX documents an optional auto_mcp flow, and reconcilePluginMcp() keeps the MCP server in sync with the plugin lifecycle. When the integration becomes active, APX writes or updates the MCP definition in the runtime or global store, depending on the integration scope. When the integration is removed or disabled, APX removes the generated MCP there too.

That gives you the convenience people want from integrations without moving ownership into the wrong layer.

The repo can still keep a clean shared MCP file for team-safe tools. But a plugin that depends on one operator's local setup does not silently rewrite project truth.

This matches the CLI too

The CLI keeps the same idea.

In src/interfaces/cli/commands/mcp.js, write operations default to shared when you are inside an APC project and global outside one. But runtime is still a first-class explicit scope, and APX's own MCP skill docs say to use it for tokens and machine-specific endpoints.

That is the important nuance.

Human-authored MCPs can be shared when they are genuinely repo-safe. Auto-generated MCPs should be more conservative because they are derived from live runtime state.

So APX uses two different defaults for two different jobs:

manual project intent can go to APC shared scope
generated integration state stays runtime-local unless it is truly machine-wide

That split keeps convenience from turning into accidental portability.

Bigger lesson

Agent systems get messy when they commit outputs that were only valid as runtime side effects.

APC works best when committed files stay small, reviewable, and broadly true for everyone who clones the repo. APX works best when it handles the messy local part: plugin activation, machine-local files, tokens, and effective MCP resolution.

Auto-registered MCPs sit exactly on that seam.

So the rule should stay simple:

keep team-safe MCP definitions in .apc/mcps.json
keep token-bearing or local-path MCPs in APX runtime scope
let plugin lifecycle update runtime MCP state automatically
do not let generated local integrations rewrite committed project context

That is how APC stays portable and APX stays practical.

Portable context should describe the project.

Runtime-generated MCP servers should describe the machine currently running it.

Tool Catalogs Belong in APX Runtime, Not APC

Manuel Bruña — Mon, 10 Aug 2026 12:04:18 +0000

Tool Catalogs Belong in APX Runtime, Not APC

One easy way to bloat an agent system is to treat the tool catalog like portable project context.

That is the wrong boundary.

APC is the portable context layer. It carries durable project meaning through AGENTS.md, .apc/, skills, MCP hints, and other repo-owned artifacts. APX is the runtime and tooling layer. It decides what to execute, where to store local state, and which tools to expose on each surface.

The tool catalog belongs on the APX side.

That sounds small, but it matters a lot in daily use.

Why this boundary matters

A project contract should travel well. A runtime capability list should adapt to the moment.

Those are different jobs.

If you push a giant tool catalog into APC, every compatible runtime inherits a lot of operational detail that may be local, temporary, or channel-specific. That makes the portable layer noisier than it should be.

APX takes a better approach. In src/core/agent/tools/registry.js, the full tool schema set is commented as roughly 25 KB / ~6.3 K tokens. That is already large enough to dominate a lightweight turn. So APX does not send the whole catalog everywhere.

Instead, it keeps APC stable and lets runtime exposure stay dynamic.

What APX actually does

On lightweight channels, APX starts with a small base set of tools and reveals the rest on demand.

The code calls this BASE_TOOL_NAMES. It includes common things an agent often needs immediately: project and agent inventory, memory reads, session and message search, file reads and writes, basic shell access, tasks, skills, and discover_tools itself.

Everything else stays out of the first prompt.

That matters most on chat-like surfaces such as Telegram, desktop, and other lightweight channels where prompt budget is tighter and the user usually wants one small action, not a full coding cockpit.

Then APX adds a narrow expansion path: discover_tools().

That handler does two useful things:

with no arguments, it returns a grouped catalog of tools that exist but are not loaded yet
with category or exact names, it activates those tools for the next model step

So a lightweight agent does not need browser automation, fetch tools, runtime delegation, or voice tools on every turn. It can ask for them only when the task actually requires them.

Why this is better than a giant always-on list

The benefit is not only token savings.

It also improves separation of concerns.

APC says what the project is.
APX says what the runtime can do right now.

Those should not collapse into one file or one prompt blob.

A project may define agents, memory, commands, and MCP hints in a portable way. But whether a Telegram session should receive browser schemas up front is not a repository truth. It is a runtime decision.

APX makes that decision per channel.

In the same registry file, some channels deliberately get the full catalog up front: routine, api, web, code, and web_code. That also makes sense. If the user already chose a richer surface, APX can spend the budget there.

So the system stays practical in both directions:

portable context stays small and durable in APC
runtime capability exposure stays adaptive in APX

Practical example

Imagine a Telegram conversation with a project agent.

The user asks for a quick answer about current tasks. The base tool set is enough: list projects, inspect tasks, read memory, maybe search messages.

Later, the user asks the same agent to inspect a live website.

That is when discover_tools({ category: "browser" }) becomes useful. APX activates the browser tool group, merges those schemas into the next model step, and the agent continues with the richer capability set.

The repository did not change. APC did not get polluted. Only the runtime surface changed, which is exactly what should happen.

Bigger lesson

A lot of agent architectures become messy because they confuse durable context with executable capability.

APC and APX work better when those stay separate.

APC should carry the portable contract: agents, rules, memory worth committing, and machine-safe project facts.

APX should handle runtime mechanics: sessions, channels, prompt budget, local state, tool exposure, and dynamic activation.

Tool catalogs are runtime mechanics.

So the clean rule is simple:

Keep project meaning in APC.

Keep channel-specific tool exposure in APX.

When a surface needs more power, load more tools there. Do not turn the portable context layer into a giant runtime manifest.

Append-Only Project Notes Beat Copying Raw Sessions Into APC

Manuel Bruña — Sun, 09 Aug 2026 12:03:14 +0000

Append-Only Project Notes Beat Copying Raw Sessions Into APC

A project often needs one small thing after an agent session ends: a durable note. Not the whole transcript. Not private runtime memory. Just the part worth keeping.

That is why append-only project notes are a useful boundary between APC and APX.

APC is the portable context layer. It keeps durable project meaning in the repository through AGENTS.md, .apc/, agent files, skills, and other committed artifacts. APX is the daily-use runtime and tooling layer. It owns sessions, messages, conversations, caches, and machine-local state under ~/.apx/.

That split already appears clearly in the APC docs. Project context should survive changing editors, machines, or providers. Runtime state should not live in .apc/. Raw sessions, tool transcripts, and temporary notes stay local unless a human exports something useful back into the repo.

The missing question is: what should that exported thing look like?

A good answer is a small append-only note.

Why append-only helps

In APX, src/core/apc/notes.js writes project notes under .apc/notes/YYYY-MM-DD.md. It creates a timestamped markdown block and appends it to that day's file. No session dump. No database row. No generated identifier maze.

That shape is healthier than copying whole runtime history into APC.

If you push full transcripts into .apc/, three problems show up fast:

portable project context gets polluted with runtime noise
private or machine-local details become easier to commit by mistake
other tools inherit far more context than the project actually meant to share

An append-only note avoids that.

It is small enough to review, durable enough to keep, and simple enough that another APC-aware tool can ignore it safely if it does not support the extension.

That last point matters. APC portable core documents the canonical structure and explicitly says unknown paths under .apc/ should be ignored unless a formal extension defines them. So APX can add .apc/notes/ as a practical repo-owned lane without pretending raw runtime state now belongs in APC.

What APX actually stores

The implementation is intentionally boring, which is a good sign.

appendProjectNote(projectPath, { title, body }) creates .apc/notes/ if needed, chooses today's file, formats a markdown block with an ISO timestamp, and appends it. When a title exists, the block uses ## Title; otherwise it falls back to a timestamp heading.

On the daemon side, src/host/daemon/api/deck.js exposes POST /projects/:pid/notes. The route accepts body and optional title, trims them, rejects an empty body, and then writes through appendProjectNote.

That is a narrow bridge back into the repository:

APX runtime decides when a durable note is worth saving
APC project tree receives only the curated markdown artifact
raw session history remains in APX local storage

This is exactly the kind of boundary APC and APX need more often.

Why this is better than "memory everything"

Teams sometimes reach for one of two bad extremes.

The first is saving nothing, which forces every runtime to rediscover the same decisions. The second is saving everything, which turns portable context into a landfill.

Append-only project notes offer a middle path.

Use them for things like:

a decision the team wants visible in the repo
a short migration finding worth keeping
a constraint discovered during debugging
a follow-up instruction another runtime should see later

Do not use them for:

full chat transcripts
secret-bearing command output
temporary scratch reasoning
private operator notes that do not belong in version control

That distinction matches the APC docs closely: move back only useful, safe, durable project knowledge.

Practical takeaway

If APC is the portable context layer, it needs artifacts shaped for portability.

Raw sessions are not shaped for portability. Append-only project notes are much closer.

APX gets this right by keeping runtime state local while still providing a very small write-back path into the repo. That path is markdown, dated, reviewable, and easy to understand later.

So the rule is simple:

Keep sessions in APX.

Keep durable project notes in APC.

When something is worth preserving, append one small note instead of copying one giant conversation.

APX Agent Vault Should Reuse Agents Without Replacing APC

Manuel Bruña — Sat, 08 Aug 2026 12:03:39 +0000

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.

DEV Community: Agent Project Context

APX MCP Resolution Should Start With Runtime, Not Global Defaults

APX MCP Resolution Should Start With Runtime, Not Global Defaults

Why runtime should win first

What APC should keep

What APX should keep

Why global should lose last

The CLI reflects the same rule

Bigger lesson

A Project Command Can Travel With APC. Its Execution Should Stay Local.

A Project Command Can Travel With APC. Its Execution Should Stay Local.

What should travel

What should not travel

Why this split matters

Practical example

APC portable, APX practical

A Visible Agent Name Should Not Double as the Agent Profile

A Visible Agent Name Should Not Double as the Agent Profile

What the repo already says

Why APC makes this easier

What goes wrong when the two collapse

Practical example

Small design rule, big payoff

Use `apx exec` for Direct Reasoning. Use `apx run` for Real Work.

Use apx exec for Direct Reasoning. Use apx run for Real Work.

What apx exec really does

What apx run really does

Same APC context, different execution surface

Practical rule

Bigger APC/APX lesson

If You Do Not Restart APX, You Are Testing Old Code

If You Do Not Restart APX, You Are Testing Old Code

Why this matters

What the docs and repo already say

Where APC fits

Practical loop

Bigger lesson

A Channel That Does Not Log Is Invisible to APX

A Channel That Does Not Log Is Invisible to APX

One global place for cross-channel turns

What APX gets from that rule

Why this should stay out of APC

APX Web Features Should Reuse the Daemon, Not Fork the CLI

APX Web Features Should Reuse the Daemon, Not Fork the CLI

Same behavior, different surface

Why this protects APC too

Practical payoff

Use `apx setup` for Machine State. Use `apx init` for Project State.

Use apx setup for Machine State. Use apx init for Project State.

What apx setup actually owns

What apx init actually owns

Why the distinction matters in practice

Useful mental model

Small detail that proves the design

Bigger lesson

Auto-Registered MCP Servers Should Stay in APX Runtime, Not APC

Auto-Registered MCP Servers Should Stay in APX Runtime, Not APC

Why this is the right boundary

What APX does with auto-MCP integrations

Practical example: Obsidian

This matches the CLI too

Bigger lesson

Tool Catalogs Belong in APX Runtime, Not APC

Tool Catalogs Belong in APX Runtime, Not APC

Why this boundary matters

What APX actually does

Why this is better than a giant always-on list

Practical example

Bigger lesson

Append-Only Project Notes Beat Copying Raw Sessions Into APC

Append-Only Project Notes Beat Copying Raw Sessions Into APC

Why append-only helps

What APX actually stores

Why this is better than "memory everything"

Practical takeaway

APX Agent Vault Should Reuse Agents Without Replacing APC

APX Agent Vault Should Reuse Agents Without Replacing APC

What the vault actually is

What should stay in APC

The practical workflow that keeps both layers clean

Why `runtime` should win first

Why `global` should lose last

Use `apx exec` for Direct Reasoning. Use `apx run` for Real Work.

What `apx exec` really does

What `apx run` really does

Use `apx setup` for Machine State. Use `apx init` for Project State.

What `apx setup` actually owns

What `apx init` actually owns