Write a coding-agent command

A coding-agent definition is a literal command template. alterac.ai stores it as entered and supports the exact case-sensitive {alterac-ai-message} placeholder. The listener replaces it with the complete initial instruction only when it starts the queued run. Stored definitions, previews, queue snapshots, and approval prompts keep the text exactly as entered, including line breaks and backslashes.

To split a long command across lines, end each continued line with a backslash (\). This works the same on macOS, Linux, and Windows. This schematic example uses a placeholder program and option; use the names your installed program accepts:

coding-agent \
  --option value \
  "{alterac-ai-message}"

Immediately before opening a worker terminal, the listener joins each continued line into one space and trims leading and trailing whitespace, so the example runs as coding-agent --option value "...". Spaces or tabs around the trailing backslash and the next line's indentation are absorbed, and both LF and CRLF line endings work. Every other backslash is kept exactly as written, including Windows paths such as C:\tools\codex.exe and escaped quotes such as \".

A line break without a trailing backslash stops the run from launching. The listener reports the task number and keeps running other tasks. To fix it, end each continued line with a backslash, or put the command on one line, then update the coding-agent definition and requeue the task. Windows ^ and PowerShell backtick continuations are not supported.

Put the placeholder inside the complete initial prompt your coding-agent program expects. Quote that prompt according to the program and shell syntax. Example coding-agent commands owns the copyable Cursor, Codex, and Claude Code templates and their version-specific test evidence. Keep the quoted placeholder and flags as supplied when using a tested template; changed flags or selectors need their own verification.

At launch, the quoted token becomes an alterac.ai-owned message. The message directs the agent to read .alterac-ai/process.md before doing anything else, identifies the exact run with task-work-run-id=[00000000-0000-0000-0000-000000000000], tells the agent not to route that marker through another task system, includes the copyable command alterac-ai work-run get 00000000-0000-0000-0000-000000000000, and tells the agent to complete that exact run. The field's hint text explains this token-to-message boundary.

Do not place credentials, access tokens, API keys, passwords, or development-only API addresses in a template. alterac.ai does not parse shell syntax, escape arguments, or sandbox the launched program. Review the exact command and understand what it can access as your local user.

Provider permissions remain separate from alterac.ai listener trust. alterac.ai starts the configured process, but it does not approve the coding agent's tools, answer its prompts, or supervise its terminal interaction. Configure provider permissions for the repository and environment you are willing to expose.

The template is also checked for valid optional selector declarations. When a definition uses selectors, alterac.ai resolves the chosen values before queueing and snapshots that resolved command. Do not use a differently cased placeholder such as {Alterac-ai-message} and do not substitute a task number.

Use {Label:first option|second option} anywhere the selected command text belongs. alterac.ai recognizes it as a selector, shows the label and its options when someone queues the task, and replaces the declaration with the selected literal text. The first option is the default.

For example, the schematic command below adds a Mode selector. It defaults to careful, and the selected value becomes the text after --mode. Replace the placeholder program, option, and values with syntax your program accepts; this is a syntax illustration, not a verified provider command:

coding-agent --mode {Mode:careful|quick} "{alterac-ai-message}"

Give each selector a non-empty label and at least two pipe-separated options. Spaces around labels and options are trimmed; each resulting option must be distinct. An option can be blank when it intentionally removes an optional command fragment, for example {Sandbox:|--sandbox workspace-write}. Keep the declaration exactly where its resolved text is valid for your coding-agent program, and confirm the preview before queueing.

When you queue a task, alterac.ai stores the selected agent name and resolved command with that work run. The listener uses that immutable snapshot. Changing, disabling, hiding, or deleting the current catalog entry does not rewrite queued or historical commands.

Review command trust modes before approving a command, and use the local listener to understand how it starts it.