Configure coding agents
Write a coding-agent command
Write and validate a literal coding-agent command template that receives the exact queued work-run identifier.
A coding-agent definition is a literal command template. alterac.ai stores it as entered and requires the exact case-sensitive {task-work-run-id} placeholder at least once. The listener replaces each occurrence with a labeled work-run ID only when it starts the queued run.
Put the placeholder inside the complete initial prompt your coding-agent program expects. Quote that prompt according to the program and shell syntax. For the currently documented providers, use the command form that starts each program with an initial prompt:
For Codex:
codex "Please complete {task-work-run-id}"
For Claude Code:
claude "Please complete {task-work-run-id}"
At launch, the quoted prompt becomes a value like "Please complete task-work-run-id=[00000000-0000-0000-0000-000000000000]". The placeholder is not a task number and is not replaced while you edit or preview the definition.
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.
| Field | Requirement |
|---|---|
| Name | Required; up to 128 characters |
| Description | Optional; up to 1,024 characters |
| Command template | Required; up to 4,096 characters and includes {task-work-run-id} |
| Enabled | Enabled entries can be selected for new work; disabled entries stay stored |
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 {Task-work-run-id} 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, this Codex command adds an Effort selector. It defaults to xhigh, and the selected value is passed as the model_reasoning_effort configuration value:
codex --config model_reasoning_effort={Effort:xhigh|high|medium|low|minimal} "Please complete {task-work-run-id}"
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.