Guides

Run a task

Not every job is an issue or a PR. Dispatch a one-off agent task — a quick change, a question about the code, a small refactor — outside the GitHub workflow. Start it from the CLI or the dashboard Dispatch view; it runs in the background and you poll for the result.

A task is a single claude run against a directory. Unlike the workflows, it isn't tied to an issue or PR and doesn't open one — it's the right tool for ad-hoc work and exploration.

Run a task from the CLI#

Give it a prompt. Add --watch to stream the run and print the result, turn count, and cost when it finishes. A task can just answer a question — no files changed:

bash

moa run "find the best open-source AI agent projects and summarize them for me" --watch

text

task tk_4f8a · running
done · 4 turns · $0.03
→ a ranked shortlist, with a one-line "best for" on each

By default the task runs in your task workspace on the server; pass --dir <path> to target a specific directory there.

Run a task from the dashboard#

Open the Dispatch view, write the prompt, pick the target, and run. You'll get the same background task with a live view — handy when you'd rather watch it than tail a terminal.

Track and cancel tasks#

Tasks are asynchronous: they move through queued → running → succeeded | failed | canceled. Each is one agent process, so canceling kills it.

bash

moa task list           # recent tasks and their state
moa task get <id>       # result, turns, cost for one task
moa task cancel <id>    # stop a running task

Note.Every run has a hard spend cap and a timeout — a task that crosses either is canceled automatically, so an open-ended prompt can't run away with cost.

When to run a task vs. a workflow#

Run a task for ad-hoc work — a quick edit, a code question, a scratch experiment — where you don't want a branch or a PR.
Use a workflow when the job is an issue or PR and you want the full safe loop — branch, verify-gate, PR, review, merge.

Note.Full flags for moa run and moa task are in the CLI reference.