Set Up Codex in Omarchy

Choose the application, connect its account, and independently inspect the result of one small task. Recorded on Omarchy package 4.0.2-1 with Codex 0.154.0, 14 September 2026. Other versions can have different menus or permission controls.

Before you start

Use a working Omarchy desktop, an internet connection, and access to the chosen provider's service. This guide uses an existing ChatGPT account; it does not promise a particular subscription entitlement or model. Keep the test inside a new project folder.

1. Choose the application

Open Super+Space → Setup → Defaults → Agent → Codex. Selecting the default can install the agent and then launches it. In our clean test VM, Codex was already downloaded by the time we reached the menu.

Read the selected default in a terminal:

omarchy default agent

The command to select it directly is omarchy default agent codex; that command also launches it and can install it. Record your existing choice first if you plan to return to it.

2. Connect the account

On first launch, follow the actual sign-in options. We used Sign in with Device Code: open the displayed address in your browser, sign in to your account, and enter the fresh code from that CLI. Keep the code and account details private. Codes expire; start a fresh attempt rather than using one from a video.

The account step in this recording was completed privately using the authorized browser session. Afterwards, this read-only command confirmed the guest's login:

codex login status

An application choice, account connection, and model selection are separate settings. The provider's authentication instructions explain supported options.

3. Give the task its own directory

mkdir -p "$HOME/Work"
demo_dir=$(mktemp -d "$HOME/Work/first-job.XXXXXX")
cd "$demo_dir"
pwd
ls -la
omarchy agent --inline

The inline launch runs the selected agent in the current terminal. Confirm its displayed path before accepting project trust. The global Super+Shift+Ctrl+A shortcut opens another terminal; in our setup it started in ~/Work, not the specific project shown in the other terminal. Always check the directory.

4. Submit the bounded first job

Turn these three rough notes into a Markdown checklist in start-checklist.md: save the current work; confirm the correct project folder; check the finished result. Use the heading 'Before the next build' and exactly three unchecked items in that order. Only create that file; don't install anything or edit system settings. Stop when done.

Watch the actual action, then inspect the result outside the agent. In the original project terminal:

pwd
cat start-checklist.md
ls -la

Our saved result was:

# Before the next build

- [ ] Save the current work.
- [ ] Confirm the correct project folder.
- [ ] Check the finished result.

We independently compared this file's exact contents and checked that it was the sole file in the practice directory. Its SHA-256 is 7e1261a315780aab51ce2a33e5bd15794fffc5493e5650186d5c8db73e4c44d2. Another run may vary capitalization or punctuation; check the actual acceptance conditions rather than assuming an identical hash. This proves one task in one folder, not general agent reliability or that no other system activity occurred.

5. Understand the controls before a larger task

In the recorded client, /permissions showed Approve for me. The installed CLI help defines it as automatic review of approval requests using the workspace-write sandbox. Automatic review may reject actions. /model is a separate selector inside Codex. We inspected both menus without changing them.

These controls vary across agents and releases; do not assume one provider's launch flags have the same effect in another tool. The Omarchy AI manual explains its integration, while the pinned launcher source shows the version-dependent arguments.

If the result differs

• No selected agent: read back the default and inspect the actual selector/installation message.
• Sign-in expired: start a fresh supported account flow; do not reuse a recorded code.
• Wrong project: stop before requesting changes and launch from the intended folder.
• Request blocked: read the actual approval/sandbox error and requested path; broad access is not the default remedy.
• Missing or incorrect file: inspect the directory, request and generated contents before declaring success.

Keep the practice folder until you have reviewed it. Switching the default agent later does not transfer accounts or undo files.