The Codex extension for VS Code refuses to send prompts until it has a concrete project folder to work against. When it doesn't, you get the red "Unable to send message" banner with the prompt "Add a project to use Codex." The fix is almost always about the folder Codex is pointed at, not the account or the model.
What the error actually means
Codex runs in Agent mode by default, which reads files, executes commands, and writes changes inside a chosen project directory. Before it will accept a prompt, it requires you to register one of your open folders as the active project. The "Add a project to use Codex" message is the extension telling you no workspace has been attached yet.
The same screen appears in two common situations: a fresh install where no project has been picked, and remote or unusual workspaces where Codex cannot treat the open folder as a valid project root.
Add a project from the Codex panel
Step 1: Open the folder or Git repository you want Codex to work on using File > Open Folder in VS Code. Pick a specific project directory, not your home directory and not the root of the drive.
Step 2: Open the Codex panel from the Activity Bar. If you don't see the icon, check the collapsed "Additional Views" section in the sidebar, then drag the panel to the side you prefer.
Step 3: Sign in with your ChatGPT account or an OpenAI API key if you haven't already. Every ChatGPT plan includes Codex, and API credits work as an alternative.
Step 4: In the "Select your project" modal, check the workspace you just opened and click Add project, then Continue. The currently opened folder appears as an option alongside any projects you've added before.
Step 5: Type a prompt into the "Tell Codex what to do" field. The status bar should show your project name and branch. If the prompt sends and Codex responds, the project is registered correctly.
Remote SSH and WSL workspaces
Codex treats remote folders as projects, but it needs a real project directory, not a filesystem mount point. Opening / over Remote-SSH on a Linux host is a known trigger for the "Add a project to use Codex" state, because the root directory is not a valid project scope.
Reconnect to the remote host and open a specific subdirectory, for example /home/you/projects/my-app, then add it from the Codex panel. The same rule applies to WSL and Dev Containers: pick the project folder inside the remote environment rather than the container root.
Common reasons the project won't attach
| Symptom | Likely cause | What to do |
|---|---|---|
| "Add a project to use Codex" on every prompt | No folder added yet, or VS Code has no folder open | Open a folder, then click Add project in the Codex panel |
Error appears when opening / over Remote-SSH | Filesystem root is not a valid project scope | Open a specific project subdirectory on the remote host |
| Codex panel is missing after install | Panel collapsed in the sidebar | Expand "Additional Views" or drag the Codex icon to the Activity Bar |
| Prompt still fails after adding a project | Stale extension state | Reload VS Code window, then reopen the Codex panel |
| Multi-root workspace with no active folder | Codex can't infer which root is the project | Open a single-folder workspace or add each root as a separate project |
Installing the extension from scratch
If the Codex panel never appears, the extension may not be installed in the current environment, which happens often with Remote-SSH where extensions install per host.
Step 1: Install the extension for your editor from the official install link for Visual Studio Code, Cursor, Windsurf, or VS Code Insiders. For Remote-SSH, install it on the remote side after connecting.
Step 2: Reload the window and open the Codex panel. Sign in with ChatGPT or an API key.
Step 3: Open a project folder and add it from the selection modal. Codex confirms the project by showing its name and current Git branch along the bottom of the input area.
How to know it worked
Three signals confirm the project is registered. The red "Unable to send message" banner disappears. The status row at the bottom of the Codex panel shows the project name and branch, for example Local and main. A prompt sent to Codex returns a response that references files in your workspace.
Because Codex can modify files directly, commit a Git checkpoint before running your first substantial task. That way you can revert any changes cleanly if the result isn't what you wanted.
If the error keeps coming back
Persistent "Add a project to use Codex" errors after a project is added usually trace back to the workspace itself. Check that VS Code still has the folder open (an empty window resets Codex's project context), that you're not accidentally opening the drive root, and that your Remote-SSH session is pointed at a real project path. If the extension keeps losing state on a specific platform or remote setup, reinstalling the Codex extension in that environment and re-adding the project clears most lingering issues.