Why not just use a vision model to read the screen?

Because it was tried and measured. A CLI call to Claude Haiku took 22.5 s per frame and hallucinated the hand, returning Lumberjack, Barbarian and Ogre for a Mini P.E.K.K.A hand. Template matching against real card art took about 10 ms and was correct on every battle frame tested, which is why there is no vision API key anywhere.

What can the agent actually not do?

Name the card the opponent played. Clash Royale draws a red health bar and nothing else, so the agent knows pressure is coming and from where, but not whether it is a Skeleton Army or a Golem. That removes counter-picking, ground-versus-air reasoning, and tracking the opponent's 8-card cycle.

Will it work without a TypeSafe API key?

Yes. The key is optional, and without it the agent runs on local tactics alone, which the README calls fully playable. Tactics are generated and scored in code against Clash Royale rules, and urgent situations are played immediately from them without consulting Jev at all.

What setup is needed before it will tap anything?

macOS 15 or later with iPhone Mirroring, Node 20+, and Accessibility permission for your terminal so synthetic taps are delivered. Then npm install and npm run compile-native, which compiles the Swift helper. The card index is committed, so no asset download is required to start.

What are the requirements to run it?

macOS 15 (Sequoia) or newer with iPhone Mirroring, Node.js 20+, and Accessibility permission for your terminal so synthetic taps are delivered. Then npm install and npm run compile-native builds the native helper.

What does it send to Jev?

Only the locally-perceived game state and the validated candidate plays: local tactics decide urgent situations immediately, and Jev picks between candidates otherwise. Without TYPESAFE_API_KEY the agent runs on local tactics alone, which is fully playable.

How is the perception done?

One native pass per frame extracts cards in hand by normalized cross-correlation against official card art, elixir by measuring the magenta bar fill, units from red/blue health bars, and clock and tower HP via Apple Vision OCR on a schedule.

CommunityJev Demos & Experiments

Jev Royal

Autonomous Clash Royale agent on macOS through the native iPhone Mirroring app, with local deterministic pixel perception and Jev choosing between candidate plays that code has already scored.

See highlights

Open github.com

Stars: 3
Language: TypeScript
Published by: Community
Author: Amrit-Nigam
Last verified: Oct 2026

Amrit-Nigam/jev-royal

User repository on GitHub

View on GitHub

Forks: 1
Last pushed: Updated Sep 2026

Repo stats from the GitHub API, cached Oct 2026.

About this project

An autonomous agent that plays Clash Royale on macOS through the native iPhone Mirroring app. Perception is entirely local and deterministic; TypeSafe's Jev ("System One") model is used to arbitrate between tactical options that have already been validated in code. Locate & capture — finds the iPhone Mirroring window via CGWindowListCopyWindowInfo and grabs silent, shadow-free frames with screencapture -x -o -l .

Quoted from the project's README. Read the full README.

Tagscommunity jevbest catalog-import

Works forJev for Classification

Used inJev for Software & DevTools

Languages: TypeScript

Highlights

Cards recognised by normalized cross-correlation against official art for all 120 cards; elixir read as a fraction, not OCR.
Cloud vision was measured and rejected: a CLI vision call took 22.5 s per frame and hallucinated the hand; matching takes about 10 ms.
Urgent situations are played straight from local tactics; Jev only arbitrates between candidates already scored in code.
TYPESAFE_API_KEY is optional, and without it the agent runs on local tactics alone and stays playable.

Watch out

The agent cannot identify which card the enemy played, because Clash Royale draws only a coloured health bar, so there is no counter-picking, no ground-versus-air distinction and no opponent cycle tracking. It reacts to pressure, not matchups. OCR state is sampled on a schedule, velocity tracking is nearest-neighbour, and only iPhone Mirroring is supported. Copy reviewed against the repository README on 2026-10-04, not from running it.

Questions about this entry

Short answers drawn from the linked project or page.

More Jev resources like this

laya-server

Self-hosted Docker service and web UI that packages Laya structured-decision inference behind a compatible System One endpoint.