aayudha docs Built from de79988 (2026-10-26)
Menu

Hand work to an agent

A story is Ready. You can let the agent you are talking to build it, or hand it to another agent's cloud: Codex, Cursor, Claude Code, or Amp. Either way the work comes back as a pull request through the same merge gate, and nothing merges without a person.

You are here: a Ready story, at Level 2. New to Ready? See step 4 of your first hour.

Needs aayudha 0.2. If aayu version prints 0.1.x, this page is ahead of your binary: run aayu self-update. Until 0.2 is released, go install github.com/rahulnakmol/agentic-ayudha/cmd/aayudha@dev installs the build this page describes.

Build it here

aayu build <story>

The agent works in its own git worktree, so your checkout is untouched. It follows the plan one layer at a time, commits a checkpoint after each, checks it, then opens a pull request. A budget keeps watch: by default 8 hours, 3 failed attempts, and 60 USD of metered spend, which applies only when aayudha's own model calls are pay-as-you-go (a gateway endpoint or a provider key); subscription use is not counted. When it runs out, the agent stops and asks a person. A pause at a subscription usage limit is not a failed attempt, and the 8 hours keep running. When an agent building on your machine (--delegate <agent> --local) hits its limit and says when it resets, the build waits and then continues by itself. When it gives no reset time, the build stops as paused: run aayu build <story> --delegate <agent> --local again once the limit resets. When the reset comes after the 8 hours end, the budget runs out during the wait, so the story is blocked as for any wall-time breach, with no attempt counted: once the limit resets, a person runs aayu ready <story> for a fresh budget, then the same aayu build command.

You should see a pull request, and a comment on the story that reads like a flight log: checkpoint, layer, result, and budget used.

The session review loop

Before each push, build has a reviewer model of a different family from the builder review the branch's change (decision 656). It runs when a reviewer it can call is available and the build is not delegated. It uses inspect's own review: the same prompt, schema, and rules as the merge gate's model review.

When the reviewer finds something, the checkpoint is committed but not pushed to the pull request's branch. It goes to refs/aayudha/held/<branch> instead, so aayu build --resume on another machine continues from it.

build lists each open item:

The agent then does one of two things for each:

The loop ends when nothing is left open, or after 3 rounds since the last push. Then build pushes.

The pull request's description gets a Session review (self-attested) section, replaced in place on each push. It lists the rounds, the reviewer, and which items were fixed, declined (with the reason), or left open at the cap.

This section is the builder's own record, not a review that counts. In solo mode a review written in the build session cannot be told from the builder's word, so the merge gate's inspect reviews the pull request again and decides.

The reviewer is the one the merge gate uses when it can be called from your machine:

It must be of a family the builder cannot be (AAYU_MODEL, or the host's build lane). aayu build writes the builder's Aayudha-Host, Aayudha-Model, and Aayudha-Effort (from AAYU_EFFORT) lines into each commit and the PR description, and keeps any a person adds there. The reviewer is of none of the families they name.

When no reviewer can be called, the push goes out without a session review, and the section says why. A build delegated to another agent is reviewed by the merge gate only.

Each round is metered spend, within [budget] per_pr_inspect_max, one cap that the merge gate's review shares. The build's record on the ledger keeps what the rounds spent, so a build resumed on another machine and the merge gate both count it against that cap. A cap of 0 means no cap to inspect, so the session review does not run.

Hand it to another agent

From inside your agent, type the short form, /codex, /cursor, /claude, or /amp, with the story number. Or run:

aayu build <story> --delegate codex     # or cursor, claude, amp, or auto

aayudha sends the receiver one brief: the story's promises, the plan, the branch and pull request rules, and a request to end with a ## What I proved section. auto picks the cheapest connected cloud agent that fits the story's size. Gave it words instead of a story number? A vague ask is unpacked with you first, and the story is made Ready before anything leaves (how aayudha unpacks a vague ask).

You should see the hand-off recorded on the story, then a pull request from the receiver.

Cloud by default

A hand-off goes to the receiver's cloud agent, not your laptop. aayudha checks first that the agent is connected and that its cloud environment can build and test your repository. --local runs the receiver's command line on your machine instead, in a fresh worktree with only its own key, so it cannot push.

If the receiver is not ready, build says exactly what is missing (the CLI, the sign-in, or the cloud connection), gives the commands to fix it, and lists the agents you can use instead. It never installs or signs in for you. See hand-off problems.

Set up the cloud environment once

aayu install --env              # shows what it found in your code, and every host's files
aayu install --env --verify     # writes them, then proves each host in a clean container

install --env reads your code for toolchains, the package manager, services, and the names of the variables you need. It asks only what the code cannot say, then writes one setup script every host calls. Commit the files it writes: a cloud agent sees only what is on your default branch.

You should see each host marked verified in aayu doctor's agent-env row.

Follow it to the end

Run the same build --delegate command again to sync. aayudha reads the receiver's report as a preview, then the merge gate's verdict:

The ci-failed loop can run that sync for you whenever a check fails.

Under the hood

The brief, the receiver adapters, the environment spec, and the cycle cap are in hand-offs, agent environments, and loops. How each host loads aayudha is in your agent.

What's next