Skip to content

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

Open
Open
Codex Desktop: add API/CLI support for creating and registering projects#25385
Labels
CLIIssues related to the Codex CLIappIssues related to the Codex desktop appapp-serverIssues involving app server protocol or interfacesenhancementNew feature or request

Description

@Sereja3578
Sereja3578
opened on May 31, 2026

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

Activity

  1. github-actions
    added
    enhancementNew feature or request
    appIssues related to the Codex desktop app
    CLIIssues related to the Codex CLI
    app-serverIssues involving app server protocol or interfaces
    on May 31, 2026

  2. Sereja3578 commented on May 31, 2026

    @Sereja3578
    Sereja3578
    on May 31, 2026
    Author

    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.

  3. devansh-jain-18 commented on Jul 10, 2026

    @devansh-jain-18
    devansh-jain-18
    on Jul 10, 2026

    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.

  4. drock commented on Jul 31, 2026

    @drock
    drock
    on Jul 31, 2026 – with ChatGPT Codex Connector

    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.

  5. pengusto commented on Aug 18, 2026

    @pengusto
    pengusto
    on Aug 18, 2026

    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

  6. kjgryboski commented on Aug 28, 2026

    @kjgryboski
    kjgryboski
    on Aug 28, 2026

    Confirmed on Codex Desktop for macOS: this remains a concrete automation gap even though the underlying app-server protocol already exposes idempotent project/create.

    Reproduction

    1. Start a standalone app-server client and call project/create for an existing absolute directory.
    2. The call succeeds and is idempotent in that app-server instance.
    3. Ask Codex Desktop to create a task using the returned project ID/root.
    4. Desktop rejects it because its saved-project registry does not contain that entry.
    5. Re-listing projects shows that the standalone app-server registry and the Desktop-visible saved-project registry are not the same durable registry.

    Opening the directory once with codex app <absolute-path> does register it in Desktop, but that launches/navigates UI and is not a safe agent-facing primitive.

    Narrow requested contract

    Please expose an agent/tool API equivalent to:

    ensure_project(absolutePath)

    with these semantics:

    • canonicalize the input and require an existing absolute directory;
    • call the Desktop-owned idempotent project/create path;
    • return the exact saved project ID and canonical root;
    • write nothing inside the repository (including no .agents/ bootstrap files);
    • reject if the returned saved root differs byte-for-byte from the canonical requested root.

    This would let an agent safely route a task to an exact linked worktree without launching UI, guessing a project ID, or modifying the repository. Until such an API exists, the safe fallback is one explicit folder registration followed by exact root verification; otherwise automation should return a clean blocker.

  7. NAEL592 commented on Sep 15, 2026

    @NAEL592
    NAEL592
    on Sep 15, 2026

    Adding a current Windows desktop use case: I asked Codex to fully organize the workspace. The agent could list projects, move them between sidebar sections, and archive inactive chats, but its available app tools had no operation to create/register a project or remove a saved project entry.

    Please expose first-class agent tools for both operations, backed by the same saved-project registry used by the desktop UI:

    • Create/register a project with an explicit name, folder, and host, returning the stable project ID.
    • Remove/unregister a project by ID, preserving its folders and files by default.
    • Preserve associated chat history and explicitly define whether chats remain accessible outside the project or are archived.
    • Detect running work and avoid interrupting it without explicit authorization.
    • Return structured, repeatable results that can be verified through list_projects.

    This would let Codex complete user-authorized workspace organization through supported tools. Please document support for local, remote, and ChatGPT projects.

  8. squizzeak commented on Sep 16, 2026

    @squizzeak
    squizzeak
    on Sep 16, 2026 – with ChatGPT Codex Connector

    I’d also like to see this capability, specifically from ChatGPT itself: the assistant should be able to take existing chats and file/move them into Projects on the user’s behalf, similar to how chats can be organized into sections. An official project-management action exposed to ChatGPT/Codex would make large chat histories much easier to organize.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    CLIIssues related to the Codex CLIappIssues related to the Codex desktop appapp-serverIssues involving app server protocol or interfacesenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions