Do I need my own TypeSafe API key to run or fork this?

Not to hold a key yourself. The single Convex action sends the question to Jev through the Convex AI Gateway, so the credential is managed on the Convex side rather than in your browser or env. You do need a Convex project, though, and specifically a paid plan, because the AI Gateway is a paid feature.

Is the answer actually random, or can it repeat the same reply?

It is a model call, not a random draw, so repeated shakes of the same question can produce the same answer, and near-misses will cluster. The page shows a probability for every one of the twenty classic answers rather than only the winner, which is the more interesting read: you can see whether it was confident or picking between neighbours.

How much work is it to stand up my own instance?

npm install, npx convex dev, npm run dev, then npx convex deploy -y and npx @convex-dev/static-hosting deploy --skip-convex. There is no environment variable to configure and no key to paste, which is both the appeal and the constraint — the cost and the credentials live inside Convex.

What happens when the Convex action fails?

The README does not say. There is no documented retry, fallback or error state, and no test suite or CI to catch regressions. If you need that, it is your code to write — the surface is small enough, a single function in convex/jev.ts, that you can see exactly what the frontend does with the response.

How is the ball itself rendered?

src/main.ts draws the ball with three.js and handles the hold-shake-release interaction, while the frontend is served by the Convex static hosting component. There is no separate web server or framework to configure.

Is there a hosted version I can try first?

Yes, it runs live at magic-jev.mikecann.app. That instance still needs someone to pay for the Convex AI Gateway calls, so a public deployment is one where the operator covers the inference cost.

What license is it, and how big is the codebase?

MIT, and small enough to read in one sitting: a three.js frontend, a single Convex action in convex/jev.ts, and a config. The README notes it was built by Mike Cann with a lot of help from Claude Code.

CommunityJev Demos & Experiments

Magic Jev Ball

A Magic 8 Ball that picks with Jev instead of at random. Hold, shake, release, and Jev chooses from the twenty classic answers and returns a probability for each one, shown under the ball.

See highlights

Open github.com

Stars: 2
Language: TypeScript
License: MIT
Published by: Community
Author: mikecann
Last verified: Oct 2026

mikecann/magic-jev-ball

User repository on GitHub

View on GitHub

A Magic 8 Ball that asks Jev instead of picking at random. Convex + AI Gateway + three.js.

Forks: 2
Last pushed: Updated Sep 2026

Repo stats from the GitHub API, cached Oct 2026.Homepage

About this project

A Magic 8 Ball that doesn't pick at random. Hold the ball, shake it, let go, and Jev, TypeSafe's decision model, picks which of the 20 classic answers fits your question. It also returns a probability for every answer, which the page shows under the ball. src/main.ts draws the ball with three.js and handles the hold-shake-release interaction. convex/jev.ts is one Convex action. It sends your question to Jev through the Convex AI Gateway, so there are no model API keys to manage.

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

Tagscommunity jevbest catalog-import awesomejev

Works forJev for Classification Jev for Ranking

Used inJev for Software & DevTools

Languages: TypeScript

Highlights

Every one of the twenty answers comes back with its own probability rather than a single result, so you can see the runner-up.
convex/jev.ts is one Convex action routing the question through the Convex AI Gateway, so there is no model API key to manage.
The ball itself is three.js in src/main.ts with a hold-shake-release interaction, served by the Convex static hosting component.
MIT licensed and small enough to read in one sitting: a frontend, one server function and a config.

Watch out

The whole idea depends on a paid feature — the README says you need a Convex project on a paid plan because the AI Gateway is a paid feature — so the free-tier path is not a deployment story. Routing through the gateway also means your questions go through Convex infrastructure to reach Jev, which is a different privacy posture from calling the API yourself, and the README does not discuss data retention on either side. The repository is very small: no tests, no CI, no configuration surface, and no discussion of failure handling when the Convex action errors or the model returns something unexpected, so treat it as a working sketch rather than a product. A deployed instance is one where somebody else pays for the gateway calls. 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

x-scanner

Chrome extension that sends each X post to Jev with six typed questions in one call near the viewport, then renders a behavior chip under the post plus a session cost and latency panel.