QLiMBer Blog

My notes on various topics

View on GitHub

WSL AI Dev Pipeline (Codex CLI + Cursor + GitHub)

Use this guide to set up an end‑to‑end WSL AI development pipeline that keeps your repositories in WSL for performance and makes Codex CLI fully functional, while you edit from Cursor on Windows and version in Git from WSL.

  • Keep repos on WSL’s ext4 for speed and reliable tooling.
  • Run Codex CLI in WSL; authenticate using the WSL workflow below.
  • Open and edit the same repo from Cursor on Windows via Remote - WSL.
  • Commit, branch, and push from WSL with SSH keys.
  • Bonus: Codex + Cursor is a great combo; currently, OpenAI and Cursor are offering GPT‑5 testing in both with separate usage limits.

Target: Ubuntu 22.04 in WSL2 — this is the recommended default for Windows developers using Linux tooling in WSL as of 2025, because Ubuntu 22.04 LTS is widely supported, stable, and gets long-term updates. The instructions here assume this environment. If you’re using another distribution or release, some package commands or versions may differ, and future LTS releases may change the defaults.

1️⃣ Update apt and check Node.js/npm

sudo apt update && sudo apt upgrade -y
node -v && npm -v  # Checks Node.js/npm versions, needs v20.x/v10.x or newer

If both Node.js and npm are new enough, you can skip the Node.js upgrade steps.

2️⃣ Remove old Node/npm if needed

sudo apt remove -y nodejs npm libnode-dev
sudo apt autoremove -y
sudo apt clean

3️⃣ Install latest Node.js LTS (if upgrade needed)

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs git

# Verify
node -v && npm -v  #  Node.js/npm versions, should be v20.x/v10.x or newer

💡 Why the curl step is important: Ubuntu’s default apt repository (even in 22.04 LTS) often ships older Node versions for stability. The curl command adds NodeSource’s repository to apt, which provides up-to-date Node.js builds. Without it, apt install nodejs would likely give you an outdated version (e.g., v12 on older setups), breaking modern tools like Codex CLI.

2️⃣ Install Codex CLI

sudo npm install -g @openai/codex
codex --version  # should show codex-cli 0.20.0 or similar

If npm prompts about a newer major version being available, you can usually ignore it unless you specifically need the newest npm features. NodeSource ships the npm version bundled with the Node LTS release, which is tested for stability. To update anyway:

sudo npm install -g npm@latest

This is optional and mainly for users who want the very latest npm.

WSL authentication (headless browser) workaround

If codex login cannot open a browser inside WSL, use this SSH tunnel method from Windows. See the project notes about Windows/WSL in the Codex CLI repo: openai/codex.

  1. Install and start SSH server in WSL (Ubuntu):

    sudo apt install -y openssh-server
sudo service ssh start

  2. From Windows PowerShell or Command Prompt, forward port 1455 to WSL and keep this window open:

    ssh -L 1455:localhost:1455 your-wsl-username@localhost

  3. In your WSL terminal, run login and follow the URL in your Windows browser:

    codex login
# Auth server listens on http://localhost:1455 and prints an https://auth.openai.com/... URL

4.Click the URL with ctrl (or copy paste to browser) and complete auth in Windows browser. It should redirect to http://localhost:1455/success. The WSL terminal will show “Successfully logged in”.

  1. Verify and clean up:

    codex "print('Hello')"  # quick test
    • Close the Windows SSH tunnel window when done.
    • Optionally stop SSH in WSL: sudo service ssh stop (or remove openssh-server if no longer needed).

3️⃣ Create SSH key for GitHub (shared ssh-agent)

ssh-keygen -t ed25519 -C "your_email@example.com"
# Press Enter for defaults; set a passphrase to protect the key

Next, configure a single ssh-agent that survives for the whole WSL session and unlock it the first time you run git or codex:

cat <<'EOF' >> ~/.profile
SSH_ENV="$HOME/.ssh/agent.env"

start_ssh_agent() {
    eval "$(ssh-agent -s)" >/dev/null
    cat >"$SSH_ENV" <<EOT
export SSH_AUTH_SOCK=$SSH_AUTH_SOCK
export SSH_AGENT_PID=$SSH_AGENT_PID
EOT
    chmod 600 "$SSH_ENV"
}

if [ -z "$SSH_AUTH_SOCK" ]; then
    if [ -f "$SSH_ENV" ]; then
        . "$SSH_ENV" >/dev/null
        kill -0 "$SSH_AGENT_PID" 2>/dev/null || start_ssh_agent
    else
        start_ssh_agent
    fi
fi
EOF

Add wrappers in ~/.bashrc so the first Git or Codex command prompts for the passphrase when a TTY is available, and otherwise reminds you to unlock the key manually:

cat <<'EOF' >> ~/.bashrc

ensure_codex_key() {
    if ssh-add -l >/dev/null 2>&1; then
        return 0
    fi
    if [ -t 0 ] && [ -t 1 ]; then
        echo "SSH key locked; enter passphrase to continue."
        ssh-add ~/.ssh/id_ed25519
    else
        echo "SSH key locked; run ssh-add ~/.ssh/id_ed25519 in a shell first." >&2
        return 1
    fi
}

git() {
    ensure_codex_key || return $?
    command git "$@"
}

codex() {
    ensure_codex_key || return $?
    command codex "$@"
}
EOF

source ~/.profile

~/.ssh/agent.env now stores the active agent socket for the current WSL session. The first call to git or codex after opening a terminal prompts for the key; later calls reuse the unlocked agent until you close WSL or kill the agent manually.

Show the public key so you can add it to GitHub:

cat ~/.ssh/id_ed25519.pub

→ Copy & paste the output into Settings → SSH and GPG keys → New SSH key on GitHub.

4️⃣ Configure SSH for GitHub

mkdir -p ~/.ssh && chmod 700 ~/.ssh
# The here‑doc below appends multiple lines non‑interactively, you can also paste the block between lines with EOF using nano.
cat << 'EOF' > ~/.ssh/config
Host *
    ForwardAgent no
    IdentitiesOnly yes

Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519
EOF

# Set correct permissions for SSH config file (required for SSH to work)
chmod 600 ~/.ssh/config

5️⃣ Clone repos into WSL filesystem

git clone git@github.com:YourUser/your-repo.git

Git + Codex SSH

  • Automatic passphrase prompt: The ensure_codex_key helper added above prompts the first time you run either git or codex in a new WSL session. If you forget to unlock the key before running Codex, the wrapper prints a reminder to run ssh-add ~/.ssh/id_ed25519 in a shell with a TTY.

  • Set remote manually (SSH): If you configure the Git remote yourself, use the SSH URL:

    git remote set-url origin git@github.com:username/repo.git

  • Letting codex init Git: If you let codex initialize and configure Git, supply an SSH URL (not HTTPS), for example:

    git@github.com:user/git-remote-test.git

✅ Keeps everything on ext4 for speed and avoids CRLF issues.

6️⃣ Use VS Code/Cursor in WSL mode

  • Install Remote - WSL extension.

  • From WSL terminal:

    code ~/projects/your-repo

    (Replace code with cursor if available)

  • Status bar should show: [WSL: Ubuntu]

📅 First-use checklist after reboot

# 1. Open a WSL terminal (shared ssh-agent is restored via ~/.profile)
# 2. Run git or codex once to unlock the key; you'll be prompted the first time only
#    If Codex says "SSH key locked", run ssh-add ~/.ssh/id_ed25519 in a terminal with a prompt

After that, GitHub SSH will work without asking again until you close WSL or reboot.

Now you’ve got:

  • Latest Node.js + npm
  • Codex CLI
  • Fast, secure GitHub SSH access with 1 passphrase per session
  • Projects on WSL’s native filesystem
  • Seamless IDE integration

📝 Notes

Git on Ubuntu 22.04 LTS (Jammy)

Ubuntu LTS prioritizes stability, so apt install git installs the older, supported Git 2.34.x with security backports. This is fine for this pipeline, but if you want newer Git features/fixes, use the official upstream PPA:

sudo add-apt-repository ppa:git-core/ppa
sudo apt update
sudo apt install git
git --version

Reference: Git downloads for Linux and Unix.