›_ Codex Issues
Codex Issues / #25385

Codex Desktop: add API/CLI support for creating and registering projects

Open 💬 4 comments Opened May 31, 2026 by Sereja3578

Feature request

Please add supported API/CLI functionality for creating and managing Codex Desktop projects from automation and from Codex itself.

Use case

I want Codex to be able to organize many conversations into projects based on natural-language instructions, for example:

  • "Create projects from this list of names."
  • "Create Codex projects for each folder under ~/Documents/Codex/Projects."
  • "Analyze my existing chats and move/organize them into projects by topic."

Today Codex can create folders and can see existing saved project IDs, but it cannot register new project/workspace roots unless they were added through the Desktop UI.

What I tried

  • Created project folders under ~/Documents/Codex/Projects
  • Added custom macOS folder icons
  • Tried adding paths manually to .codex-global-state.json under electron-saved-workspace-roots and project-order
  • Codex Desktop later rewrote the state back to the UI-registered project list
  • Tried codex app "/path/to/project"
  • Tried creating a thread with the app tool using an unregistered folder as projectId

The tool rejected the unregistered path:

Unknown projectId: /Users/me/Documents/Codex/Projects/Gadgets
Saved projectIds:
/Users/me/Documents/Codex/Projects/TestProject

Requested behavior

Please expose supported project/workspace management operations, such as:

codex project add "/path/to/project"
codex project remove "/path/to/project"
codex project list

or:

codex app "/path/to/project" --save-project

or equivalent app-server methods:

{ "method": "workspaceRoot.add", "params": { "path": "/path/to/project" } }
{ "method": "workspaceRoot.list" }
{ "method": "workspaceRoot.remove", "params": { "path": "/path/to/project" } }

It would also be useful if Codex agents could call an official tool to:

  • create a project from a name
  • register an existing folder as a project
  • create projects from a list
  • create projects from folders
  • organize existing chats into projects by meaning/topic

Why this matters

Projects are core to keeping Codex useful over time. If a user has many workflows, manually creating and opening every project through the UI is slow and hard to automate. A supported API would enable:

  • import workflows from ChatGPT project lists
  • bulk project setup
  • Finder Shortcuts / Automator Quick Actions
  • cleanup and organization assistants
  • future chat migration / classification workflows

Environment

  • Codex Desktop on macOS
  • Codex app version: 26.527.31326
  • Codex CLI version: 2.93.0 GitHub CLI installed separately for reporting

View original on GitHub ↗

4 Comments

Sereja3578 · 2 months ago

Additional finding after testing a manual migration attempt:

I tried to move existing projectless threads into saved projects by updating local state fields and sqlite metadata:

  • removed thread IDs from .codex-global-state.json -> projectless-thread-ids
  • changed .codex-global-state.json -> thread-workspace-root-hints to saved project roots
  • updated state_5.sqlite -> threads.cwd to the saved project root paths

Immediately after editing, local sqlite/global-state looked correct. After restarting Codex Desktop, the app restored the old state:

  • projectless-thread-ids returned to the original projectless thread list
  • thread-workspace-root-hints returned to /Users/me/Documents/Codex
  • the UI still showed the threads as projectless/orphaned

So the saved/projectless ownership model appears to be maintained by another internal source of truth or reconstructed by the running app, and local file edits are not a reliable workaround. This makes an official API/tool for moving existing threads into projects even more important.

A useful API would cover both directions:

codex thread move --thread <thread-id> --project /path/to/project
codex thread classify --project-roots ~/Documents/Codex/Projects

or equivalent app-server / desktop tool operations.

devansh-jain-18 · 1 month ago

I hit the same gap in Codex Desktop on macOS while trying to continue an agent task in a newly cloned repository.

Current behavior:

  • The Codex app tools expose project listing and thread creation, but thread creation only accepts an already-saved projectId.
  • There is no callable add/register project operation.
  • Falling back to Computer Use does not work because Codex explicitly blocks automating its own app: Computer Use is not allowed to use the app com.openai.codex for safety reasons.
  • The CLI fallback, codex app /path/to/repo, did not connect to the already-running Desktop app in this environment and instead attempted to download another installer, so it was not a reliable registration path.

This leaves an agent able to clone and inspect a repository, but unable to add that folder to the Desktop project list or create a project-scoped worker there without a manual UI step.

An official high-level tool such as add_project(path), backed by an app-server workspace-root add/list/remove API, would close the gap without requiring self-UI automation or edits to internal global-state files.

drock · 27 days ago

Adding the missing desktop UX case to this request: Codex Desktop currently has no discoverable Remove project action in the project menu, and the project documentation covers editing/pinning/archiving chats but not removing a local project.

Requested behavior:

  • Provide a supported Remove project action in the Desktop UI, plus the CLI/API operations proposed here.
  • Remove only the project registration/sidebar entry—never delete the underlying folder or Git repository.
  • Preserve associated chats by default and clearly explain that they can reappear if the same project folder is added again; offer any chat archive/delete behavior separately.

I investigated the local files as a workaround. ~/.codex/config.toml contains per-path trust settings, but removing those does not appear to be project removal. The desktop registry is represented across several keys in ~/.codex/.codex-global-state.json (including local-projects, project-order, selected-project, thread-project-assignments, and workspace-root state). Editing only one key would risk stale associations, and the app may rewrite the file while running. That makes manual configuration editing an unsafe, unsupported substitute for a first-class removal operation.

pengusto · 9 days ago

One concrete use case for this API is project identity automation. I want a Codex skill to register a folder, set its display name, and assign an icon and color from a consistent scheme. Today, users have to configure each project manually in the app.

The API could cover:

  • create or register a project
  • read and update its display name, icon, and color
  • list the available built-in icons and colors
  • remove a project registration without deleting its folder

Changing the display name should not rename the backing directory.

Related visual mockup and icon request: #25448