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.