How to Build a CI Failure Fix Agent

A CI failure fix agent starts from a clear trigger and ends with a handoff a person can check. The steps below cover that path, and the code shape after them lists the fields one run needs.

1. 1Define the trigger: issue, PR, failed CI job, docs change or support ticket.
2. 2Limit tool access to the files and systems the agent needs.
3. 3Add a plan step before writes.
4. 4Run checks and produce a short reviewer handoff.
5. 5Log the prompt, changed files, commands and result.

type AgentJob = {
  task: string;
  context: string[];
  allowedTools: string[];
  checks: string[];
  handoff: "diff" | "comment" | "pull_request";
};

Decide allowedTools first. While you build, broad access is tempting, because narrowing it is fiddly and everything works when you are watching. An agent that runs unattended with write access to the whole repo and a shell is a different kind of risk from one that can edit three paths and run a single command. You find out which one you built on the run where something goes wrong.

handoff decides whether people will trust the agent. For an agent that changes code, returning a diff keeps a person in front of every change before it lands, which is the right default while you learn how the agent behaves on your codebase. A pull request keeps the same gate with less friction once you have more confidence in the agent.

A comment is the lightest handoff and suits agents that only diagnose. Whichever you choose, don't let the agent merge until the commands in checks are ones you would have run yourself.

Most failures here are ordinary. The agent gets too much room, or someone trusts a "done" that no test proved.

Scope problems show up first. Give an agent a vague task and it will find related work to do, which looks like initiative until you face a diff across twenty files and can't tell which changes were the point. Narrow the task instead: name the files, name the behavior that should change and say what is out of bounds. A stronger model won't solve a scope problem.

Weak checks show up last and do the most damage. An agent reports success from its own reading of its own work, and nothing outside it says otherwise. If the agent's summary is the only thing between its work and your main branch, you have no review step. Give it a command whose exit code you trust, and fail the run when that command fails.

Partly, so check before you write a line of this. Cursor's cloud agents automatically try to fix CI failures in pull requests they opened themselves. That route supports GitHub Actions only, and automatic fixing is available on Teams and Enterprise plans.

On other plans that include Cloud AgentsAgents that run in a Cursor-managed virtual machine, check out the repo, do the work and open a pull request, then shut down, with no load on your laptop. Press Enter for the full definition., ask the cloud agent to monitor and fix CI failures on the PR. Free and Plus don't include Cloud Agents.

The dividing line is who pushed the commit. Cloud agents don't auto-fix CI failures on human commits. So red checks on branches that people pushed by hand fall outside the automatic path, and that is the gap a build of your own fills.

You can also ask directly. Tag the agent in a comment on the pull request, for example @cursor please fix the CI failures. To switch the automatic behavior off for one pull request, comment @cursor autofix off.

Spend a week on the built-in path with real red pull requests before you build. Reading a handful of the agent's attempts shows which of your failures it can fix at all, and designing the loop first can't tell you that. If you skip that week, you risk a well-built repair agent aimed at failures that needed a person anyway.

Give it a ceiling and a list of cases where it won't act at all. Cursor's own auto-fix stops after 10 CI-failure follow-ups on a pull request. It also skips an attempt when the same check is already failing on the PR's base commit, when a human pushed a new commit, or when someone sent the agent a follow-up message. The ceiling of 10 is Cursor's setting, not a rule. Any small ceiling works, as long as the run ends by saying it gave up instead of going quiet.

Copy the base-commit rule first, and don't ship the loop without it. A check that was red before your branch existed is not your branch's problem. An agent that can't tell the difference keeps editing until the check turns green. That patch is worse than none, because it changes code that was never broken and buries the real fix inside the diff.

The human-commit rule guards against a quieter problem: two authors on one branch, one of them a machine. If someone is halfway through their own fix, an agent patching underneath them creates a conflict that neither of them wrote. One conflict is cheap to sort out, but a loop that keeps causing them is the kind a team switches off.

The ones where the log names the problem and any engineer on the team would fix it the same way. That covers a type error, a lint rule, a snapshot that needs regenerating, or an import that still points at a file that moved.

Keep flaky tests out. Ask an agent to make a failing test pass, and it will find a way to make it pass. On a real bug, that is what you wanted. On a race condition, it means a retry wrapper or a quietly widened assertion, and you have automated the removal of a signal you were paying to have.

Before you write your own, read Cursor's marketplace template for triaging failed GitHub Actions. It investigates a failed or cancelled run, posts a summary to Slack and defaults to triage only, opening a pull request only when it has high confidence in a minimal fix. That shows where someone else drew the line between investigating and changing code.

For the loop itself, use agent -p "...", the headless form: a prompt goes in, a result comes out, and there is no interactive UI. That fits a CI job where nobody is at a keyboard to approve a step. Give it an explicit allow or deny policy for shell commands instead of the permissions you happen to use interactively.

Start it as a diagnosis-only agent that comments on the failure, names the suspected cause and proposes no patch. A month of reading those comments is the cheapest way to learn whether its patches would have been any good.