turnstile-bypass works by patching one mouse event, and verified only on macOS

Two preconditions and one preflight line decide everything

The project's own entry condition is two items: Python 3.10 or newer, and Google Chrome or Chromium. That is the entire dependency list, because requirements.txt contains exactly one package, DrissionPage at 4.0.0 or newer. Installation is three commands:

git clone https://github.com/Sophomoresty/turnstile-bypass.git
cd turnstile-bypass
python3 scripts/install.py

install.py creates a virtual environment inside the repository, installs the requirements, packs the extension archive and runs a preflight script. The preflight result you want is a single object reading ok true with a drissionpage method of true. Chrome is located by path, and the documented fallbacks are an environment variable pointing at the binary on macOS and Windows, a stable Chrome or Chromium package on Linux, and xvfb with a command prefix on a Linux box with no desktop.

The core trick is a two-property mouse event patch

The interesting engineering is smaller than the name suggests. The extension is Manifest V3, runs in the MAIN world, applies to all frames, and matches one origin only: challenges.cloudflare.com. What it changes is MouseEvent.screenX and screenY. The reason is documented with a chromium issue reference: when Chrome is driven through the DevTools Protocol, synthetic clicks arrive with screen coordinates equal to client coordinates, and the challenge interprets that as bot behaviour. So the patch is a compatibility shim for an artifact of browser automation, not a model, a solver farm or an image classifier. That distinction matters for anyone judging the risk, because the change is scoped to two fields on one origin and leaves everything else about the page alone.

Three lanes exist, and the default depends on your PATH

After installation the default lane is DrissionPage plus the packaged extension. That default is conditional: if agent-browser-cli and Node are already on the PATH, the entry script prefers that lane instead, and an environment variable set to zero forces the DrissionPage route back. Both lanes can be requested explicitly, and the documentation notes that the agent-browser lane is faster only when that tool and Node are installed and when the Chrome profile already has the extension loaded. There is also a port rule worth knowing: iframe clicks must go through the DevTools Protocol on its default port 19221, never the shim on 19222. So a machine whose ambient PATH happens to contain a browser CLI will change behaviour with no configuration change on your part.

A paid third-party solver is wired in, introduced mid-sentence

A third lane exists and it is not local. A client key environment variable named for a commercial captcha service is read, and a lane flag selects that service, with a site key passed on the command line to identify which challenge to solve. The README calls it a last resort, and the ordering is consistent with that label: local automation first, a faster local toolchain second, a paid remote service third. The paragraph introducing it, however, ends on the word and, with the explanation of what the key is used for never arriving, and the layout listing cuts off partway through that script's filename as well. Neither gap changes the design, but both mean the remote lane is documented less precisely than the other two.

The scope table rules out more than it claims to handle

There is a table headed with what the project is not, and it is longer than the in-scope column. In scope: the widget challenge on the origin page, and the interstitial waiting-room page in either its JavaScript or managed form, ending in a clearance cookie plus the real origin HTML. Out of scope: Cloudflare 1020 and 1015 responses and WAF blocks, Bot Fight when the browser is already banned, and three things it is not at all, namely hCaptcha, reCAPTCHA and headless Chrome. The limits section repeats it: headed Chrome only, the interstitial path needs the tab in front, datacenter addresses often fail with one residential retry allowed before stopping, and tokens must not be cached across sessions. Most of these limits are Cloudflare's decisions rather than the author's.

Verification covers macOS out of three claimed platforms

The description claims macOS, Windows and Linux, and the verification table covers one of them. The stated environment is macOS with Chrome 152, the agent-browser path and DevTools Protocol port 19221. Four rows are recorded: Cloudflare's own dummy widget page, a local interactive dummy page, one production widget target with a token length of 816 across three attempts in eight to eleven seconds, and one interstitial target returning a clearance cookie between 533 and 597 characters in about nine seconds. There is no Windows row and no Linux row anywhere in the file, and the project publishes no releases at all, with the last push to the default branch dated September 7, 2026. Cross-platform support is a design claim rather than a tested one.

The success test is a 20 character floor a dummy token clears

Output is a single JSON object on stdout, and the success criteria are length checks rather than validity checks. A widget solve is ok true plus a token longer than 20 characters, to be used immediately since the lifetime is about 300 seconds. An interstitial solve is ok true plus a kind of cf_clearance or cf_passed and a clearance length above 20. Failure is ok false with an error field, and the documentation adds one instruction worth repeating in any wrapper you build: do not invent a token. Note what the verification table shows about that threshold. Both dummy targets returned a token length of 21, one character above the floor, while the production target returned 816. A length check cannot tell those apart.

Four root entries never appear in the layout listing

The layout block in the documentation accounts for the runnable parts of the project: the runbook, the readme, the license, the requirements file, the extension source and its packed copy, an example page, and nine scripts covering install, end-to-end check, preflight, packing and the individual solver variants. The repository root holds more than that. A SKILL.md sits next to AGENTS.md, so the project is packaged both as a runbook for coding agents and as something installable as a skill. Three directories, harness, rules and workflows, appear in neither the layout block nor the prose. One documented script, the Camoufox variant, has no description beyond its filename, and the limits section describes the project as not a fingerprint browser.

Editorial conclusion

Read this before running anything. Automating your way past a bot check is something site operators have chosen to put in front of their pages, and using this against a third party's site may breach that site's terms whatever the code allows. Where it is defensible is testing your own integration against Cloudflare's own demo page, or reproducing a challenge your own application now has to survive. If you take it at all, install it, run the preflight, and stop at the point where the scope table says no, because the cases it excludes are excluded by Cloudflare rather than by this project. Fix your own IP reputation before assuming the tool is the problem, and never cache a token, since the lifetime is about five minutes.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Sophomoresty/turnstile-bypass on GitHub