jevex
Minimal agent loop where Jev selects each action and approves tool calls, a chat model fills arguments, and MCP tools execute.
Overview
Jevex is a minimal experiment in an agent architecture where Jev directs control flow. Given the user request and previous observations, Jev selects the next action: a tool, an answer or a clarification. If a tool needs content slots, a LangChain chat model (gpt-4.1-mini by default) fills them; Python validates the arguments; Jev approves the exact call; and an MCP server executes it, appending the result or error to state for the next step. When the answer is ready, the LLM writes the prose.
Three local MCP servers expose 12 read-only tools over documents and simple calculations, using fictional workshop data, and document access is restricted to plain files in one directory. Example cases include reading a price list and multiplying, computing days between dates, or recognising that a weather question has no tool. Jev's choices and confidence go to stderr and an optional JSONL trace records decisions, arguments, observations and token usage. A separate benchmark compares Jev-directed loops with standard and compact native tool-calling LLM loops on real web research with Exa and Fetch MCP, and an illustrated explainer covers the limits it exposed. MIT licensed.
What the decision model decides
| Type | Question | Answers |
|---|---|---|
| Choice | Which action should be taken next: which tool, answer or clarify? | — |
| Yes / no | Should this exact tool call with these arguments be approved? | — |
How it works
- Jev selects the next action from request and observations
- LLM fills content slots; Python validates arguments
- Jev approves the exact call; MCP executes
- Loop until answer or clarification; LLM writes prose
Strengths
- Clear split of control flow and text generation
- Read-only tools and restricted file access
- Benchmark against native tool-calling loops
Caveats
- Minimal experiment with fictional data
- Needs both TypeSafe and OpenAI keys
Getting started
uv sync --group dev, fill TYPESAFE_API_KEY and OPENAI_API_KEY in .env, then `uv run jevex 'Read prices.md. How much do three notebooks cost?' --trace run.jsonl`.At a glance
- Type
- MCP server
- Status
- research
- Language
- Python
- Runtime
- CLI + local MCP servers
- Has code
- yes
- Has tests
- yes
- License
- MIT
Use cases and integrations
How curated lists describe it
An Agent experiment where Jev directs a tool loop, a chat model fills arguments and prose, and MCP tools execute.
logicrw/awesome-jev-projectsMinimal agent loop where Jev directs control flow and a LangChain chat model writes argument values and the final response.
hellogumbo/awesome-jev
Frequently asked questions
Who decides which tool to call?
Jev selects the action and approves the exact call; the LLM only fills arguments and writes prose.
Are the tools safe?
All bundled tools are read-only and file access is restricted.
Is there a comparison with normal agents?
Yes, a research benchmark compares it with native tool-calling LLM loops.
Related projects
Zero-dependency agent harness that sends each loop fork (act?, which tool, risk, done?) to a decision model and keeps the LLM for writing.
ServiceprototypeJavaScript- SystemOneHarness★ 193
Agent harness that compiles an environment's finite actions into typed questions for Jev and gates each step by confidence.
CLIbetaPython DeepSeek Harness plugin with 12 opt-in Jev or Luna Decisions judgments: skill and file selection, supervision, filtering and approval help.
PluginbetaTypeScriptOne skill and MCP server for Claude Code, Codex and Hermes where Jev gates large-model turns, routes models and guards Git steps.
MCP serverbetaPythonPython harness for open-ended goals: AI-authored tools and checks, Jev choosing the next tool and arguments from fresh state.
ProjectbetaPythonPython agent runtime where Jev Choice decisions pick tools and arguments, and low-confidence picks go to an LLM for review.
ServicebetaPython