SikuliX1 is a read-only mirror: where visual automation actually lives now

What this repository actually is, and who it is not for

The README opens with a status badge that reads "archived mirror" and a heading that calls SikuliX1 a "Historical SikuliX1 codebase mirrored under oculix-org." The table immediately below it is the clearest statement of intent in the whole file: if you want to use SikuliX today, the README sends you to oculix-org/Oculix. If you want to report a bug or request a feature, it sends you to that fork's issue tracker. If you want documentation, it sends you to docs.oculix.org. The only row that describes this repository is the last one: "Browse the legacy SikuliX1 code."

So the audience is narrow. This is for someone who needs to read the 2.0.x-era source: a maintainer porting a patch forward, an engineer auditing what a legacy script actually did, or a researcher tracing the lineage the README lays out from MIT CSAIL in 2003 through the 2009 UIST paper to RaiMan's stewardship and the 2026 handover. It is not for someone who wants a working automation tool this quarter. The README says the upstream RaiMan/SikuliX1 was archived by its creator in March 2026, and that this mirror exists so the code stays browsable.

The distinction matters because the repository is not archived on GitHub itself, and its last push was on 2026-07-24. A recent commit date on a mirror is not evidence of a maintained product. The README's own status badge and its "read-only mirror" line are the authoritative statement, and they point in the opposite direction from the commit timestamp.

How SikuliX locates a button: OpenCV, screen pixels, and no DOM

The mechanism the README describes is computer vision. SikuliX uses OpenCV to identify and interact with anything visible on a screen, on Windows, macOS or Linux. It locates GUI elements through image recognition and then drives them with simulated mouse and keyboard input. The README states plainly that no access to source code, DOM, or accessibility APIs is required, and quotes the original motto: "If you can see it, you can automate it."

That design decision is the whole architecture. A script holds a reference image of the target, the runtime captures the screen, and the match is resolved by template matching rather than by a widget identifier. The practical consequence is that the same script can drive a Java Swing application, a browser, and a native dialog without three different driver stacks. The other consequence is that the script is only as stable as the pixels it matches against. Theme changes, font rendering differences, display scaling and DPI settings all sit between the reference image and the screen, and the repository layout reflects that concern: there is a Support/ directory at the top level and an IDE/ directory alongside API/, which is where the scripting and capture tooling lives.

The README also names Tesseract OCR as part of the stack, which is how text on screen becomes readable when image matching alone is not enough. For the modern continuation, the README lists OpenCV 4.10 via Apertix, Java 17+, a working VNC stack, Android 12+ ADB, a PaddleOCR option, and 22 native-reviewed locales. Those are the fork's characteristics, not this mirror's, and the README presents them as the reason to move.

Installing and running a first script from the mirror

The README does not give installation steps for this repository. It gives a routing table. That is the honest answer to "how do I install SikuliX1 from oculix-org/SikuliX1": the README tells you to use the fork instead, so the only install instructions you can follow in good faith are the fork's.

The repository does carry a pom.xml at the top level, so the code is a Maven project and can be built from source if you have a JDK. A .java-version file sits next to it, which pins the Java version the build expects. Read that file before you run anything, because the README positions this codebase as the Java 8 to 11 era while the fork is Java 17+.

git clone https://github.com/oculix-org/SikuliX1.git
cd SikuliX1
cat .java-version
mvn -f pom.xml package

What you should see is a Maven build producing artifacts under target/. What the README does not promise is that the result runs on a current JDK, that the OpenCV binding resolves on your platform, or that any of it is supported. There is no release note describing a build recipe for this mirror.

For a first real use, the README's own direction is to install the active fork and read docs.oculix.org. The image-matching idea you would write against is the same one, so the shape of a script is worth understanding even if you never build this mirror. A SikuliX script names an image file and an action; the runtime finds the image on screen and performs the action at the matched coordinates. The README does not include a code sample, so the exact API surface is something you read at docs.oculix.org rather than copy from here.

The failure mode is the pitch: pixel matching breaks quietly

Image recognition is also the limitation. A match either succeeds or it does not, and when it fails the script does not usually report a missing widget. It reports that the image was not found, or it matches the wrong region and clicks there. Nothing in the README describes a fallback that inspects the accessibility tree or the DOM when the visual match fails, because by design there is no such fallback. The README frames this as the strength: no source code, no DOM, no accessibility APIs. The same sentence is the failure mode.

The second constraint is the release history visible in the repository. The release list includes 2.0.5 labeled "buggy version" from 2021-03-03, a 2.0.5-final revision the same day, and a v2.0.5 dated 2026-04-02. A version label that carries the word "buggy" is a warning about which tag you check out. If you pin a build to this mirror, pin it to a tag whose provenance you have actually read, not to the newest date.

The third is scope. This is the wrong tool when the target exposes a real automation surface. If the application has a documented API, a DOM you can query, or accessibility metadata, driving it through screenshots adds a rendering dependency for no benefit. Visual matching earns its place when the interface is a black box: a legacy desktop client, a third-party installer, a remote console, a canvas. It is the wrong tool when the interface is already addressable.

OculiX versus this mirror: a fork with a support path

The alternative the README names is oculix-org/Oculix, and the difference is not cosmetic. OculiX is described as the active fork, targeting Java 17+, with current releases listed as v3.0.3 stable and v4.0 in flight. It carries OpenCV 4.10 via Apertix, a working VNC stack, Android 12+ ADB support, a PaddleOCR option, and 22 native-reviewed locales. It has a public documentation site at docs.oculix.org and an issue tracker at oculix-org/Oculix/issues.

Compare that with what this mirror offers. No documentation site of its own. No issue tracker for its own code, since the README routes bug reports to the fork. No stated Java version beyond what .java-version pins. The difference in approach is not a different matching algorithm; it is whether anyone will answer when the match fails. Choosing between them is choosing between reading history and running software.

If you want a different category of tool entirely, the honest comparison is to accessibility-API drivers and browser automation frameworks, which address widgets by identity rather than by appearance. Those fail loudly when the widget is missing and survive a theme change. They also cannot touch an application that exposes nothing, which is the case SikuliX was built for. The two approaches are not substitutes; they cover different halves of the problem.

Licence, maintenance cost, and what upgrading means here

The repository is MIT-licensed, and the README says the MIT licence chosen 23 years ago is still in place. MIT is permissive: it allows reuse and modification with the licence and copyright notice preserved. That is a statement about the licence text, not legal advice about your situation; if you are redistributing a build, read LICENSE at the repository root and get your own counsel on notice requirements.

The maintenance cost of depending on this mirror is the cost of depending on code nobody is patching here. The README states that upstream RaiMan/SikuliX1 was archived by its creator in March 2026 and that stewardship moved to oculix-org. Bug reports for this codebase go to the fork's tracker, which means a fix you need will land there, not here. The last push to this repository was on 2026-07-24, but the README's own status badge calls it an archived mirror, so treat the commit date as mirror housekeeping rather than product maintenance.

Upgrading is a migration, not a version bump. Moving from this 2.0.x-era source to OculiX means a Java 17+ runtime, a newer OpenCV binding through Apertix, and whatever API changes came with v3.0.3. The README does not document a migration guide, and it does not document rollback. If you are running SikuliX scripts in production today, the thing to verify first is which release your scripts were written against, because that determines how much of the API you will be re-reading at docs.oculix.org.

Editorial conclusion

Adopt this repository only as a reference copy of the historical SikuliX1 source, and only if you have a reason to read 2.0.x-era Java rather than run it. Anyone starting new visual automation work should go to oculix-org/Oculix, which the README describes as the active fork with Java 17+ and current releases, and read docs.oculix.org for the current API. Before you clone either one, verify two things in the target repository itself: the licence file at the root, and whether the release you intend to build against is the one the README currently recommends.

Frequently asked questions

Official sources

1. License: MIT
2. oculix-org/SikuliX1 on GitHub
3. Project website
4. README
5. Releases