📌 Before Opening an Issue: Please Read This First

[ilysenko]

Thank you for helping improve ChatGPT Desktop for Linux

Thank you for taking the time to help improve ChatGPT Desktop for Linux.

This project exists primarily to keep the latest upstream ChatGPT Desktop app buildable, installable, and usable on Linux. Reports from users are an important part of that work, especially when they identify reproducible problems affecting installation, startup, updates, or everyday use.

At the same time, every new upstream CODEX.DMG can significantly change the internal application files that this project patches. A fix that works today may require additional maintenance after the next upstream release. To keep that maintenance sustainable, we try to focus the shared issue tracker on concrete problems that affect a meaningful number of users or prevent an important supported workflow from working.

Before opening a new issue, please use the guidance below to check whether the problem belongs to this project and to collect the information needed for us to investigate it effectively.

If the app generally works and the requested change is mainly a personal preference, visual adjustment, or setup-specific integration, a Local Feature may be a better fit. Local Features let you customize or patch the app for your own environment without adding permanent maintenance work to the shared project.

Should this be a repository issue?

Please open an issue when all of the following are true:

• The problem still occurs on the latest main branch and the latest supported upstream DMG.
• It is caused by this Linux wrapper, its patches, launcher, packaging, updater, or documented Linux runtime behavior.
• It has clear reproduction steps and observable expected and actual results.
• It affects a broad supported path or is serious enough to make that path unusable.
• You have searched existing issues and followed the relevant troubleshooting guidance.

Please think carefully before opening an issue when the app otherwise works and the request is mainly:

• a personal visual preference, such as a font, transparency, spacing, theme, or window decoration;
• a workflow or integration useful only for a particular setup;
• a cosmetic quirk limited to one unusual compositor configuration;
• upstream ChatGPT behavior, an account restriction, a server-side rollout, or a third-party website problem;
• behavior from an old repository revision, old package, or old DMG;
• a speculative improvement without a reproducible failure or evidence of broad user impact.

A narrowly scoped report can still be valid, but it must demonstrate why the project should permanently own its maintenance cost across future DMGs. “This would be nice on my system” is not enough by itself.

Before submitting

1. Update the repository and rebuild against the latest supported DMG.
2. Reproduce with all optional Linux Features disabled, unless the report is specifically about one of those features.
3. Remove or disable any user-local patches and confirm the problem remains.
4. Search open and closed issues for the same symptom and error text.
5. Reduce the report to the smallest repeatable sequence of actions.
6. Confirm that the behavior belongs to this Linux project rather than the upstream app, Codex CLI, account, network, compositor, or another external service.

Information every bug report should include

Please include:

• A short, factual summary of the failure.
• Exact reproduction steps, including the command used to install, build, update, or launch.
• Expected behavior and actual behavior.
• Whether it happens every time, and the earliest known working version if applicable.
• Linux distribution and version.
• Desktop environment or window manager and version.
• Session type: X11, XWayland, or native Wayland (echo "$XDG_SESSION_TYPE").
• Installation method: source build, .deb, .rpm, pacman package, AppImage, Nix, or updater-built package.
• Repository commit (git rev-parse HEAD) and ChatGPT Desktop/upstream build information.
• GPU model and driver version for rendering, freezing, scaling, or compositor problems.
• Enabled features. For native installs, attach /opt/codex-desktop/.codex-linux/linux-features-staged.json when present; for local builds, attach codex-app/.codex-linux/linux-features-staged.json.

Prefer text and JSON attachments over screenshots of terminal output. Preserve complete error lines and timestamps.

Logs and reports to attach

Attach only the files relevant to the failing stage.

Launch, blank window, CLI discovery, or webview startup

sed -n '1,240p' ~/.cache/codex-desktop/launcher.log

Updater or package promotion

codex-update-manager status --json
codex-update-manager diagnose --json
sed -n '1,240p' ~/.local/state/codex-update-manager/service.log
systemctl --user status codex-update-manager.service --no-pager

Build failure or suspected upstream patch drift

Include the complete terminal output from the failing command and attach the applicable reports:

• codex-app/.codex-linux/patch-report.json
• dist-next/rebuild/patch-report.json
• dist-next/rebuild/rebuild-report.json
• the newest reports/patch-report.json below ~/.cache/codex-update-manager/workspaces/ for updater rebuilds

Scaling or HiDPI problems

./codex-app/start.sh --diagnose-scaling
# Native package:
/opt/codex-desktop/start.sh --diagnose-scaling

For Computer Use problems, also include the relevant doctor output described in the Linux Computer Use documentation.

Protect private data

Review every attachment before posting. Remove access tokens, cookies, credentials, private conversation content, email addresses, and other personal data. Do not upload Codex.dmg, extracted upstream application bundles, app.asar, or other copyrighted upstream payloads. Redact secrets without removing the surrounding error context needed to diagnose the problem.

Use Local Features for personal fixes and experiments

If a change is useful mainly for your own environment, you can implement it as a private Local Feature under the git-ignored directory:

linux-features/local/<feature-id>/

Local Features use the same feature contract as repository features and can carry patches, resources, runtime hooks, and package hooks without adding permanent maintenance work to the shared project. See the Linux Features documentation.

If your Local Feature later proves broadly useful, works against the current DMG, preserves the default feature-off path, and you are prepared to help maintain it when upstream changes, you may open a focused proposal or pull request for wider inclusion.

What happens to incomplete or out-of-scope reports?

Issues without reproduction steps, current-version evidence, or the required diagnostics may be closed while waiting for a complete report. Requests that are upstream-owned, personal customizations, or too narrow to justify ongoing repository maintenance may be closed as out of scope or not planned.

Thank you for helping keep the issue tracker focused on problems that can be verified, maintained, and solved for the wider Linux user base.