Run the local task listener

Run the listener from an initialized repository to start approved queued work for that repository's selected project. It uses your existing coding-agent installation and does not execute work in an alterac.ai-hosted sandbox.

1. In the repository directory that contains the configured .alterac-ai folder, confirm your coding-agent program is installed and authenticated.
2. Start the listener:

alterac-ai listen

3. Keep the terminal open. The listener checks for work every five seconds by default and shows a waiting status when none is queued. Stop it with Ctrl+C.
4. When it displays an approval prompt, compare the incoming command with any previous command shown. Approve it only when it is expected, or defer it to keep the task queued.

You can run more than one listener, including listeners for different configured projects. Each process is reported separately; duplicate listeners for the same project can compete to start eligible queued runs, but a run is started only once.

After approval, the listener replaces {alterac-ai-message} with a complete instruction that identifies the exact alterac.ai work run, routes the coding agent through .alterac-ai/process.md before implementation, tells it not to use another task system for the marker, supplies the exact work-run retrieval command, and tells it to complete that run. It then marks the run started and opens the selected coding-agent command in a separate terminal when the operating system supports it. The worker terminal owns its output, errors, and interaction. The listener does not capture, replay, or upload that output.

If the listener cannot open a worker terminal, it prints the complete platform-safe rendered command. Run that exact command in a terminal from the repository directory to continue. On macOS and Linux, the printed backslashes protect the launch message's visible command backticks from shell substitution. Do not remove them or edit the launch message or labeled work-run ID.

• The listener is waiting for your first or changed-command approval.
• You deferred the command.
• No listener is running from a repository configured for the task's project.

Queued work uses an immutable snapshot of the selected coding-agent name and resolved command. Later catalog edits, disabling, hiding, or deletion do not change that queued run. Requeue the task to use a newly edited definition.

Update the CLI before queueing a definition that uses {alterac-ai-message}. An older CLI does not know how to expand that token and will stop before it starts the run. If the listener reports that a queued snapshot has no required alterac.ai launch placeholder, update the definition with the current token and requeue the task.

If the listener has already approved and started a run but cannot open a worker terminal, it prints the command for manual launch and the task is already Agent working. Likewise, a program that is missing or not authenticated can fail only after the listener starts the run. You can run the printed command after resolving the local problem, or use Recover agent work on the Agent-working task details to replace the incomplete run. The same recovery section remains available if the agent later stops or finishes without submitting its work, or if you moved the task directly to Agent working without creating a run, regardless of current listener presence.

Use alterac-ai config trust to check the local approval mode, then restart alterac-ai listen from the configured repository. If a terminal launch failed, use the listener's printed command manually after you have reviewed it. For the exact placeholder and snapshot behavior, see Write a coding-agent command. For the approval rules, see Choose a command trust mode.