Use PDMShell with ChatGPT and Codex

PDMShell offers an embedded ChatGPT preview and a separate external Codex MCP integration. Both can discover commands and request approved operations; the embedded preview runs commands in your selected standalone tab.

Important

Embedded session tools require a build that includes Use command catalog and run in the selected session in AI setup. This is a local desktop integration, not an integration into the ChatGPT website or Microsoft Copilot.

ChatGPT inside PDMShell

Available from 4.0.72. PDMShell 4.0.78 remembers the ChatGPT connection and selected model, renders selectable Markdown replies, and improves approval choices. Start with AI inside PDMShell for screenshots, the model selector, draft Run/Use actions, Ollama, and the Vault Script Editor workflow.

1. Open AI Preview, then the settings gear.
2. Choose ChatGPT · Codex sign-in. Let setup locate the Codex CLI, or browse to codex.exe. The Codex desktop app is not required.
3. Complete the browser sign-in with a ChatGPT account that has Codex access, then choose a model. PDMShell remembers the saved sign-in and selected model for reconnecting. This flow does not ask for an OpenAI API key; account access and usage limits still apply.
4. Optionally enable Use command catalog and run in the selected session, then select Done. Leave it off for drafting and explanations only.
5. Select the tab you want to work in and describe the task. ChatGPT can read the installed command catalog, inspect syntax and parameters, check session state, and propose execution.
6. Review the session name and exact command in each approval dialog. PDMShell 4.0.78 shows executable commands directly instead of JSON-wrapped arguments. Allow once & share result approves that call and sharing its result with OpenAI. You can remember read-only approval, or approve one exact command for the current chat and session. Deny, Escape, or closing the dialog executes nothing for that call.

Approved commands use the selected tab's normal console runner, existing vault login, current folder, and session variables. Results and errors appear in the console/history and return to ChatGPT. Unsaved script text and unfinished console input are preserved. There is no second vault session or separate MCP process for embedded execution.

Commands outside the remembered read-only approval or exact-command approval still require review. Results can contain vault names, file paths, usernames, metadata, and command output; only share data your organization permits. Never enter passwords or license keys in chat. Existing standalone command permissions and MCP license/trial checks remain in effect.

Switching tabs starts fresh AI context on the next message. A pending call cannot silently move to another tab, and busy tabs reject new calls. Clear text clears the displayed transcript only. New chat or disconnecting clears AI context and chat-scoped approvals without logging out of your tab. Stop requests cooperative cancellation; it cannot undo completed changes and some PDM operations must finish before they stop. Check the console and vault before retrying.

PDMShell exposes only its reviewed session tools: built-in shell execution, file editing, web tools, other MCP servers, and runtime permission grants remain disabled. Session tools use the Codex app-server's experimental dynamic-tool interface, so keep the CLI current. If tool-enabled setup fails, update the CLI or disable session tools to use drafting mode. See the official app-server documentation.

For the same session workflow with an Anthropic API key, see Claude API setup. Use the compact provider-logo menu beside Settings to switch saved ChatGPT, Claude and Ollama connections. Switching providers starts a new conversation; the previous provider's messages and chat-scoped approvals are not forwarded.

External Codex MCP integration

The remaining sections describe the separate external-client integration introduced in PDMShell 4.0.62. External Codex uses its own MCP session rather than the selected standalone tab. No separate API key is required for the local MCP connection. Existing PDMShell licensing and SOLIDWORKS PDM permissions still apply.

Settings - AI Integrations

Open PDMShell, then go to Settings > AI Integrations.

Action	What it does
Connect to Codex	Configures or repairs the installer-managed Codex MCP connection.
Test local MCP connection	Starts the local MCP executable and checks server communication, version reporting, and command discovery.

Results and errors appear inline on the settings page.

The connection test does not log into a vault, execute PDM commands, or start a license trial. It verifies the local MCP server, not whether Codex has loaded or approved the connection.

Follow the restart instruction shown on the settings page after setup.

Codex configuration

PDMShell can configure Codex automatically when Codex already has a configuration directory.

Configuration location:

%USERPROFILE%\.codex\config.toml

If CODEX_HOME is set to an absolute path, PDMShell uses that directory instead.

Codex setup behavior:

• Installation and updates configure Codex only when the configuration directory already exists.
• Uninstall removes only the installer-managed PDMShell Codex entry.
• Existing unrelated configuration, comments, enabled or disabled settings, and approval settings are preserved.
• Configuration changes create uniquely named backups.
• Existing manually configured PDMShell entries are left unchanged; setup reports the conflict.
• Invalid or ambiguous configuration is left unchanged.
• Setup failures are logged without blocking installation.
• New entries request tool approval, use a 30-second startup timeout, and use a 1,800-second tool timeout.

Keep the generated managed-block comments in config.toml. PDMShell uses those comments so updates and uninstall can safely recognize the managed entry.

Restart Codex after configuring or repairing the connection.

Command-line switches

Switch	Purpose
--configure-codex	Explicitly configure or repair the Codex connection.
--configure-codex-if-present	Installer mode; skips absent Codex configuration directories.
--unconfigure-codex	Remove only the installer-managed Codex connection.
--test-connection	Run the non-mutating local MCP test.

Troubleshooting

• Codex does not show PDMShell: Run Connect to Codex, restart Codex, and confirm %USERPROFILE%\.codex\config.toml exists.
• CODEX_HOME is ignored: Confirm CODEX_HOME is an absolute path. Relative paths are not used for setup.
• Manual PDMShell entry already exists: PDMShell leaves it unchanged and reports the conflict. Remove or rename the manual entry if you want PDMShell to manage the connection.
• Setup fails during install: Installation continues. Check the MCP setup log.
• Local test passes but Codex does not use tools: Restart Codex and approve the connection/tools inside Codex. The local test verifies the server, not Codex approval state.

Log location:

%LOCALAPPDATA%\Blue Byte Systems\PDMShell\Logs\mcp-setup.log

Signed packages and automated MCP setup tests were verified for this release. Live installer and UI validation may still be required in your environment.

Command discovery and large results

PDMShell 4.0.62 expands MCP command details so Codex can see more examples, parameter types, constraints, and CSV guidance before it runs a command.

• Shared-search commands that support CSV query input document the <Path.csv> format.
• runswmacro -list is described as a path parameter, not a Boolean switch.
• pdmshell_discover_values helps discover supported vault-specific values.
• pdmshell_read_result reads large command results by page. Stored results are temporary and bounded, and truncation is reported explicitly.
• Passwords are redacted from command output and errors.
• Commands without active implementations, such as toolbox, rebuild, and preview, are shown as unavailable through MCP.

Available tools

You normally do not need to call these tools by name. Codex chooses the appropriate tool for your request.

Tool	What it does
pdmshell_version	Shows the installed PDMShell and MCP server versions.
pdmshell_license_status	Shows the local PDMShell license status.
pdmshell_list_vaults	Lists PDM vault views available on this computer.
pdmshell_list_commands	Lists available PDMShell commands.
pdmshell_describe_command	Explains a command and all its parameters.
pdmshell_describe_search	Explains PDMShell searches and provides examples.
pdmshell_describe_expressions	Returns the shared placeholder/function reference with aliases, context requirements and side effects.
pdmshell_execute	Runs one PDMShell command in the current session.
pdmshell_discover_values	Discovers supported vault-specific values.
pdmshell_read_result	Reads paginated large command results.

For Claude Desktop setup, see Use PDMShell with Claude Desktop. Continue with Advanced Search, the Command Reference, or the PDMShell release notes.