Overview · Install · Usage · Commands · Keys · Jevels · Configuration · Jev docs

Use Jev everywhere to make & track decisions.

[!WARNING] Early development: jevelry is young and changes fast. Commands, the jevel format and the answer document may change between minor versions until 1.0, so pin the version you depend on.

jevelry lets your code and your coding agent ask Jev, the decision model from TypeSafe, a small typed question and get back a decision it can act on, and it keeps every decision so you can see how often Jev was right.

Overview

Your code and your coding agent make the same small calls every day: is this ticket urgent, which team should get it, is this bug a duplicate, did this test fail because of the code or because of the machine it ran on. Today each of those is usually a prompt that returns text you parse, and you don't learn how sure the model was.

With jevelry you ask each of those questions to Jev with one command. A question lives in a small file called a jevel, and seventeen ready-made jevels ship with the package. Jev answers with how sure it is, and the jevel turns that into one of three decisions:

One ticket triage is about 1,280 input tokens at $0.042 per million, roughly $0.00005, so a dollar covers around 18,000 of them. jevelry itself is free and MIT, and TypeSafe charges only for input tokens.

Where it helps

In your app. A support ticket comes in and needs a team and a priority. On act your code routes it to the team Jev picked, on mark it routes it and flags it for the queue owner, and on fall_back it leaves the ticket for a person, the same way it works today:

npx jevelry ask ticket-triage --state '{"ticket": {"subject": "Charged twice", "message": "I was billed twice this month, please refund one today."}}'

In your coding agent. A test fails with connect EPERM because the sandbox blocked a network call, and left alone your agent will probably start rewriting code that was fine. With the jevelry skill installed it asks first, and on environment it reports the sandbox problem and leaves your code alone:

npx jevelry ask review-comment-kind --state '{"comment": {"author": "ci-bot", "text": "FAIL tests/api.test.ts\nTypeError: fetch failed\n  cause: Error: connect EPERM 104.18.2.1:443"}}'

Features

• Interactive TUI: Built with Ink for a full-screen terminal experience
• Ready-made jevels: Seventeen decisions for tickets, messages, issues, pull requests, logs, alerts and failing tests
• Typed decisions in code: Load a jevel once and get a typed decision wherever your code asks
• Commands Jev runs: Jev picks the command to run and asks you first when it is only fairly sure
• Review and tuning: Mark whether Jev was right and move thresholds based on real outcomes
• Persistent log: Every decision in one local log, with a report per question
• Tested jevels: Every shipped jevel is checked against the real API on its own cases
• Agent skill: One install for Claude Code, Codex, Cursor, opencode and pi
• Typed answers: Your editor knows the options of every jevel

Installation

jevelry runs on Node 22 or newer, so check node --version first.

Using npm, on your machine

npm install -g jevelry
jevelry install

jevelry install puts the skill into every coding agent it finds and asks for your TypeSafe key. You can skip the key with Enter and add it later. Get a key at https://docs.typesafe.ai.

As a library in your project

npm install jevelry

In your coding agent

Run this inside Claude Code, Codex, pi, opencode or Cursor, or in your terminal:

npx jevelry install

If you prefer the skills installer, npx skills add backant-io/jevelry --skill jevelry does the same for the agents it supports.

From source

git clone https://github.com/backant-io/jevelry.git
cd jevelry
npm install
npm run build
node bin/jevelry.js --help

Usage

Start

jevelry tui

It opens on the start screen with what you can do from there: try a jevel, review the decisions Jev marked, open the dashboard or go through your history. Press d for the dashboard, which shows you how Jev decided today, what needs you and how each of your jevels is doing. When your log is still empty, the first row on the start screen offers you a sample ticket: press enter to open it in Try and enter again to ask Jev about it live, and you see your first answer in a few seconds. If you have no key yet, Try tells you how to add one.

Ask from the command line

export TYPESAFE_API_KEY=...
npx jevelry ask ticket-triage --state '{"ticket": {"subject": "Charged twice", "message": "I was billed twice this month, please refund one today."}}'

You get one JSON document back with an answer per question, and the part your code reads is the decision:

"team":        { "choice": "billing",  "confidence": 1.0,  "decision": "act"  }
"urgent":      { "noul": 0.98,         "yes": true,        "decision": "act"  }
"frustration": { "score": 0.24,        "confidence": 0.64, "decision": "mark" }

The whole document and a jq one-liner are in docs/examples.md.

In your program

When the decision happens inside your own code, you load the jevel once when your program starts and call decide at the point where your code decides today:

import { jevel } from "jevelry";

const triage = jevel("ticket-triage");

const d = await triage.decide({ ticket });
switch (d.team?.decision) {
  case "act": route(ticket, d.team.answer); break;
  case "mark": route(ticket, d.team.answer); flagForQueueOwner(ticket); break;
  case "fall_back": leaveInGeneralQueue(ticket); break;
}

decide asks Jev, writes the ask to your log and hands you every question with its decision and its answer. When Jev can't answer, because TypeSafe is busy or your network is down, every question comes back fall_back with the reason in d.error, so your code just keeps its old path. Run npx jevelry types --out src/jevels.d.ts once and d.team.answer is typed as "billing" | "technical" | "account" | "other".

Let Jev run the command

When the next step after a decision is always one of a few commands, you put those commands into the jevel and jevelry runs the one Jev picks. failing-test ships with the package and works this way:

npx jevelry run failing-test --dry-run --state '{"test": {"name": "checkout > pays with a saved card", "output": "TimeoutError: waiting for selector failed: timeout 5000ms exceeded", "history": "fails about once a week and passes on a rerun"}}'

--dry-run prints what would run. Your state goes to the command on stdin and in the file JEVELRY_STATE points at, so a ticket that says ; rm -rf ~ stays plain text. jevelry prints the path of the jevel on stderr before it runs anything, because a jevels/ folder in your project comes before the ones that ship.

Use it with your coding agent

You probably want your coding agent to write the jevel and wire it in, while you review the questions. Once the skill is installed, talk to your agent the way you would to a colleague who has read the guide:

Using the jevelry skill, write a jevel that decides which team a support ticket goes to
and whether it is urgent, run check on it, and wire the decisions into src/inbox.ts.

The skill keeps every jevel in ./jevels/ and leaves the questions and thresholds for you to read. The guide the agent reads is skills/jevelry/references/writing-jevels.md and works for people too.

Command-line reference

-V, --version prints the version and -h, --help prints the help, on the program and on every command. A <source> is @file, - for stdin, or inline JSON.

ask

run

outcome

report

tui

tui needs an interactive terminal and exits 1 in a pipe.

list, show, check

types

install, install-skill

Keyboard shortcuts

The footer shows the keys of the screen you are on, and ? lists them all.

Global

ctrl+p works on every screen, also while you type. The other global keys pause while a screen takes typed text.

Start screen

Dashboard

Review

c, w and s count once a card has been up for 450 ms, and a held key records once.

Jevel

Try

While you edit the state, typing and pasting go into the text, the arrows, home and end move, tab adds two spaces, enter asks and esc stops editing.

History

In the report, j k scroll, J cycles the jevel and esc goes back to the list.

Dialogs

Jevels

A jevel is a folder with one JEVEL.md in it, the same way a skill for your coding agent is a folder with one SKILL.md. The frontmatter holds the questions, their options and the thresholds, and the body is what you and your agents read. Jev takes three kinds of question:

Seventeen ship with the package, each with an example.json to ask it with and a cases.json of realistic states with the answer a person would give. The table with their questions and state keys is in jevels/README.md.

jevelry finds jevels in --jevels <dir>, then JEVELRY_JEVELS, then ./jevels, then $JEVELRY_HOME/jevels, then the ones that ship, and the first one with the name wins. To write your own, copy the nearest folder into ./jevels, change the name, rewrite the questions and run npx jevelry check <name> until it prints 0 warnings. check refuses what the API would refuse (more than 255 options, a threshold outside 0 to 1, a question with no instructions) and warns about a yes/no question whose "yes" means no, a double negative, options that carry different fields and a model that is not pinned. The whole method is in skills/jevelry/references/writing-jevels.md.

Then write a cases.json with at least three states from your own data: one clear one way, one clear the other way and one you would ask a colleague about. The clear cases should land on the right answer, and the unclear one should stay below act.

Decisions and the log

A yes/no question's certainty is how far its probability sits from 0.5, and a choice or score uses the confidence Jev reports. The thresholds live in the jevel, per question, with act: 0.9, mark: 0.7 when the jevel sets none, so a question that skips an expensive step can ask for a higher bar than one that only sorts a list.

The answer document

ask prints one JSON document, protocol 2. Its schema is docs/protocol/ask.schema.json.

On failure the document is { "protocol": 2, "error": { "exit", "code", "message" } }, with field when a field is wrong and retry_after_ms when TypeSafe gave one.

The log, outcomes and the report

Every ask goes into $JEVELRY_HOME/log.jsonl with its answers, its decisions and a hash of the state. The state itself goes in only with --log-state, jevel(name, { logState: true }) or JEVELRY_LOG_STATE=1, because states often hold customer text, and an ask from Try always keeps its state. When you later know what was true, you tell jevelry:

npx jevelry outcome <log_id> urgent yes
npx jevelry report --jevel ticket-triage

jevel          question     asks  act  mark  fall_back  outcomes  agree(act)  agree(mark)  certainty
ticket-triage  frustration  1     0    1     0          0         -           -            0.64
ticket-triage  team         1     1    0     0          0         -           -            1.00
ticket-triage  urgent       1     1    0     0          1         100%        -            0.98

agree(act) is how often act was right, and that is the number you move a threshold by. For a question that repeats over a list, the question name carries the index, so you write same_as[0].

Tuning thresholds

Once a question has 20 reviewed decisions, the Jevel screen proposes a lower act threshold when the decisions above it were right at least 90% of the time and at least as often as at the current threshold, less two points. T writes it into the jevel file. A jevel that came with jevelry is first copied into ./jevels, and from then on your project uses that copy.

Configuration

Environment variables

The model an ask uses is the first one set of --model, the jevel's model, JEVELRY_MODEL and TYPESAFE_DEFAULT_MODEL.

A command started by jevelry run gets these, and TYPESAFE_API_KEY is removed from its environment:

Where the key is stored

jevelry install stores the key in the macOS keychain (service typesafe-api-key, account jevelry) and on every other machine in $JEVELRY_HOME/env as TYPESAFE_API_KEY=..., readable only by you. A key that is already in the environment, the keychain or the file is left as it is.

$JEVELRY_HOME

When it fails

ask and run print one JSON document on stdout in every case. On failure it is an error document and the exit code says what happened:

When jevelry run runs a command, it exits with that command's exit code.

Architecture

An ask flows like this: the jevel is found and checked, the state is checked against the jevel's required keys, questions that repeat over a list are expanded, the request is estimated against the budget, and then the official @typesafe-ai/sdk sends every question in one request. Each answer is checked against its question, turned into a decision by the thresholds and written to stdout, and the ask is appended to the log.

Development

Prerequisites

• Node 22 or newer
• a TypeSafe key, for the live tests only

Build and test

git clone https://github.com/backant-io/jevelry.git
cd jevelry
npm install
npm run build
npm test
npm run lint

npm test builds first and runs the offline suite against recorded answers. The live suite asks the real API with the key from your environment:

export TYPESAFE_API_KEY=...
npm run test:live
npm run test:live -- tests/live/jevels.test.ts

How do we know you can trust it

364 tests run offline against recorded answers from TypeSafe's API reference, against the seventeen jevels and their cases, and against every screen of jevelry tui at 80x24 and 120x40. 99 tests run against the real API on demand with npm run test:live: every jevel answers its own example.json, every case in every cases.json gets the answer it expects, five more cover the API itself, one routes the ticket-triage example through decide in your program, one asks ticket-triage from the Try screen of jevelry tui and one lets failing-test run its command. One of those tests reads the log afterwards and checks that your key stays out of it.

License

MIT. See LICENSE.

Contributing

Issues and pull requests are welcome at https://github.com/backant-io/jevelry. Run npm test and npm run lint before you open one, and when you add a jevel, give it an example.json and a cases.json and run its cases with npm run test:live -- tests/live/jevels.test.ts.