Agent Slugs Are the Smallest Handoff Key Between APC and APX

A lot of APC and APX discussion happens at the level of folders, memory, or runtimes. But there is a smaller boundary that matters every day: the agent slug.

APC is the portable context layer. It keeps the project contract in the repository: AGENTS.md, .apc/project.json, .apc/agents/<slug>.md, skills, commands, and curated memory that is safe to share. APX is the daily-use runtime and tooling layer. It reads that contract, runs agents, stores local runtime state under ~/.apx/, and gives you CLI, daemon, and web admin workflows.

The slug is where those two layers meet.

In APC, the slug identifies the structured agent definition. In APX, the same slug becomes the routing key for commands like apx run <slug>, apx exec -a <slug>, apx memory <slug>, and apx session new <slug>. APX also uses it to place runtime files under per-agent paths such as ~/.apx/projects/<project-id>/agents/<slug>/sessions.

That sounds small, but it solves a real design problem: how do you keep a portable project contract and a local runtime aligned without inventing hidden IDs for every agent?

The answer is not to make the runtime smarter. The answer is to keep the join key boring.

Why this matters

If the shared name for an agent is unstable, everything around it gets noisy.

• Session history stops feeling continuous.
• Runtime memory becomes harder to inspect.
• Telegram routing, CLI commands, and follow-up sessions become less predictable.
• Teams start treating agent definitions like disposable prompts instead of durable project roles.

A stable slug avoids that.

For example, if a repository defines .apc/agents/reviewer.md, APX can keep using reviewer everywhere:

apx run reviewer --runtime claude-code "Review the open PRs"
apx exec -a reviewer "Summarize test risk"
apx memory reviewer
apx session new reviewer --title "Follow-up audit"

That is a better contract than a display name. You can rename a role description, change the model, or expand the skills list, and the runtime history still lands under the same agent lane.

What should stay stable

The slug should describe the durable responsibility, not the mood of the prompt.

Good slugs:

• reviewer
• planner
• backend
• release-manager

Weak slugs:

• smart-reviewer-v2
• best-agent-final
• claude-helper
• telegram-reviewer-temporary

Those weaker names leak implementation details into the project contract. They age badly when you switch models, channels, or runtimes. APC should describe the project role. APX should decide how that role runs today.

APC side, APX side

APC keeps the definition portable:

• AGENTS.md holds repository-wide rules.
• .apc/agents/<slug>.md holds the structured agent definition.
• .apc/agents/<slug>/memory.md can hold curated, team-safe memory.

APX keeps the runtime local:

• sessions
• conversations
• message logs
• runtime memory and caches

That split only stays clean if both sides can point to the same agent identity without translation glue. The slug is enough.

This is also why APX does not need a second hidden naming system for normal agent work. The portable name from APC already gives the runtime a stable filesystem lane, command target, and audit trail anchor.

Practical rule

Pick slugs like you would pick API names.

• Stable over clever
• Role-based over model-based
• Short over decorative
• Reusable over temporary

If you need to change how an agent behaves, edit the definition. If you need a different responsibility, create another slug.

That keeps APC readable in the repo and APX readable on disk.

The bigger APC/APX idea is often described as portable context plus local runtime. That is true. But in daily use, the smallest piece doing real work is often just one good slug.