Run work unattended with memo auto-run
Habits that make memo auto-run work through a pile of items without you watching each one. They come from running it for a while, and are one way to do it, not the only one. Every screen and every state is in Run memos automatically. This page says what to write and how to set it up, and links there for the rest.
How it works
Section titled “How it works”| What you do | What the agent does |
|---|---|
| Keep the detailed procedure in the repository, and write a short standing instruction that points at it | Reads the instruction when the session starts, then follows the procedure it points at |
| Write one memo per work item, with its scope and what is out of scope | Takes the memos waiting to run in order, as many per run as “Memos per session” says |
| Put what is left of a large task on the issue, and cap how many parts it may queue | Does one part, records the rest, and ends |
| Read the run history, approve what sessions add, end a run that hangs | Ends the run when its session has nothing left to wait for, and stops the session |
Choose auto-run
Section titled “Choose auto-run”| For this | Use |
|---|---|
| Items that pile up, each done by following the same instruction | Memo auto-run |
| The same prompt at set times | A schedule |
| Splitting one task you are watching into parts | Child sessions |
| Steering several sessions through chat, with you deciding along the way | The Fleet Operator |
Auto-run suits work that is small enough to finish in one run and clear enough to need no answer from you on the way. When most items need a person’s decision, it only moves the waiting around.
First setup
Section titled “First setup”- Write a short instruction (next section) and save the settings with “Run by itself” off. Saving starts nothing
- Add one or two memos you are sure about
- Press “Run now” once, and read the session and the result
- Fix the instruction, then run once more if you changed it much
- Turn “Run by itself” on
Decide these fields before you do (the fields):
| Field | A starting point |
|---|---|
| Spend limit (USD) | Set a number. 0 means no limit, and nothing else bounds a run that goes wrong (budget) |
| Memos per session | Set 1, so one run is one work item and one pull request to review. At 2 or more, a run takes several memos and the separation this page relies on is lost |
| Sessions at the same time | Start at 1 or 2. A category allows at most 6 open runs, and all your auto-run categories together at most 4 |
| Runs per day | A little above what you expect. It holds back a runaway |
| When it runs | “In a time window” when you want runs only while you are away, or when the host is quiet |
| Follow-ups a run may add without approval | Leave 4 for a task done in parts, 0 where no run should add memos unseen (follow-ups) |
| Accept notes from sessions I started without approval | Leave it off until you have read a few memos sessions added (approval) |
A memo a session adds waits for your approval. The one memo a run adds without it is a follow-up of the memo it was given, for the same work item and within the category’s number (follow-ups). Read the memos on the approval card as instructions to the next session, because that is what they become (Approve).
Write the standing instruction for nobody watching
Section titled “Write the standing instruction for nobody watching”Keep the instruction short, and keep the procedure in the repository. A skill or an instructions file in the repository is versioned, reviewed and shared. The instruction says which one to follow:
Follow <the skill or file that holds the procedure> for each memo.Work only in this repository. Work on one memo's item and nothing else.Open a pull request for the change. <Say here whether the session may merge.>Before your last answer: stop any watch you started and any child session.Your last answer is a summary that starts with "Done:", "Partial:","Deferred:" or "Too large:", then one line on what a person must decide.A session reads its instructions when it starts. Editing the instruction or the file does not change a run that is already going; the next run reads the new text.
Write the procedure for a reader who is not there:
- Never end on a question. “Tell me if I should continue” is never read in time, and the run stays open “waiting for you” and holds its place. Decide, or stop and say why
- Put what a person must decide on the pull request or the issue, and say so in the summary. The chat of a stopped session is not where anyone looks
- Say when to skip an item: the issue is closed, the problem is already fixed, or it waits on a decision that is not made. Skipping ends the run with a summary that starts with
Deferred:, and that is a good result - Clean up before the last answer. Stop the watches and timers you started and the child sessions you started. A run ends only when nothing is left to wait for (How long a run stays open)
- Say what the session must not do, as in Use it more safely. Do not put a password or a token in the instruction
Write the memos
Section titled “Write the memos”Each memo is one work item. A memo says what to work on and cannot widen the instruction (What the session is given).
<Name of the item, or a link to the issue>Scope: <what to change>Out of scope: <what to leave alone, and which other item covers it>Depends on: <item, or "none">- State scope and out-of-scope. An item with no edge grows. Naming what is left out is what keeps one run to one pull request
- Keep a fixed dependency line such as
Depends on: …in the text, so a reader and the next session see it. Where order matters, also set the memo to wait for the other one (Make a memo wait for another). The line is for people; the waiting is what the queue obeys - Link a work item instead of copying its text. The session reads the issue itself (Add a work item)
- Decide first, then queue. When your standing instruction tells the session to skip an item that needs a decision (
Deferred:), an unattended run does, and nobody is there to answer otherwise. Record the decision on the issue first, as a comment that states the chosen option, and say in the memo to implement it “as decided in the issue’s latest comment” - Keep the memo short. The item’s detail belongs on the issue, where a person can read it too
Order and concurrency
Section titled “Order and concurrency”- Queue order is priority. A run takes the oldest memos waiting to run, so put the item you want first at the top
- Do not run items that touch the same files at once. Two runs working on the same files conflict when their pull requests meet. Set “Sessions at the same time” to 1 for such a category, or make one memo wait for the other
- A memo that waits for another takes no place. The queue holds it, and memos behind it still run. It is released once the memo it waits for ended well and every pull request of that run is merged
- A session that waits on a watch keeps its run open and holds a place. A run that waits for a long time on a review or a build uses one of the “Sessions at the same time” the whole while. Where the order is known, prefer making the memo wait for the other one over a session that waits
Large tasks
Section titled “Large tasks”A task that does not fit in one run goes through the queue in parts.
- One part per run. Say in the memo which part this is
- Each part leaves the main branch releasable on its own. New behaviour is unreachable, or sits behind today’s default; no half-wired screen is merged. A part that cannot be released alone is too big, so cut it differently
- Record what is left on the issue before ending. A checklist on the issue is enough. The queue does not run a started memo again by itself, so the issue is where the remainder survives. The one exception is a run that hands its memo back because the work cannot be done yet (A run hands its memo back); the memo then runs again later as a new run
- Let the run queue the next part, with a cap in the memo, for example
Part 2 of at most 5. Your approval of the first memo also covers up to the category’s “Follow-ups a run may add without approval” (4 unless you changed it) follow-ups of it, for the same work item, so a five-part task needs one approval, not four (follow-ups). Set that number to at least the parts minus one. The number in the memo is advice to the run, and the category’s number is what the Control Plane counts. Past it the next part waits on the approval card, where approving it starts a new chain. Tell the run to add the next part for the same work item (the same reference) only after its own pull request has merged, and to say when it reaches the cap and add nothing - Do not queue the next part when this part did not merge. Tell the run to add it only after its own pull request has merged. A run that stopped short, or whose pull request is still open, adds nothing, so no memo is left waiting on a pull request that may never merge
- Start the summary with
Partial:for a part that left work,Deferred:for an item it did not do, andToo large:for an item that needs cutting first. They read at a glance in the run history
Review and merge without a person per pull request
Section titled “Review and merge without a person per pull request”This is one way to run it. It suits changes you are willing to merge on a second model’s review; for the rest, keep the merge for yourself.
State what blocks a merge, in the standing instruction and in the reviewer’s brief. These block it: a regression against the main branch, the change’s own behaviour broken under a single fault, data loss, a security hole, and missing tests for the change. A finding that needs two or more independent faults at once, or that only a design change beyond the pull request would close, and that leaves the case no worse than the main branch, goes to a follow-up issue and a Known limits section, and the pull request merges. Without this, a strict reviewer finds a deeper composition every round and the part never merges.
- Review with another model. A reviewer session on a different model reads the pull request and reports to the session that opened it (Child sessions)
- Merge only the commit that was reviewed. Pin the merge to the head the reviewer saw, for example
gh pr merge --match-head-commit <sha>. A merge of a changed head is refused - Treat the last review round with care. A commit after the last review leaves the head unreviewed. In the last round fix only what blocks the merge, and file the minor findings as a follow-up issue
- Keep some merges for a person: changes to CI or release workflows, and migrations that drop or rewrite data. A forward-only migration cannot be rolled back with a release
- Move human checks to a release gate or a staging environment. Label the pull requests that need a live check and list them there, so the check happens once per release and not once per pull request
The instruction states which of these the session may do. A session that must not merge says so in the summary and leaves the pull request.
Watch it
Section titled “Watch it”- Read the run history. The summary opens with the words above, so a day of runs reads as a list
- A run that stays open shows why under “Not finished”. For one you no longer need, press “End” on its row: the place is freed and the session and the sessions it started are stopped (End a run yourself)
- Two failed first turns in a row pause the category. Fix the cause and resume (Pause and resume)
- Check the “Auto-run” row of the notification settings, so an overdue run and a pause reach you (Get notified)
Pitfalls
Section titled “Pitfalls”- Editing the instruction does not change a run that is going. It applies from the next run
- Issues left open after their pull request merged waste runs. The next run picks them, finds nothing to do and ends with
Deferred:. Close the issue, or check before you queue it - A waiting run holds a place. Four runs waiting on watches leave a category with 4 places full and nothing else starts. End them, or make the order explicit with a memo that waits
- A started memo does not run again by itself, except when its run handed it back (A run hands its memo back). When a run ended with work left, the remainder is on the issue. Put it back with “Return to queue” only after you have checked the pull request (Return a run’s memos to the queue)
- Several chains in parallel keep the approval card busy. A chain’s first memo needs no approval when you wrote it yourself or a session you launched added it with that setting on; a memo from any other session needs one. A part past “Follow-ups a run may add without approval” waits on the card too; approving it starts a new chain of up to that many more (follow-ups). Set that number to at least the parts minus one
- Follow-up issues keep growing. Runs file an issue for each finding they set aside, so the issue count rises while the queue converges. They are not queued automatically; triage them from time to time
- Do not turn on “Run by itself” first. Try once with “Run now”, then switch it on, and set the spend limit before you do