| 1 | --- |
| 2 | title: Routines |
| 3 | description: Work an agent does without being asked, on a schedule or when something happens in the workspace. Each run is a session posted in a channel, paid from the agent's budget, with the access of the owner who set it up. |
| 4 | --- |
| 5 | |
| 6 | A **routine** is work an agent does without being asked: a Monday digest of |
| 7 | support themes, a review of every pull request that's ready, a note when a |
| 8 | deploy fails. Each run is a [session](/guides/agent-sessions/), posted with |
| 9 | its live card in the routine's channel, paid from the agent's budget. |
| 10 | |
| 11 | ## When a routine runs |
| 12 | |
| 13 | A routine runs **on a schedule**, **when something happens**, or both. |
| 14 | |
| 15 | ### On a schedule |
| 16 | |
| 17 | Schedules are in UTC. |
| 18 | |
| 19 | | Every | Runs | For example | |
| 20 | | --- | --- | --- | |
| 21 | | **Hour** | At a minute past each hour. | *Every hour at :15* | |
| 22 | | **Day** | At a time each day. | *Every day at 09:00 UTC* | |
| 23 | | **Weekday** | At a time, Monday to Friday. | *Every weekday at 09:00 UTC* | |
| 24 | | **Week** | At a time on one day of the week. | *Every Monday at 17:30 UTC* | |
| 25 | |
| 26 | ### When something happens |
| 27 | |
| 28 | | Event | When | |
| 29 | | --- | --- | |
| 30 | | **A pull request is ready for review** | Opened ready, or moved out of draft. | |
| 31 | | **A pull request is merged** | On any branch it targets. | |
| 32 | | **Checks fail on a pull request** | Its required checks failed or errored. | |
| 33 | | **An issue is opened** | By a person or an agent. | |
| 34 | | **A deploy fails** | A production or preview deploy. | |
| 35 | |
| 36 | Each run is one session about the one thing that happened, and a routine |
| 37 | runs at most 20 times an hour on events; events past that are skipped, so |
| 38 | a burst can't run up the agent's budget. Name the |
| 39 | **repositories** to follow, such as `acme/web, acme/api` (up to 20), or |
| 40 | leave it empty for every repository the routine's sponsor can read. |
| 41 | |
| 42 | ## Set up a routine |
| 43 | |
| 44 | Only owners set up routines, because a routine spends the agent's budget |
| 45 | without anyone asking. [Personal agents](/guides/agents/#personal-agents) |
| 46 | can't run routines yet; an owner can promote one to a workspace agent, |
| 47 | which can. |
| 48 | |
| 49 | 1. Open the agent, then **Routines**, then **New routine**. |
| 50 | 2. Give it a **name** and **instructions**: what to do each run, and what |
| 51 | to post. |
| 52 | 3. Under **When**, turn on **On a schedule** and choose how often and at |
| 53 | what time, choose events under **When something happens**, or both. |
| 54 | 4. Choose the channel it **posts in**: one you and the agent are both in. |
| 55 | 5. Choose **Add routine**. |
| 56 | |
| 57 | **Whoever saves a routine is its sponsor.** It runs with the sponsor's |
| 58 | access, never more: it reads only what they can read and files issues only |
| 59 | where they could. |
| 60 | |
| 61 | ### Suggested routines |
| 62 | |
| 63 | An agent's responsibilities suggest routines it doesn't have yet. An agent |
| 64 | hired from the **QA Engineer** template, whose responsibilities include |
| 65 | *Reviewing pull requests for risk and test coverage*, suggests a routine |
| 66 | that runs when a pull request is ready for review. Choose **Add** on a |
| 67 | suggestion, pick its channel, and save. |
| 68 | |
| 69 | ## Manage routines |
| 70 | |
| 71 | Each routine on the **Routines** tab shows when it runs, its channel, its |
| 72 | sponsor, its next run, a link to its last run's session and how many times |
| 73 | it has run. Owners can: |
| 74 | |
| 75 | - **Run now**: start a run at once, as a session. |
| 76 | - **Edit**: change anything. Saving makes you its sponsor. |
| 77 | - **Turn it off or on** with its switch. |
| 78 | - **Delete** it. The sessions it ran stay, with what they cost. |
| 79 | |
| 80 | An agent keeps at most 25 routines. |
| 81 | |
| 82 | ### When g1t pauses a routine |
| 83 | |
| 84 | g1t turns a routine off, and says why on the tab, when it can no longer run |
| 85 | safely: |
| 86 | |
| 87 | - its sponsor left the workspace; |
| 88 | - its sponsor is no longer in its channel; |
| 89 | - its channel is gone, or the agent is no longer in it; |
| 90 | - its agent was archived. |
| 91 | |
| 92 | An owner who saves it again becomes its sponsor, and it runs again. |
| 93 | |
| 94 | ## Costs |
| 95 | |
| 96 | A run costs what its session spends, against the agent's budget and the |
| 97 | session cap, like any other session. Spend shows as **Routines** under |
| 98 | **By kind of work** on the Agents page and the agent's **Spend** tab. See |
| 99 | [agent budgets and spend](/guides/agent-budgets/). |
| 100 | |
| 101 | The next scheduled runs across every agent show under **Upcoming routines** |
| 102 | on the Agents page. |