How to Use TypeSafe and Jev in Codex Desktop
If you have already installed the typesafe-ai Skill in Codex Desktop and obtained a TypeSafe API key, the next step is understanding how the pieces fit together.
The most common point of confusion is simple: installing the typesafe-ai Skill does not mean Codex will automatically call Jev.
The Skill, API key, environment variable, and Jev API call are separate parts of the setup. Once you understand that distinction, configuring the workflow becomes straightforward.
Can Codex Desktop Run npx skills add?
Yes. If you are working with Codex Desktop, you can install the Skill from the terminal in your project directory.
Run:
npx skills add typesafe-ai/skills --skill typesafe-ai
After installation, you can check the available Skills with:
npx skills list
You can also check from Codex itself:
/skills
If typesafe-ai appears in the list, Codex has successfully recognized the Skill.
For a global installation, use:
npx skills add typesafe-ai/skills --skill typesafe-ai -g
The practical difference is scope. A project-level installation is useful when the Skill belongs to one project. A global installation makes it available across projects.
What Does the typesafe-ai Skill Actually Do?
If typesafe-ai appears under /skills, Codex can load the Skill instructions when working on TypeSafe-related tasks.
That does not mean every request will be sent to Jev.
The Skill is primarily useful for helping Codex work with TypeSafe, including designing workflows and generating TypeSafe/Jev integration code.
Think of the workflow as:
Codex Desktop
↓
typesafe-ai Skill
↓
TypeSafe SDK code
↓
TYPESAFE_API_KEY
↓
TypeSafe API
↓
Jev
The first part is about helping Codex understand how to build the integration. The API request happens only when the generated or existing code actually invokes the TypeSafe API.
This distinction matters when troubleshooting. A Skill can be installed correctly while the API configuration is still missing or incorrect.
Why Doesn’t the Skill Installation Ask for an API Key?
Installing the Skill and authenticating with TypeSafe happen at different stages.
When you run:
npx skills add typesafe-ai/skills --skill typesafe-ai
you are installing the Skill.
You are not yet making a TypeSafe API request.
The API key becomes relevant when an application or script actually calls the TypeSafe API. The TypeSafe JavaScript SDK can read the key from the TYPESAFE_API_KEY environment variable.
So there is no API-key prompt during Skill installation.
How to Configure TYPESAFE_API_KEY
If you already have a TypeSafe API key, configure it as an environment variable in the environment where the TypeSafe code will run.
macOS
Open Terminal and run:
export TYPESAFE_API_KEY="YOUR_API_KEY"
You can verify that the variable exists with:
echo $TYPESAFE_API_KEY
If you want the variable to be available automatically in future terminal sessions, add it to your Zsh configuration:
echo 'export TYPESAFE_API_KEY="YOUR_API_KEY"' >> ~/.zshrc
source ~/.zshrc
After changing the environment configuration, restart Codex Desktop.
Windows
Open PowerShell and run:
$env:TYPESAFE_API_KEY="YOUR_API_KEY"
Verify it with:
echo $env:TYPESAFE_API_KEY
To save the variable at the user level:
[Environment]::SetEnvironmentVariable(
"TYPESAFE_API_KEY",
"YOUR_API_KEY",
"User"
)
Restart Codex Desktop after making the change so the new environment variable can be picked up.
Do not paste your real API key into a public repository or share it in a chat.
Will Codex Automatically Call Jev When I Use typesafe-ai?
No.
Installing typesafe-ai does not turn every Codex request into a Jev request.
For example, you might ask Codex:
Help me determine whether this customer is requesting a refund.
Codex can use the typesafe-ai Skill to help design an appropriate TypeSafe/Jev implementation. It may generate TypeScript code for the integration.
At that point, the important question is whether the generated program is actually executed.
If Codex only writes the code, Jev has not necessarily been called.
If the program is executed and the code makes the TypeSafe API request, the flow can reach Jev.
This gives you two different scenarios.
Code generation only
User request
↓
Codex
↓
typesafe-ai Skill
↓
TypeScript code
Actual Jev execution
User request
↓
Codex
↓
typesafe-ai Skill
↓
TypeScript code
↓
TypeSafe SDK
↓
TypeSafe API
↓
Jev
The second flow is what you need if your goal is to verify that Jev is actually being used.
How to Test Jev from Codex Desktop
Since you already have the Skill installed and have a TypeSafe API key, the most useful test is to ask Codex to create and run a minimal Jev example.
In Codex Desktop, use:
$typesafe-ai
Create a minimal TypeScript example that uses the TypeSafe Jev API.
Requirements:
1. Use @typesafe-ai/sdk.
2. Read the API key from TYPESAFE_API_KEY.
3. Use Jev.
4. Create a simple typed judgment.
5. Actually run the example.
6. Tell me whether the API call succeeded.
7. If it fails, show me the actual HTTP error instead of guessing.
The phrase “actually run the example” is important.
Without it, Codex may simply generate source code. Running the example gives you a way to verify whether the environment variable, SDK, authentication, and API request are working together.
How Do You Know Jev Was Actually Called?
The most useful test is an executable TypeScript example rather than a documentation-only request.
Ask Codex to run a minimal example and report the result:
$typesafe-ai
Create a minimal TypeScript Jev example and actually run it.
Use TYPESAFE_API_KEY for authentication.
Do not only generate the code.
Execute it and report the actual API result or the actual error.
This lets you distinguish several different failure points.
If typesafe-ai cannot be loaded, the Skill configuration needs attention.
If TYPESAFE_API_KEY is unavailable, the runtime environment needs attention.
If authentication or the API request fails, the returned error provides information about the API call.
If the program completes the request successfully, you have verified the actual integration rather than merely verifying that the Skill exists.
typesafe-ai Skill vs. Jev
The two concepts are easy to mix up.
typesafe-ai is useful when you want Codex to help you build with TypeSafe and Jev.
A direct Jev execution tool or Skill serves a different purpose. It can be used when you want an agent workflow to execute a Jev judgment directly rather than generate application code that will call Jev later.
This distinction is especially important when you see $typesafe-ai working successfully. Seeing the Skill in Codex confirms that the Skill is available. It does not, by itself, prove that a Jev API request has been made.
Recommended Setup for Codex Desktop
If your current setup looks like this:
Codex Desktop
✓
typesafe-ai installed
✓
/skills shows typesafe-ai
✓
TypeSafe API key obtained
you do not need to reinstall the Skill.
Configure the API key, restart Codex if necessary, and run an actual Jev test.
Step 1: Check the Skill
In Codex:
/skills
Confirm that you see:
typesafe-ai
Step 2: Configure the API key
macOS:
export TYPESAFE_API_KEY="YOUR_API_KEY"
Windows PowerShell:
$env:TYPESAFE_API_KEY="YOUR_API_KEY"
Step 3: Restart Codex Desktop
This is particularly important after configuring a persistent environment variable.
Step 4: Ask Codex to execute a real test
$typesafe-ai
Create a minimal TypeScript Jev example and actually run it.
Use TYPESAFE_API_KEY for authentication.
Do not only generate the code.
Report the actual API result or the actual error.
Step 5: Inspect the result
A successful code-generation response is not enough to confirm Jev usage.
You want the program to actually execute the API request and return a result or a concrete error.
Quick Setup Checklist
-
[ ] Install Codex Desktop -
[ ] Install typesafe-ai -
[ ] Confirm typesafe-aiappears under/skills -
[ ] Obtain a TypeSafe API key -
[ ] Configure TYPESAFE_API_KEY -
[ ] Restart Codex Desktop if necessary -
[ ] Use $typesafe-ai -
[ ] Ask Codex to create a minimal Jev example -
[ ] Tell Codex to actually execute the example -
[ ] Check the real API result or error
FAQ
Does seeing typesafe-ai under /skills mean Jev is working?
No. It confirms that Codex recognizes the Skill. You still need to execute a TypeSafe API request to verify Jev connectivity.
Why didn’t the Skill installation ask for my API key?
Because Skill installation and API authentication are separate steps. The API key is needed when code actually accesses the TypeSafe API.
Does $typesafe-ai automatically call Jev?
No. The Skill can help Codex create TypeSafe/Jev code, but the API call occurs when the relevant code or direct execution tool is actually run.
Where should I put TYPESAFE_API_KEY?
Use an environment variable in the environment where the TypeSafe code runs. On macOS, you can configure it through your shell environment. On Windows, you can use a PowerShell environment variable.
Should I put the API key directly into the TypeScript source code?
No. With this setup, use TYPESAFE_API_KEY instead of hard-coding the secret in source code.
Can Codex generate Jev code without calling Jev?
Yes. Code generation and API execution are separate operations. Ask Codex to actually run the generated example when you need to verify the API call.
Do I need another Jev Skill?
That depends on your workflow. If your goal is developing an application that integrates TypeSafe and Jev, typesafe-ai is designed to help with that work. If you want Codex to execute Jev judgments directly during an agent workflow, you need an appropriate direct Jev execution mechanism.
What is the simplest way to verify the whole setup?
Use $typesafe-ai to create a minimal TypeScript Jev example and explicitly ask Codex to execute it. The execution result gives you a concrete test of the Skill, environment variable, SDK, authentication, and API request.
