How tasks work
A task is the unit of work in Jaah. You describe what you want in plain words. Jaah hands it to a runner, an AI agent that does the work in your project's code, and the result comes back to the task. Everything Jaah does for you, from a one-line fix to a large feature, is a task or a group of tasks.
This page explains the ideas behind tasks. For the steps, see Start a task and Stop, restart or reset a task. For every control on the screen, see Tasks.
Terms
| Term | Meaning |
|---|---|
| Task | One piece of work: a description, its settings, and everything that happened while it was worked on. |
| Runner | The AI agent that works on a task. It runs on one of your organization's machines, called nodes, in its own copy of the project's repository, called a worktree. |
| Persona | The kind of expert a runner acts as, such as Coder or Researcher. It decides how the runner works and what it hands back. |
| Project | The repository a task works on. Every task belongs to one project. |
| Feature | A folder for related tasks inside a project. Optional. |
| Epic | A large task that Jaah splits into subtasks and runs in stages. |
| Subtask | A task that belongs to an epic. |
| Prerequisite | A task that must finish before another one can start. |
| Attempt | One run of a task. A task that fails is tried again, up to a limit. |
Where a task belongs
- Project. A task always belongs to one project, and works in that project's repository. Your access to the project decides whether you can see the task and whether you can start or stop it. See Projects.
- Feature. Inside a project, you can file related tasks under a feature to keep them together. Select a feature in the sidebar to see only its tasks.
- Epic. A task started as an Epic is not worked on directly. Jaah splits it into subtasks, shown under it on the board, and the epic's state follows theirs. Its subtasks move through stages, each with its own persona: Analyze (pin down the requirements), Design (choose the approach), Plan (split the work), one Coder subtask per piece of work, and Finish (check the result as a whole). See Personas.
- Prerequisites. A task can depend on other tasks. It waits until each prerequisite is done before it starts. You add them under Advanced when you start a task.
Who works on it
When a task starts, Jaah picks a node with a free worktree for the project and launches a runner there. The runner reads the task's description, works in the worktree, and reports back. A worktree stays with its task until the task finishes, is reset or is deleted, so a task you stop and start again carries on with the work it already had. See Worktrees and Nodes.
The runner uses one of your organization's model accounts to reach the AI model. What its runs cost is shown on the task's row and on its Details tab. See Model accounts.
How much the runner asks you depends on the involvement you chose when you started the task:
- Unattended — the runner decides everything itself.
- Guided — the runner asks you before key decisions.
- Chat — a conversation with an advisor, who talks it through with you in the console. A chat stays open until you select Complete.
Even an Unattended task can stop to ask when it needs something only a person can give it, such as access to a system. See Answer a task's question.
What a task produces
What comes back depends on the persona:
- A merged change. A Coder task changes the project's code and delivers it as a pull request that's merged into the project. The task is Done once the change is merged.
- An outcome. Every runner ends with a short summary of what it did, shown as Outcome on the Details tab, with a link to the merged change when there is one.
- Artifacts. Files the task produced, such as its report or a mockup, on the Artifacts tab.
- A finding that no change is needed. A runner that finds the work is already done ends without a change and says why in its outcome.
The lifecycle
A task moves through these states. The board groups them into sections: Draft, In progress, Stopped and Done.
| State | Section | What it means | What moves it on |
|---|---|---|---|
| Draft | Draft | Saved, not started. | You select Start or Go. |
| Queued | In progress | Started, waiting for a free worktree. | Jaah dispatches it. |
| Waiting | In progress | Waiting on something before it can run, such as a prerequisite that isn't done yet. | The thing it waits on is ready. |
| Held | In progress | An epic that runs only the subtasks you start by hand. | You select Start on a subtask; the epic stays Held. |
| Starting | In progress | A runner is being launched. | The runner starts. |
| Running | In progress | A runner is working on it. | The runner finishes, asks, or fails. |
| Asking | Stopped | The runner needs your answer to go on. | You answer. |
| Delivering | In progress | Your answer is on its way to the runner. | The runner resumes. |
| Paused | Stopped | Stopped by hand, parked waiting on a customer, or paused by Jaah because your Jaah balance ran out. Its work is kept. | You select Start. A task Jaah paused resumes by itself once the balance is back. |
| Failed | Stopped | Every attempt failed. | You select Start or Reset. |
| Done | Done | Finished. | You select Start to run it again. |
The usual path is Draft → Queued → Starting → Running → Done, with a stop at Asking whenever the runner needs you.
When a run fails
A run can fail: the runner hits an error, the model account runs out, or the machine goes away. A failed run uses one attempt, and the task is queued again automatically. Only when it has used all its attempts does it stop as Failed. Nothing retries a Failed task: it waits for you. Read its Outcome and Activity, then start it again or reset it.
Stop, reset and complete
You can change a task's course at any time from its ⋯ menu:
- Stop pauses it. The work so far is kept, and Start carries on from there.
- Reset returns it to a clean Draft. The runner is stopped, its questions, report and outcome stop being shown, and work it hadn't delivered is discarded. The description and attachments stay.
- Complete marks it Done by hand.
A task never becomes final on its own: a Done task can be started again, and a task you stopped waits until you act. How to do each of these is in Stop, restart or reset a task.
Who can do what
What you can do with a task depends on your access, set by your organization's admin:
- Seeing tasks needs access to the task board and to the task's project.
- Creating tasks needs the create-tasks permission.
- Starting, stopping, resetting and completing a task needs edit access to its project.
A control you don't have access to isn't shown. See Groups for how access is granted.
Related concepts
- How epics and features work — large tasks split into subtasks and run in stages.
- How personas and playbooks work — the kind of expert that runs a task.
- How chat works — a task that is a conversation with an advisor.
- How worktrees work and How nodes work — where a runner does its work.
- How projects work — the repository every task belongs to.