Codex Jev Preflight

A fail-open preflight hook for every Codex task.

Ask TypeSafe Jev for task_type, complexity, risk, and execution_mode before Codex starts working. The result is advisory, validated, and never blocks the task.

Live demo · Quick start · How it works · Configuration · Security · 中文

_{If this project is useful, consider giving it a star ⭐}

Why this exists

Codex normally decides for itself whether a task should be answered directly, inspected first, planned, or clarified. This project makes that first decision consistent by asking Jev before execution starts.

JEV PRE-TASK ASSESSMENT (automatic, advisory routing metadata):
- task_type: code_change
- complexity: moderate
- risk: medium
- execution_mode: inspect_then_act

Important

The assessment is advisory context only. It cannot override system instructions, developer instructions, or an explicit user request.

Tip

If Jev times out, hits a quota limit, or returns an invalid response, the hook fails open and Codex continues normally.

Features

Feature	Description
Fail-open	Jev errors never block the task
Zero dependencies	Python standard library only
Persistent breaker	Stops repeated calls after a confirmed exhausted quota
Validated output	Unknown values become unknown
Private configuration	Hidden API-key input and 0600 file permissions
Manual trust	The installer does not trust the hook automatically

Quick start

Recommended: paste this into Codex

Install and configure Codex Jev Preflight from https://github.com/wellkilo/codex-jev-preflight.

Requirements:
1. Read the repository README first.
2. Install the project from source.
3. Run codex-jev-configure and ask me to enter the TypeSafe Jev API key with hidden input. Never ask me to paste the key into chat.
4. Run codex-jev-install and verify the hook output.
5. Preserve existing hooks.json and AGENTS.md configuration.
6. Tell me whether Codex must be restarted or a new task must be opened.

Manual install

git clone https://github.com/wellkilo/codex-jev-preflight.git
cd codex-jev-preflight

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

codex-jev-configure
codex-jev-install

The default configuration path is $CODEX_HOME/jev.env, normally ~/.codex/jev.env.

Restart Codex or open a new task after installation, then approve the hook if prompted. To explicitly opt into automatic trust:

codex-jev-install --trust

Verify

python -m unittest discover -s tests -v

HOOK=$(python -c 'import jev_user_prompt_hook; print(jev_user_prompt_hook.__file__)')
printf '%s' '{"prompt":"Review the project and propose a fix","hook_event_name":"UserPromptSubmit"}' |
  python "$HOOK"

The output should contain JEV PRE-TASK ASSESSMENT.

How it works

flowchart LR
    A[User prompt] --> B[Codex UserPromptSubmit]
    B --> C[TypeSafe Jev]
    C --> D[Validate four choices]
    D --> E[Inject advisory context]
    E --> F[Codex continues normally]
    C -. timeout / quota / error .-> G[Fail open]
    G --> F

Loading

After installation, use Codex normally. No special command is needed in every prompt:

Inspect the authentication module, identify security risks, and propose the smallest safe fix.

Routing fields

Field	Values
task_type	answer, code_change, research, browser_automation, planning, conversation, other
complexity	trivial, simple, moderate, complex
risk	low, medium, high
execution_mode	direct_answer, inspect_then_act, plan_then_execute, ask_clarification

Configuration

TYPESAFE_API_KEY=your-key
TYPESAFE_API_ENDPOINT=https://api.typesafe.ai/v1/systemone
JEV_MODEL=jev-latest
JEV_STATE_PATH=/absolute/path/to/.jev_quota_state.json

Variable	Required	Description
TYPESAFE_API_KEY	Yes	TypeSafe Jev API key
TYPESAFE_API_ENDPOINT	No	Defaults to https://api.typesafe.ai/v1/systemone
JEV_MODEL	No	Defaults to jev-latest
JEV_STATE_PATH	No	Persistent quota-breaker state file
JEV_ENV_FILE	No	Explicit configuration file
JEV_HOOK_DEBUG_LOG	No	Optional hook debug log

Configuration lookup order

1. JEV_ENV_FILE
2. .env beside the project source
3. .env in the current working directory
4. $CODEX_HOME/jev.env
5. $XDG_CONFIG_HOME/codex-jev-preflight/env

Existing process environment variables take precedence.

Reset the quota breaker

After adding credits, remove the state file or run:

python -c 'from jev_agent import get_default_client; get_default_client().reset()'

Security and privacy

• The hook sends the first 24,000 characters of the current user prompt to the configured TypeSafe endpoint.
• API keys are not logged, and real env files are excluded by .gitignore.
• Jev responses are validated against the allowed routing enums before injection.
• Do not include sensitive data that should not be sent to a third-party service.
• Report vulnerabilities through the process in SECURITY.md.

Documentation

Resource	Description
Live frontend	English default with a Chinese language switch
Frontend source	Zero-build GitHub Pages site
Architecture	Hook flow, routing contract, and fail-open paths
Contributing	Local development and pull-request rules
Changelog	Release history

Development

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -m unittest discover -s tests -v

Tests are fully offline and never call the live Jev API.

License

MIT License. See LICENSE.

This project is not affiliated with OpenAI, Codex, TypeSafe, or Jev.