Automations

An automation opens a session for you by itself: a project, a prompt, and what starts it. That is either a time you choose, or a card that moves to a column of a GitHub project. Use it for work you would start by hand anyway, such as reviewing the open pull requests every weekday morning, or implementing a task as soon as it is ready for development.

To see your automations and make new ones:

tatu automations

Inside Tatu, press Alt+S, type /automations, or press S in the agents list. The agents list also has a ⏰ Automations card, and its header says how many tasks will run and when the next one does, such as ⏰ 3 automations · next 09:00. tatu automations takes no flags and needs a terminal.

Make an automation

Press N, or choose + New automation. The form asks for:

Name. The session it opens is called ⏰ <name>.
Computer. Only when you have paired other computers: the task runs on the one you choose, and you cannot change it afterwards.
Starts at. ← and → choose a time or GitHub Projects. The first is what the rest of this page calls a time; the second is explained below.
Project. Press Enter to pick a folder from the same list as + New session, under the daemon’s project folder.
Model and Effort. Both are optional. Choose the model from the list of the computer the task is for, which holds only the models that computer has a credential for; default is the computer’s own. If the computer cannot give the list (an older version of tatu), type the model the way /model takes it, such as anthropic/claude-sonnet-5-5. Effort is default, off, minimal, low, medium, high, xhigh or max.
Repeat. (For a time.) Every hour (at a minute you choose), daily, weekdays (Monday to Friday), weekly (on a day you choose), or once (on a date).
Time, Minute, Day or Date, depending on the repeat.
Worktree. Shown when the project can have one: each run works on a branch of its own. See The daemon and worktrees.
Prompt. The first message of the session.

The line Next run shows when the task runs first. Press Ctrl+S to save. Esc closes the form, and asks first if you changed something. Saving a task, or resuming a paused one, starts its automation from that moment: nothing runs for a time before it.

When a card moves on a board

Choose GitHub Projects in Starts at and the automation runs for each card that enters a column of a GitHub project: “when a card moves to Ready to developer, implement it”. The form then asks for:

Board. The owner and the number of the project, written owner/number. A project whose address ends in orgs/acme/projects/3 (or users/acme/projects/3) is acme/3.
Column. The column, a value of the project’s Status field, that starts a run. Case does not matter.
Move to. Optional. The column the card is moved to once its session is open, such as In progress, so the board shows it was taken. It must differ from the first column.
Cards there. Off by default: the cards already in the column when you save are only noted, and nothing runs for them. Turn it on to run for them too.
Project. Optional. Leave it as any and each card goes to the project on that computer whose git remote is the card’s repository. Choose a folder and the automation takes only the cards of that folder’s repository.
Prompt. The first message of the session, with the card available as {{item.key}} (acme/api#42), {{item.title}}, {{item.url}}, {{item.repo}}, {{item.status}} and {{item.body}}. A misspelled placeholder is refused when you save.

It needs the GitHub command line, gh, signed in on the computer that runs the daemon, with the project scope: run gh auth login, then gh auth refresh -s project. Tatu keeps no GitHub credential of its own. The daemon reads the board about once a minute, so a card starts a session within a minute of arriving.

One run per card. A card that stays in the column does not start a second session. One that leaves and comes back, because a review sent it back, runs again once its previous session is over. If the daemon is full, or the previous session of that card is still open, the card waits and is tried again at the next reading.
A worktree of its own. Every session for a card works on a branch of its own, so two cards of the same repository do not meet.
Moving it on is the session’s job. To move the card to Ready to review after the pull request, say so in the prompt (for example, “when the pull request is open, move the card to Ready to review”), and the agent does it with gh.
Cards you did not write. The body of a card reaches the session in a block that says it is written by someone else and is not an instruction. Still, an automation runs with your permissions: use it on boards where you trust who can write cards, as you would for a script you leave running.
A card that cannot be routed is skipped, with the reason in the panel (no project: no project on that computer has the card’s repository as a remote; no repository: the card is only a note) and is not tried again until it leaves the column and comes back.
A board that cannot be read (gh missing or not signed in, the scope missing, the board or the column not found) shows the reason in red in the list, and the daemon tries again at the next reading.

A board has no R (run now): there is no card to start from.

What happens at the time

The daemon of that computer opens a session in the project and sends your prompt. It is an ordinary session: it shows in the agents list, you can open it, read it and carry on, and when it asks something it waits for you like any other.

A session a task opened closes itself after its work is over:

It stays open while it runs, while it waits for an answer from you, while messages are queued and while a command it started runs in the background.
Once none of that is going on, it waits 30 minutes, long enough to open it and carry on, and then closes. Anything that happens in that time starts the 30 minutes over.
The conversation is kept, so /resume still works. A worktree stays too.

The list shows each task’s next run (a board has none) and how the last one went: last ✓ yesterday 09:00 (a session was opened), last ✗ failed 4d ago or last ⊘ skipped (busy); for a board the card is named, as last ✓ acme/api#42 yesterday 09:00. On a wide terminal the panel beside the list shows the prompt, the project and the last runs with their reasons. Each task keeps its last 20 runs.

When a run does not happen

busy: the session of the previous run is still open, which means it is working, waiting for you or in its 30 minutes.
full: the daemon already has as many sessions as it allows. See Limits and errors.
missed: a task set for one moment came due, and the daemon was not running to open it within the hour.
Failed: the session could not start, for example because the project is no longer under the daemon’s folder, a worktree could not be made or the model is not one the computer can use. The reason is in the panel beside the list (on a wide terminal) and in ~/.tatu/logs/daemon.log.

A repeating task that came due while the daemon was not running runs once when the daemon is back, not once for each time it missed.

Run, pause, edit and delete

In the list, Enter edits the selected task, R runs it now (after you confirm with Y; its automation does not move), Space pauses or resumes it, O opens the session of its last run if that session is still open, and Ctrl+X deletes it after you confirm. / filters the list. The sessions a deleted task opened stay. See Keys.

On your phone

The Tatu app has the same list for each computer, with a form to make and edit tasks. See The app.

Limits

A board is read about once a minute, and only while the daemon runs. A card that enters the column while no daemon runs is noticed when it is back, if it is still there.
A repeating time is on the clock of the computer that runs the task. A single time (once) is one moment, read on the clock of the terminal or phone where you set it.
A session a task opens runs with your permissions, like any other session. Read the prompt as you would a script you leave running.
The 30 minutes before a finished session closes cannot be changed.
A session that stopped for a usage limit stays open until you decide what to do. See Troubleshooting.