APX Routines: Use exec_agent for Text, super_agent for Work

The most useful APX routine decision is also the simplest one: pick exec_agent when you want a model to write text, and pick super_agent when the routine must actually do work.

That line sounds small, but it is the difference between a clean automation and a messy one. APX routines sit on top of APC project context, so the project contract stays portable in .apc/, while the runtime decides how much power a scheduled task really needs.

What a routine is

A routine is scheduled work that the APX daemon runs on a timer. The docs keep the model small and explicit:

• heartbeat for a simple marker
• shell for plain commands
• exec_agent for one LLM call, no tools
• super_agent for a full tool loop
• telegram for a fixed message

That split is the right kind of boring. It forces the author to say what kind of job they are scheduling instead of hiding everything behind one vague “agent” button.

exec_agent: when the output is the product

Use exec_agent when the routine should return prose, a summary, a digest, or another piece of text that a human or another command will consume.

Good fits:

• daily status summaries
• morning task digests
• changelog drafts
• short Telegram updates
• email-ready text
• any workflow where the model should speak, not operate

The key property is that exec_agent makes one model call. No tool loop, no hidden side effects, no wandering across MCP servers.

That is a good default when the job is basically “read some context, then write a paragraph.”

super_agent: when the routine must act

Use super_agent when the routine must do more than write text.

Good fits:

• inspect files and then edit them
• call MCP tools
• create tasks
• send dynamic Telegram messages
• combine several steps with decision points
• gather inputs from the project and then take action

super_agent is APX itself in a loop. It gets the full tool registry, so it can orchestrate work instead of only describing it.

That power is useful, but it costs more complexity. If the routine only needs a sentence, giving it tool access is overkill.

The clean rule

Here is the rule I use:

• If the result is plain text, choose exec_agent.
• If the routine must interact with tools, choose super_agent.
• If the task is pure shell, use shell.
• If the message is fixed, use telegram.

APC matters here because the routine still reads project context from the repo. APX only decides how to execute it.

That separation keeps the project contract portable and the runtime opinionated.

The double-message trap

One common mistake is mixing super_agent with a post_commands step that also sends Telegram.

That can produce two messages:

• one from the agent's own send_telegram tool call
• one from the shell post step

APX has suppression logic to reduce the damage, but the clean design is still simpler: let exec_agent write the message, then let the post command send it once.

That is the right pattern for scheduled notifications:

apx routine add daily-summary \
  --project my-app \
  --kind exec_agent \
  --schedule "every:24h" \
  --spec '{"agent":"default","prompt":"Summarize today\'s changes in one short paragraph."}' \
  --post-commands 'apx telegram send "$APX_LLM_OUTPUT"'

If the routine needs tool access later, switch to super_agent on purpose. Do not start there by habit.

Why this keeps APX useful

APX is the daily-use runtime layer for APC. That means it should turn project context into concrete behavior without making every automation feel like a mini product.

The routine model does that well:

• APC stores the project contract.
• APX stores the runtime state.
• routines decide schedule and execution style.
• the agent kind decides whether the job is text or action.

That gives you enough structure to automate real work without losing control.

Practical takeaway

If you are building a scheduled workflow in APX, start with this sequence:

1. Ask whether the routine only needs text.
2. If yes, use exec_agent.
3. If no, use super_agent.
4. Keep shell for shell jobs.
5. Keep telegram for fixed messages.

That choice removes a lot of accidental complexity.

And that is the deeper point: the best automation is not the most powerful one. It is the one that uses just enough runtime for the job.

APC keeps the context portable. APX keeps the action local. Routines sit exactly in that boundary, which is why they work.