Guide for noobs to set up Codex CLI in Windows via WSL

Q3 2025

Problem: as a non-programmer or new programmer who wants to just dive into coding immediately with the help of AI, and who does not get the benefit of sitting next to 20 senior developers in a business, I could only get so far with web frontends such as gemini.google.com or chatgpt.com

Your solution: I've done all the hard work/discovery and I explain here how to do it in an ELI5 format (explain like I'm five)

(none of this was written by AI, nor have I used any spell checks)

What is WSL? Windows Subsystems for Linux. Wait wait wait don't leave, it's easier than it sounds, trust me! I avoided this step for literal months because CLI's suck. They still suck but I'll show you what to do.

This guide covers information I wish I could have had access to 8 months ago. If you spend half an hour reading this, that's ~8 months of research condensed into a quick 30 minute study.

There are hundreds, no, thousands of random AI coding projects, IDE's etc. I've tried some, but they always seem to come with problems. Some examples:
- Roo/Kilo et al: API only (which is too costly), and they burn tokens far too quickly on top of that, making them very expensive. The base software is free, but to get any real work done will cost you.
- Claude Code, have you seen the state of the subreddit? CC is falling apart (this may pass), but Sonnet/Opus have worse limits and are more expensive than Codex.
- Cursor/Windsurf/OtherSimilar: yet another paid subscription I don't need, introducing their own limits that I don't want.
- VS Code, sucks in Windows (at the time of writing) and offers little benefit to me over CLI.

Why use CLI? Because the methods are largely cross-transferable. If I learn Codex CLI and have to move to Claude Code (which is CLI-based), the learning curve is low.

Why CLI in WSL?
- Because Windows Subsystems for Linux acts as a container, preventing the AI agent from making changes in your other Windows folders.
- Because the tooling that the AI uses inside WSL/Ubuntu is a lot better than the tooling in Windows. I've tried Codex natively in Windows and my goodness what a horrible experience: nonstop manually approving every tiny request, nonstop powershell commands, python commands, other inane commands that should never even be a thing, I mean holy moly wtf is Codex doing in Windows native? It's just borked. Don't do it. OpenAI please fix this mess. And guys, just use WSL until they do fix it (probably never).

Definition of irony: OpenAI (largely Microsoft owned), builds tools that work better on Mac/Linux than their own operating system (Windows).

See, the issue these days is not that it takes a long time to learn how to code. That will never change. What has changed is learning to code is now optional for entry level.
No, the issue is that learning the TOOLS for AI coding without someone to show you every step of the way is a RIGHT PAIN.

Here are a few examples of the different strength levels of AI coding:

Level 1: Gemini, ChatGPT, and just about every other web-based AI frontend you can imagine.
Level 2: Claude.AI (and maaaybe Google AI Studio (but probably not))
Level 3: Codex CLI (and possibly VS Code, but probably not)
Level 4: Claude Code with MCP, tool calling, multi agents, etc.

That's right, we're bypassing level 1 & 2 and going all the way to level 3. Moreover by training ourselves on level 3 right away, it makes the entry to level 4 that much easier.

My requirements for the perfect AI tool; the AI must:
- Be useable in Windows.
- Code in html for easy preview via canvas or browser; avoid wasting time compiling. It can code in other languages if required, of course.
- Only make requested changes to a codebase; in other words, don't re-write the entire codebase when I just need one line changed. (this rules out most web frontends like Gemini & ChatGPT)
- Some way to view how close to the token cap we are.
- Capable of handing a codebase of 20k+ lines of code without issue.
- Not have stupidly low token limit. (this rules out Claude LOL)
- Not be stupidly expensive. (this also rules out Claude)
- Not be stupidly difficult to set up.
- Don't bug me asking permission for each change. We're vibe coding. I only care about the outcome.
- Don't have access to my Windows files. For security reasons: NO TOUCHEY!!
- I want to do version control myself in the Windows filesystem. I don't understand Github and this is yet another learning curve (tm) that I will address one day, but today is not that day (thanks, Aragorn).

Is this all too much to ask? Apparently. So I have foregone one thing: "not be too difficult to install". Yes, I chose the difficult path. It has taken months of research to get here. New developers who get the benefit of sitting next to their senior peers will no doubt go from zero to complete in 10 minutes or less. Good for you guys. The rest of us plebs don't have the luxury of sitting next to experts all day.

In learning how to do this myself I decided to write a guide on how, to allow other non-developers an easy path to set up the difficult part.

Although I have some experience with coding in the past, I've wanted to try fully embracing vibe coding. Yes, vibe coding. I use the term unironically because I know it annoys a lot of people, and that's mildly hilarious. I hope the term stays, and I hope the haters stay mad.

The problem is that as of the time of writing, most tools that enable vibe coding still suck, and the good ones have a steep learning curve, meaning Jo Bloggs will really struggle to use them. My aim of this page is to provide a short guide so easy to follow that even your grandmother could get it working.

Pre-requisettes:
- This guide is for Windows users. You'll need to be on W10 or later.
- You will need admin rights on Windows. If you own your computer, you can usually assume you have admin rights.
- Buy a $20/£20 ChatGPT 1 month subscription. Stupid expensive I know, let's hope prices drop one day (wishful thinking tbh). You'll obviously need to renew the subscription if you want to keep using it after the first month. AI is advancing so quickly now that it's not a good idea to pay for a years subscription for any given AI tool, because there's always a chance something better is only 3 months away.
- You need to know how to copy & paste. Ctrl+C to copy, and Ctrl+V to paste.
- Note that because Linux CLI sucks (meaning, it doesn't follow standard conventions), Ctrl+V doesn't always work: inside Linux command line you can usually right click to paste.

Skill requirements, you need to understand:
- What the Windows start menu is. If you can find the Windows key on your keyboard that is helpful.
- What the taskbar is (this is the bar with the icons along the bottom of your screen, but you already knew that, right? Right?!)
- What left and right click with the mouse is.
- If I tell you to click on something, assume this means left click unless I state otherwise.

The actual guide begins here:

Fully update Windows. I got this working on Windows 10 as well for what it's worth, but you'll likely be on Windows 11. If you're on W11 you should be on 24H2 at least. You can check by pressing Windows key + R, or search "run" from the start menu. Type "winver" into the run box:

 

 

When you click OK, you should see something like this:

If you're on an older version of Windows 11, for example Version 22H2, then search "Windows update" from the start menu to run updates. I don't have a screenshot of this, sorry.

Caution: I found that it's very easy to break WSL during the setup process if you do things in the wrong order or follow the wrong instructions. So through breaking it multiple times, trial and error, I reinstalled Windows on a test device several times for a clean state to get the process down to a T: in other words, you should follow these steps exactly, not skip anything, and not do anything out of order.

Order of steps: We need to enable the WSL feature, then install WSL, then install Ubuntu:

Key knowledge: to run powershell as admin, click on the start menu (or press the Windows key), type powershell, right click the result -> run as administrator:

 

To enable WSL: Run powershell as admin, then type this command and press enter:
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

Enable Virtual Machine Platform, needed for WSL2 :
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Restart Windows (Click on the start menu -> power icon -> restart)

Random musings: maybe I could have left out /norestart in the previous command to skip the GUI restart step but hey, I didn't test this so ymmv.

After Windows has restarted, open the Microsoft Store. If you can't find the icon, search for "Microsoft Store" from the start menu; the icon looks like this:

 

Search in the Microsoft Store for "Ubuntu LTS" and install the latest version (24.04 at the time of writing). Install it by clicking "Get" then, IMPORTANT: do NOT open WSL/Ubuntu yet.

Open powershell admin again, then enter these two commands, one at a time:
wsl.exe --update
wsl --set-default-version 2

Now go back to the Microsoft Store and open WSL/Ubuntu:

 
Create unix username & pass. The password will not show, this is a Linux security feature. Personally I don't like it, I'd rather see asterisks, but it is what it is.

Close the command line window (it might still be called powershell). Close Microsoft Store.

Search "WSL" from the start menu; it should have a penguin icon, and open it:

Right click the WSL icon on your taskbar and pin to taskbar (the icon may look slightly different)

Launch WSL (penguin icon) by clicking it. If it fails to open, then something has gone wrong - troubleshoot using chatgpt.

----- ----- -----
Skip this paragraph if nothing has gone wrong:
Some of the troubleshooting steps may include- powershell admin commands:
Get-AppxPackage -Name "*ubuntu*" | Remove-AppxPackage
wsl --unregister Ubuntu
Restart Windows, then repeat the install process:
Open Microsoft Store.
Search for the latest Ubuntu LTS, eg. Ubuntu 24.04 LTS then get > open.
It'll ask to create a unix user again.
----- ----- -----

Key knowledge: To paste commands into Linux/WSL, Ctrl+V may not work. You can right click on the command line and it usually pastes whatever text is on the clipboard.

Assuming nothing has gone wrong or troubleshooting was successful: in other words, if you click the WSL penguin icon and it successfully opens, next steps: run the following commands in WSL (not powershell), which will run updates inside of Ubuntu, then install NodeJS:

sudo apt update && sudo apt upgrade -y

Then run these 3 commands one at a time to install NodeJS:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
source ~/.bashrc
nvm install --lts

At this stage everything should be ready to install Codex. You can install Codex in WSL/Ubuntu with the following command:

npm install -g @openai/codex

For the sake of testing, navigate to File Explorer in Windows, look for Linux in lower left corner > Ubuntu > home > 'user' > create new folder called 'coding', enter it > create new folder called 'test1'. The test1 folder can function as your first project folder:

In WSL, you can navigate to the folder that was just created using this command:

cd ~/coding/test1

It should look a bit like this:

To launch Codex: type codex, and press enter:

codex

Sadly I do not have further screenshots detailing the authentication process, but tl;dr it usually works like this:

Log in using your GPT/Codex profile (do not use API). It will present a link which you can copy and paste into a web browser. Log into your ChatGPT account to authenticate.

Press 1 to allow codex to work in this folder without asking for approval.
Press 1 to try the new GPT-5-Codex model.
Use /model command to change models.
On the $20/£20 plan, I recommend using the gpt-5 medium model for planning, and the gpt-5-codex low model for coding.

I recommend starting with html for no compile easy testing.

Key knowledge: Keep your conversations fairly short; start a new chat often. A long chat window will burn through tokens much faster, cause the AI to slow down and increase risk of hallucinations.

Inside the folder you're coding in, I recommend adding at least two md (markdown) files:
Agents.md
Roadmap.md

These are just text files with an .md file extension. You can ask Codex to create the files for you. Here's an example prompt you can give the AI:

Create Agents.md containing the following instructions:

---

# Agent.md instructions
Code in HTML and supporting languages (eg. Javascript)
Keep all logic in one HTML file (no module splits).
Read Roadmap.md first.

# Roadmap.md
Roadmap.md file can be created if it doesn't exist yet.
Roadmap.md should act as a list of planned actions for the project.
Roadmap.md should be continuously updated to mark sections as complete as progress is made.
Roadmap convention: Begin entries with `+` for completed items, `-` for pending/to-do items. When a task is completed, change its leading `-` to `+` and optionally append a brief note.

---

At the end of each chat session, instruct Codex to update Roadmap.md - this means you can close the session and in the new session, instruct Codex to read Agents.md (it does by default but can't hurt to remind it) and read Roadmap.md and ask it to suggest next steps in the coding plan. It should pick two or three next optimal steps from the roadmap and continue where it left off with a fresh session, meaning fewer token usage and faster results.

Note: the reason I instruct via Agents.md to keep all logic in a single html file is because the AI loves to create dozens of files, sometimes splitting them into subfolders. This is good if you have a large codebase with many separate modules, but most of the coding projects I've used so far have been under 2000 lines of code, and when I share a single html file with other people it makes it very easy to share + easy for them to test it, versus having to zip it & instruct them to unzip etc. I find making it easy for others to test your work removes a lot of barriers of entry for getting 3rd party testers: hence using html & monolithic codebase. This may not apply in your use-case.

Beware: 3rd party CLI forks such as just-any-code and opencode: These tools may or may not allow direct authentication. If they do, fantastic. If they do not, and are API only, then they are dead on arrival imo and you should avoid. API is generally too expensive. I believe you can log into opencode with Claude, but as mentioned previously Claude may currently be going through some issues (possibly quantization) so my advice is to stick with Codex until something better comes along (Gemini 3 pls hurry up) or Claude fixes their issues.

API footnote: some open source models such as GLM 4.5 may be viable via API due to lower costs. GPT5 Codex is still better however (at the time of writing)