# When a website changes: how Dejo replays safely

> Every saved step is checked. Dejo finds a moved button another way, clears pop-ups and cookie banners safely, stops on the wrong account, and relearns only the step that broke.

Canonical: https://dejo.run/docs/when-the-site-changes

> For AI agents: the index of this site is https://dejo.run/llms.txt, and every page is also served as markdown (add .md to its address, or send Accept: text/markdown).

**The short answer:** every saved step carries a check that it landed. When the page is different, Dejo either finds the element another way, clears what is in the way, or stops at that exact step and says why. It never clicks on blindly, and every choice it makes on its own is listed in its reply.

I build Dejo, and this was the question nearly every reply asked after I posted our benchmark. A tool that replays saved steps is only as good as what it does when the page does not match, so here is all of it, including the parts where Dejo stops and asks.

| On the replay, the page shows... | What Dejo does |
|---|---|
| The same page | Replays every step as plain code, no model calls |
| A button that moved or got new words | Finds it with another of its saved ways, and says which |
| A toast or banner that is not there this time | Skips the step that closed it, and says so |
| A pop-up that was not there while learning | Closes it safely, then runs the step, and says what it pressed |
| An element that is really gone | Stops at that one step; your agent fixes only it |
| More than half the steps broken | Treats the site as rebuilt and learns the task again |
| A different signed-in account | Stops before step 1 and names both accounts |
| A sign-in page instead of the site | Asks you to sign in again, instead of repairing anything |
| A captcha or a block | Stops and hands the browser to you |

## Every step is checked

When your agent first does a task, Dejo saves each step together with proof that it worked: the address changed, the field holds the value, the file downloaded, the row count is right. A step that cannot check itself is not saved.

On a replay, each step runs and then its check runs. If the check fails, the replay stops at that step. This is what separates Dejo from a recorder: a recorder plays the clicks back; Dejo plays them back and confirms each one.

## A button that moved or got new words

Each step remembers up to nine ways to find its element, best first: its role and name (`button "Save"`), its label, its text, its place, and more. Sites restyle often, and a new class name or a slightly different position usually leaves one of those ways working.

When the first way misses and a backup finds the element, the backup moves up for next time, and the reply says which way was used. On a slow page, Dejo waits for the page to finish before it calls any way broken. How this differs from Playwright's healer agent is in [self-healing Playwright: repair one step, not the run](https://dejo.run/blog/self-healing-browser-automation).

## Pop-ups, toasts and cookie banners

These are the most common reason a saved route breaks, because they do not appear at a fixed point. Dejo handles both directions.

**Shown while learning, gone on the replay.** If your agent closed a toast or a cookie banner while learning, and that press only took its own element away, the step is saved as one that can be skipped. When the banner is not there next time, Dejo skips it and says so. A toast that faded out by itself, or said "Dismissed" before it went, counts too. A risky step (marked `!`) or a step with its own check is never skipped.

**Not there while learning, in the way on the replay.** When something covers the element a step needs, Dejo tries these, in order:

1. the pop-up's own close: "Close", "No thanks", "Not now", "×"
2. the Escape key
3. a consent banner's button, choosing "Reject all" or "Necessary only" over "Accept"

It never presses anything that buys, pays, sends, deletes, submits, subscribes or signs up, and never a button that sends a form with fields in it. Many news sites ask for consent inside the consent platform's own frame; Dejo looks inside that frame with the same rules.

On real sites on 10 November 2026, from a clean browser: theguardian.com's consent box was answered with "No, thank you", and on spiegel.de, which offers only "Consent and continue" or "Subscribe now", Dejo pressed "Consent and continue" and never the subscribe button. Both tasks then replayed in under two seconds.

## Only the broken step is learned again

If no saved way finds the element, or its check fails, Dejo stops at that one step and shows the page. Your agent sends one line for that step, and the rest of the route stays as it was.

If more than half the steps are broken, the site was rebuilt rather than tweaked. Dejo then learns the task again, but it keeps what it already knows about the site (its pages, its pop-ups), so the second time costs less than the first.

## The right account, or it stops

A saved route does the right steps for whoever is signed in. Replayed as the wrong person, it would download their invoice or post as them. So while learning, Dejo notes who the page shows as signed in: an email address in the header or account menu, the name on the account button, or "Signed in as ...". Only what is on the screen, never a cookie or a password.

Before a replay acts, and after any sign-in step, Dejo looks again. If the page names someone else, it stops before step 1 and says who was expected and who is signed in. A page that names nobody is no reason to stop. To set it yourself, add a step:

```
expect signed in as "you@example.com"
```

To keep several accounts apart from the start, give each its own profile. See [signing in](https://dejo.run/docs/sign-in).

## Signed out, captchas and blocks

When a session runs out, a site sends you to a sign-in page, an identity provider (Google, Microsoft, Okta, Auth0), or answers 401. Dejo recognizes these after a step fails and asks you to sign in again, rather than "repairing" a step that is not broken.

On a captcha, or a pop-up with no safe way out, Dejo stops and hands the browser to you. It does not solve captchas and does not get around a site's block on automated browsers.

## Everything it decided is in the reply

Nothing that changes what ran is silent. A replay that decided anything on its own says so:

```
done: "the price" on shop.example (profile default), 3 steps replayed in 1840 ms, no page reading.
decided on its own (2):
- step 2: cleared a pop-up: "Join our newsletter" closed by its "No thanks" control; cleared up front from now on
- step 3: found by a backup way (css:#total-button); role:button|Show total missed and moved down
```

The same list is written to the step log in `~/.dejo/logs`, so you can see later what happened on a run nobody watched.

## When the task changes

A saved route answers one task. Asked in other words, Dejo replays it only when it is sure it is the same job, for the same person, with the right values (since 0.5.1):

- **New values are swapped in.** "flights from Kolkata to Pune on 9 Dec" replays the Delhi to Mumbai route with every value changed, and says so. A value the route has no place for stops it before step 1.
- **"This month" means this month.** A route learned in September for "this month's invoice" is moved to the current month by the browser's clock.
- **Another subject or another deed is another job.** "find the minimum Dart SDK" never replays "find the changelog entry", and download never runs delete. Dejo stops and shows the page in the same reply, so your agent teaches the new task at once.
- **Each signed-in profile keeps its own routes.** A customer's and a vendor's "show my orders" never overwrite each other.

## How we test it

The Dejo repository has a drift lab: demo pages that change between visits (a toast on some visits, a newsletter box only on the replay, a consent banner, a button whose words and class change, a list that reorders, an element that arrives late, and a second account). Each test learns on one visit and replays on another. Real-site checks run on top of that, which is how the frame-based consent boxes above were found and fixed. The code and tests are in [dejohq/dejo-mcp](https://github.com/dejohq/dejo-mcp).

## FAQ

## FAQ

### What happens when a website changes after Dejo learned a task?

Each saved step has a check that it landed. If a button moved or got new words, Dejo usually still finds it with one of up to nine saved ways. If none of them works, Dejo stops at that one step, shows the page, and your agent fixes only that step. If more than half the steps break, the site was rebuilt, and Dejo learns the task again.

### Will Dejo click the wrong thing if the page looks different?

It is built not to. Every step is checked after it runs, so a click that did not land stops the replay instead of carrying on. Dejo never guesses between two elements with the same name, and it never presses anything that buys, pays, sends, deletes, submits, subscribes or signs up while clearing a pop-up.

### What about cookie banners and pop-ups that only show up sometimes?

A pop-up that covers a step is closed by its own close button, then Escape, then a consent button, choosing reject over accept. That works inside a consent platform's own frame too. A step that only closed a banner is skipped when the banner is not there next time. Every choice is listed in the reply.

### What if a different account is signed in?

Dejo notes who the page shows as signed in while it learns. Before a replay acts, it looks again. If the page names someone else, it stops before step 1 and says who was expected and who is signed in.

### Does Dejo solve captchas?

No. On a captcha or a block it stops and hands the browser to you. It does not solve captchas or get around a site's block on automated browsers.

## Related

- [Dejo MCP server setup: install in a minute](https://dejo.run/docs)
- [Browser automation in Claude Code: add a browser MCP](https://dejo.run/docs/claude-code)
- [Browser automation in Codex: the config.toml setup](https://dejo.run/docs/codex)
- [Cursor browser automation with a browser MCP](https://dejo.run/docs/cursor)
- [Keep your AI agent signed in to websites](https://dejo.run/docs/sign-in)
- [Dejo MCP tools reference](https://dejo.run/docs/tools)
- [Troubleshooting Dejo](https://dejo.run/docs/troubleshooting)
