codex-oauth-automation-extension: The Chrome Extension That Turns OAuth Into a State Machine

The login flow is the product

This repo is not really about clicking buttons faster. It is about keeping a fragile sequence of transitions alive while the browser, the email provider, and the target site all keep changing the rules. That is why the most useful mental model is not “bot,” but stateful controller.

The extension’s job is to coordinate a process that can break in half a dozen places: a redirect arrives late, a page label changes, a verification code lands in the wrong inbox, or the flow lands on an unexpected callback. The interesting part is not that it automates a login. It is that it treats failure as normal and builds around it.

// Simplified mental model of the flow
const steps = [
  'configure',
  'openSignup',
  'fetchCode',
  'submitCode',
  'captureCallback',
  'recoverIfNeeded'
];

async function run(state) {
  for (const step of steps) {
    state.current = step;
    await dispatch(step, state);
    if (state.failed && isRecoverable(state)) {
      await recover(state);
      continue;
    }
  }
}

// session state keeps the live step
// local state keeps persistent settings

A state machine hidden inside a browser extension

The center of gravity is the background service worker. It coordinates step transitions, stores live progress in chrome.storage.session, and keeps durable preferences in chrome.storage.local. That split matters. One layer is for “where am I right now,” and the other is for “how should I behave next time?”

That architecture gives the extension a recovery story. If the flow pauses, reloads, or trips on a redirect, the system can rehydrate state and keep moving instead of starting over blindly. In a brittle auth funnel, that is the difference between a script and a control plane.

Identity is modular, not fixed

The other notable design choice is that email is treated like a backend, not a hardcoded dependency. The repo supports different mailbox paths, and the orchestration layer can switch between them without rewriting the whole flow. That is how one state machine can survive multiple provider quirks.

This is a small but important abstraction. When the inbox source becomes replaceable, the rest of the system stops caring whether the code arrives from a local helper, a remote API, or a specific provider implementation. The flow keeps its shape even when the identity source changes.

Why the extension survives UI drift

The brittle part of any automation is the page surface. Labels change, inputs move, and one A/B test can invalidate a selector that used to work yesterday. This repo answers that with defensive selectors, regex-based matching, and page-specific content scripts that are willing to keep looking until they find the right control.

That is a subtle but important move. Instead of betting on one perfect DOM shape, the code accepts that the UI is unstable and writes for variation. The result is less elegant than a single query selector, but much more honest about the environment it runs in.

That comment is revealing because it shows the project’s real shape. Features are not bolted on as isolated scripts. They are inserted into the step model itself, which is exactly what a resilient automation system should do.

Recovery is a first-class feature

The most mature part of the design is how it handles failure. Late-stage callback issues are not treated as impossible edge cases. They are part of the expected operating envelope, and the code includes logic to decide whether to retry, reset, or keep moving.

• A verification code may arrive, but not in the mailbox path the flow expected.
• A callback may land late, after the state machine has already advanced.
• A selector may work on one page variant and fail on the next.
• A step may time out, but the system can still recover without losing the whole run.

That is why the repo feels closer to infrastructure than a macro. Most automation tools optimize the happy path. This one spends its effort on everything that happens after the happy path breaks.

How it compares to simpler approaches

A simpler Chrome extension can be easier to understand and easier to ship. A Python batch tool can be better for bulk operations and server-side control. This repo sits between them, with the browser-native reach of an extension and the discipline of a state machine.

The trade-off is obvious. More orchestration means more moving parts, more state to track, and more surface area to maintain. But that cost is the point. If the target flow is unstable, the tool has to be unstable in reverse, meaning flexible enough to absorb change without collapsing.

Seen that way, the repo is not overbuilt. It is appropriately built for a hostile interface.

What this repo really is

The useful lesson here is architectural, not operational. codex-oauth-automation-extension treats authentication as a browser-native control problem: coordinate steps, keep state, swap backends, recover from failure, and do it all inside MV3 constraints. That is why it reads less like a script and more like a small automation OS.