Jev-AI-Skill

One workflow for your AI coding tools: build, skip the large-model turns you don't need, choose the right help, review and publish.

Jev-AI-Skill is one skill and one MCP server for Claude Code, Codex and Hermes. Jev, the fast decision model from TypeSafe System One, makes the small judgments; your AI coding tool does the work. Describe what you want to achieve, and your assistant gets a structured way to work toward it, check the result and prepare the next Git step, while Jev keeps large models out of turns a single cheap decision can settle.

What you get

• Loop builds, finds and fixes code with configured checks and an independent review.
• Gate asks Jev before a large model runs, with four MCP tools:
  • gate_triage decides whether a cron run, poll, notification or chat event needs an agent at all.
  • gate_verdict checks which review findings the evidence already closes before another review round.
  • gate_decide answers a question you would otherwise be asked, and says when you really must decide.
  • gate_pick chooses a tool, skill or session from one-line descriptions.
• --watch runs a recurring check with no agent: silent on success, and a new failure is reported once.
• --http and JEV_MCP_URL keep the TypeSafe key on one always-on server for your private network, while Loop still runs on each machine next to its own projects.
• Route picks a model tier, a skill and whether to delegate.
• Git recommends commit, push or pull-request steps within repository rules.
• find_code.py ranks code-search results so a coding model reads less.

Capability	What it does	Why it helps
Loop	Turns a build or code-repair goal into execution steps, runs configured checks and requests independent review.	Completion depends on checks and a separate review, with saved state for resuming work.
Gate	Asks Jev, before a large model runs, whether an event needs an agent, which review findings are already closed, whether a question must go to the owner, and which tool or skill fits.	Scheduled jobs, polls, notifications, review rounds and owner questions stop consuming large-model turns when Jev can answer from a compact state.
Route	Chooses a model capability tier, a relevant installed skill and whether to delegate.	Routine tasks can use lighter models while harder work gets stronger help; actual cost and quality depend on the available models.
Git	Recommends commit, push or pull-request steps and applies repository rules.	Keeps publishing decisions tied to repository facts, review status and your authorization.

Why use it across AI tools?

Use the same goal, acceptance criteria and workflow whether you work in Claude Code, Codex or Hermes. You can keep your preferred coding assistant while giving it a common process for choosing help, checking progress and handing work to an independent reviewer. The goal and run state live in files, so another configured client can resume the same run when it has access to the same checkout and state. Conversation history is not automatically transferred, and a run should have one active executor at a time.

Route works with capability tiers rather than hard-coded provider model IDs. The active client maps those tiers to the models and delegation tools it actually exposes. This lets the workflow travel between supported clients without prescribing one provider for every task. Jev decisions still require a TypeSafe API key.

Built-in installation currently supports Claude Code, Codex and Hermes. Other AI clients need support for the skill instructions, Python helpers, MCP and an independent review mechanism, plus integration work. Compatibility with every AI app is not claimed.

For example, ask: “Build a CSV export for this project with Jev.” Loop coordinates the work and checks, Route helps choose a suitable skill and model for each task, and an independent reviewer evaluates the result. Git then recommends an authorized repository step. You can also use Route or Git on their own.

For an existing codebase, ask: “Find where the old parser API is used, fix the calls that are broken, and verify the behavior with Jev.” The coding assistant searches and inspects the matches. For an ambiguous change, find_code.py enumerates every visible text chunk in the selected project and asks Jev to rank all of them. It keeps low-scoring chunks in the report; a capable coding model then inspects the original files and decides what to edit. With an exact symbol, the helper can instead rank all literal matching lines. Jev Loop coordinates the repair, checks and review. A request to find locations only reports them without editing files.

Run the read-only ranking helper directly with python <jev-skill-dir>/find_code.py --repo <project> --task "Fix old parser behavior" --output report.json. Add --pattern "old_api" for exhaustive literal matches in that scope. It requires rg and the same TypeSafe key as Jev Route. When Jev cannot answer, the report retains unranked leads and reports the failure. The helper sends short source excerpts to TypeSafe; do not use it for credentials or source that must stay local. Ranking may save coding-model reading on ambiguous searches, but it does not prove that every relevant location was recognized or make an exhaustive review unnecessary.

The installed skill is named jev. The MCP server and its tools keep their existing identity, jev-loop (loop_start, loop_decide, loop_record_turn, loop_record_review, loop_status, and the Gate tools gate_triage, gate_verdict, gate_decide, gate_pick). Route, Git and code search are Python helpers next to the skill (route.py, git_decide.py, find_code.py), not MCP tools. Say jev, jev-loop, jev-gate, jev-route or jev-git; these triggers use the same skill. The installers migrate recognized old skill folders (jev-loop, jev-route and jev-git where configured), removing a folder only when its frontmatter confirms that exact legacy skill.

Install

Requires Python 3.11+, at least one supported harness, and a TypeSafe API key. Set TYPESAFE_API_KEY or store it in ~/.config/jev-loop/typesafe_api_key.

# Windows
git clone https://github.com/King4s/Jev-AI-Skill.git; cd Jev-AI-Skill; .\install.ps1

# Linux, macOS or WSL
git clone https://github.com/King4s/Jev-AI-Skill.git ~/Jev-AI-Skill && ~/Jev-AI-Skill/install.sh

On Windows, install.ps1 always copies the skill to Claude Code's ~/.claude/skills/jev/; it registers Claude's MCP server only if claude is on PATH. Codex and Hermes skill copies and MCP registration are conditional on their CLI being on PATH. On Linux, macOS and WSL, install.sh conditionally copies the skill and registers the server for each CLI it finds (claude, codex, hermes). The POSIX installer creates a repository-local .venv; the Windows installer uses python from PATH. Both install Python dependencies. Hermes uses $HERMES_HOME when set, otherwise ~/.hermes, for its skill, config and .env paths. Both installers run jev_mcp.py --check if a key is available; otherwise they print a key warning and skip the live check. Restart the harness or start a new session after setup. Run the installer again after git pull to update.

One shared server for several machines

By default every harness starts its own local server, which needs the TypeSafe key on that machine. To keep the key on one always-on host instead, run the server over HTTP there and point the other machines at it:

# On the always-on host (a systemd unit is in deploy/jev-loop-http.service)
python jev_mcp.py --http --host <tailnet-ip> --port 8765

# On each other machine
JEV_MCP_URL=http://<tailnet-ip>:8765/mcp ./install.sh      # Windows: $env:JEV_MCP_URL=...; .\install.ps1

With JEV_MCP_URL set, both installers still register a local jev-loop server with Claude Code, Codex and Hermes, but give it JEV_UPSTREAM: the local server reads goal files, runs Loop checks and keeps run state on the machine where the project lives, and forwards only its Jev calls to the host's /jev endpoint. The TypeSafe key stays on that host. The HTTP server has no authentication of its own, so bind it to a private address such as a Tailscale IP.

What that means in practice:

• Loop, Gate, Route and Git all work on every machine, for projects on that machine. A local server needs the repository clone and its Python dependencies, which the installer sets up; it does not need the key.
• If the host is unreachable, Jev decisions fail with Jev upstream ... unreachable. Loop and Gate report that as a failed decision; they never guess.
• Keep JEV_MCP_URL set on every reinstall. The installers replace the registration each time; running one without JEV_MCP_URL makes that machine call TypeSafe with its own key. That is also how to leave the shared server on purpose.
• Updating. On the server host, pull its clone and restart the service (systemctl restart jev-loop-http). On each other machine, git pull and rerun the installer with the same JEV_MCP_URL to refresh the local server and skill copies. Restart harness sessions afterwards.
• Checking the server. systemctl status jev-loop-http on the host. From a client, any HTTP status means it is up: curl -s -m 5 -o /dev/null -w '%{http_code}\n' -X POST -H 'Content-Type: application/json' -d '{}' http://<tailnet-ip>:8765/mcp prints 400. A plain GET keeps the stream open, so always pass a timeout. On a client, JEV_UPSTREAM=http://<tailnet-ip>:8765 python jev_mcp.py --check proves the forwarding path end to end.
• Non-interactive shells. Over SSH without a login shell, CLIs installed in ~/.local/bin are often not on PATH, and the installer then prints not on PATH - skipping for them. Prefix the run with PATH="$HOME/.local/bin:$PATH".
• Older Hermes. Releases without --connect-timeout (seen with v0.17) are handled: install.sh retries the registration without the flag.

The key file can also be used by the helpers. In Hermes, the installer passes an environment reference only when its .env contains a TYPESAFE_API_KEY; otherwise the server reads the key file itself.

Loop

Say what you want built, or invoke the jev skill (/jev in Claude Code, $jev or /skills in Codex, or the harness's skill mechanism in Hermes). It gathers missing requirements, drafts acceptance criteria, writes a goal JSON file and summarizes it. It starts once the user has said to proceed, or directly when the user already asked it to start. The harness follows Jev's role and brief, records each turn, and requests an independent reviewer when Jev routes to review. The server runs configured checks and records the run; only the reviewer can mark it complete.

loop_start → loop_decide → execute → loop_record_turn → checks → loop_decide
                                      review → loop_record_review → execute or stop

The MCP tools are loop_start(goal_path), loop_decide(run_id), loop_record_turn(run_id, notes, files, executor_ok), loop_record_review(run_id, done, missing) and loop_status(run_id). A rejected review returns the run to execution; record that turn before the next decision. An approved review stops the run as complete.

Example requests include:

Build with Jev: a small tool that renames my photos by capture date.

Continue the existing goal in this folder and fix the failing checks.

The skill supports harness-specific tool names and workflows; question and delegation facilities vary by harness. If an optional question or Route delegation tool is unavailable, the skill uses a suitable chat or in-session fallback and states the limitation. Loop always follows the MCP server protocol and obtains an independent review; the executor cannot replace that review with its own verdict.

The goal file uses goal, acceptance, workdir, checks, roles and optional limits such as max_turns, max_consecutive_failures, check_timeout, stall_turns, review_turns, jev_done_threshold and jev_review_threshold; see goal.example.json. Checks are shell commands run in workdir. They may execute code on your machine. Jev receives the goal, acceptance criteria, a limited project file list, check results and compact turn notes; it does not read the implementation itself. A reviewer reads the work independently. Stalled or unreviewed progress can be sent to review before Jev's done score crosses its threshold. The server stores run state in runs/<id>.state.json and a decision tape in runs/<id>.jsonl.

The separate legacy loop.py script asks models through OpenRouter to execute and review the goal. Its executor_model and review_model settings in the example goal apply to that script; the MCP Loop uses the active harness for execution and review.

Gate

Gate came out of an audit of the owner's Hermes, Codex and Claude Code histories: the largest token sinks were not coding, but scheduled jobs that woke an agent to echo an exit code, timers that replayed a whole coordinator thread to find no work, chat-room turns that answered "pass", notification turns that confirmed a green result, review rounds re-run on findings already closed, and questions to the owner whose recommended answer was already known. Each Gate tool replaces one of those turns with a single Jev call over a compact state, and logs the decision to runs/gate.jsonl.

Tool	Question Jev answers	Result
gate_triage(events, known, policy)	For each of up to 40 events: routine, already known, worth a one-line report, or does an agent have to act?	action per event, skip_agent, report
gate_verdict(goal, items, evidence, changes)	Which open findings or criteria does the evidence close, and is the next review none, narrow or full?	items with p_closed, open, review
gate_decide(question, options, context, recommended, policy)	Which of the harness's own options answers the question, and must the owner decide it themselves?	choice, p_ask_owner, proceed
gate_pick(task, candidates, context)	Which tool, skill, session, channel or file fits the task, from one-line descriptions?	pick or null, top

Events and items are clipped to a few hundred characters each; raw output never reaches Jev. Scripts without an MCP host, such as cron jobs, get the same decisions from the command line:

echo '{"events": [{"kind": "cron", "source": "smoke", "summary": "exit 1: /suite 404", "exit_code": 1}],
       "known": ["Suite Landing: HTTP 404"]}' | python jev_mcp.py --gate triage

A recurring health check needs no agent at all. --watch runs the check, prints nothing on success, and on failure asks Jev whether the problem is new; a new problem is printed once and remembered in the known file until the check passes again:

python jev_mcp.py --watch --name "Suite smoke" --known-file ~/.cache/jev/suite.known -- python3 smoke.py

Use it as the script of a script-only scheduled job, such as a Hermes no_agent cron job, where empty output is a silent run.

Gate decides whether a large model runs; it does not replace deterministic facts such as exit codes or commit comparisons, and an error from a Gate tool means the expensive path must be taken, never that an event is ignored.

Route

Route asks Jev to choose a capability tier, a relevant skill and whether to delegate. The tiers haiku, sonnet, opus and fable describe relative capabilities; they are not model IDs. Map the returned tier to a model actually available in the current harness. When the chosen skill falls below the helper's confidence threshold, it returns none. If a requested model or delegation feature is unavailable, the harness applies its documented fallback.

Create a JSON request and pass its path to the installed helper:

{
  "task": "Add CSV export and define done criteria",
  "context": "Keep the existing command-line interface",
  "skills": {"api-and-interface-design": "Design stable module interfaces"},
  "main_model": "sonnet",
  "review": false
}

python ~/.agents/skills/jev/route.py request.json

Use main_model as the main session's mapped capability tier. review must be a JSON boolean; set it to true for an independent reviewer, which requires delegation and raises its tier to at least the main session's tier. The output JSON includes model, skill, subagent, reason and raw probability data. The helper makes the TypeSafe request and returns a decision; it does not launch models or agents itself.

Git

Git gathers repository facts, asks Jev for a next step, and applies hard blocks before returning action, blocked, commands, argv, reason, facts and raw fields. Preview facts and blocks without a TypeSafe call:

python ~/.agents/skills/jev/git_decide.py --repo . --summary "Feature is complete" --scan-only

For a Jev decision, include --reviewed only after independent review and --checks-green only when checks for the current work pass:

python ~/.agents/skills/jev/git_decide.py --repo . --summary "Feature is complete" --reviewed --checks-green

The helper does not modify Git state. commands is display guidance only; use the returned argv as argument vectors with shell execution disabled, after replacing its placeholders. The harness executes only steps already within the user's authorization. By default, direct publishing from main or master is blocked; pushes are blocked for unsupported origin destinations, blocked commits, disallowed identities, matching private patterns or suspected secrets. A pull request also requires both flags above, and an outward step may be withheld when Jev says a user decision is needed.

The secret scan uses a small set of text patterns over added lines in outgoing commits, merge-parent diffs and the working-tree diff, plus commit subjects. It is a heuristic and cannot guarantee that secrets or private data are absent. Review outgoing changes yourself. Private per-repository policies live outside the repository in ~/.config/jev-git/policies/*.json. They match the canonical origin remote exactly. If a repository is renamed, update its configured origin URL and the policy's remote value to the new matching remote while retaining the rest of the policy.

Moving existing clones after the repository rename

The repository's canonical URL is King4s/Jev-AI-Skill (previously jev-loop and jev). Move an existing clone to the new remote by updating its origin, pulling, and rerunning the installer. The local directory may keep its old name; runtime identities such as the MCP server and API key path remain jev-loop.

git remote set-url origin git@github.com:King4s/Jev-AI-Skill.git
git pull
./install.sh                 # Windows: .\install.ps1

Development

See AGENTS.md for repository workflow and CHANGELOG.md for release history. The helper modules use Python's standard library; the MCP server requires the packages in requirements.txt. On Linux or macOS, run pip install -r requirements.txt (Windows PowerShell: python -m pip install -r requirements.txt).

Security

Checks run shell commands from the goal file, and the code they test may have been written by a model. Treat goals and checks as executable code and use an isolated environment for untrusted projects. The API key is read from the environment or key file; it is not written to the repository or run tape.

License

MIT