Set up Doomer in Codex

Use this guide after choosing a team or personal skill installation. It covers terminal/TUI and desktop UI sessions on macOS and Linux. Quick reviews do not require a Doomer account.

Choose your environment

Interface	macOS	Linux
Terminal / TUI	Open the repository and start `codex`.	Open the repository and start `codex`.
Desktop / graphical UI	Open the repository in the app and start a local chat.	Use your available Codex graphical client, or the terminal if a desktop client is unavailable.
Remote execution	Install Doomer in the environment that edits the checkout.	Install Doomer in the environment that edits the checkout.

The operating system that matters is where commands run. A macOS app connected to a Linux workspace needs the skill and CLI in that Linux workspace. The agent-led installer selects the matching OS and architecture; you do not need Homebrew or Node.js for that route.

1. Install the skill

Paste this into a Codex chat with your repository open:

text

Read https://doomer.ai/install.md and follow the instructions to set up Doomer in this repository.
Use a team installation so I can commit the skill and share it with my teammates.

For an installation only on your machine, replace the second sentence with “Use a personal installation.” To install manually with Node.js 22.20 or later, run this from the repository root and select Codex and the project scope:

npx skills add doomerlabs/skills --skill doomer-review

Then ask Codex to finish Doomer setup. Commit the generated skill files and skills-lock.json for a team installation. Installing shared instructions does not grant upload permission for teammates.

2. Complete local setup and upload approval

Follow the setup link returned by the agent. Review the upload scope before allowing it: approved reviews send repository snapshots, task context, and the agent's finding responses to Doomer. Each developer makes this choice for their own agent. A previously approved integration can reuse its saved approval.

If setup offers an optional Codex approval-reviewer policy, review the exact proposed text and scope. Saving that policy is separate from upload approval and may require a new chat or reload before Codex uses it. Keep your existing sandbox and approval mode.

3. Configure Doomer hooks

The agent-led setup should run this command in the environment where Codex executes:

doomer hooks --agent codex

If you used the manual installer, ask Codex to run it after installing the CLI. It adds Doomer's lifecycle entries and preserves unrelated hooks. The default file is ~/.codex/hooks.json; when CODEX_HOME is set, it uses that directory's hooks.json. Run setup under the same user and Codex profile as your coding session.

Doomer configures prompt, tool-use, and stop events to track the task and request reviews. Let the installer generate the commands for your installed release and profile instead of copying another machine's hook file.

4. Review and trust hooks

Terminal / TUI

Restart Codex after setup if it has not loaded the new hooks.
Enter /hooks in the Codex conversation, not in your shell.
Open the Doomer entries, inspect their commands, and trust the entries you approve. The list includes labels such as Doomer: capture task and Doomer: review changes.
Return to the repository and start a coding task.

Desktop / graphical UI

Reload or restart the app after setup if needed, and open the same repository and profile.
Select Review hooks when the composer offers it, or open Settings → Hooks.
Inspect and trust the Doomer entries. If your client does not expose this control, use its supported hook-review workflow; do not assume trusting hooks in a different profile applies here.
Start a fresh coding chat in the repository.

Codex skips untrusted non-managed hooks. Changing a hook definition requires reviewing it again. Project-local hooks also require a trusted project. See OpenAI's hook documentation.

5. Verify a review

Give Codex a small, real coding task. Ask it to confirm whether Doomer received a hook callback for this session, then open the quick-review link and check for the agent's responses.

A hook file on disk proves configuration only. A real callback proves activation; a completed review with recorded responses proves delivery. While activation is unverified, the skill can still prepare, submit, read, and respond to reviews through explicit CLI calls.

You’re ready when…

The agent returns a quick-review link, and the review of your latest changes has completed.
Each hypothesis has an accept, reject, or defer decision and an explanation in Feedback. A completed review can also return no hypotheses.
If using hooks, Doomer has received a real callback from this session. Until then, the skill can submit reviews explicitly; installed hooks alone do not prove activation.

Troubleshooting

Symptom	Check
Doomer is missing from `/hooks` or Settings	Check the executing user, `CODEX_HOME`, and the path reported by `doomer hooks --agent codex`; reload the client.
Hooks appear but do not run	Review their trust state. In `~/.codex/config.toml` (or `CODEX_HOME/config.toml`), check the `[features]` section for `hooks = false`. Also check whether managed policy disables non-managed hooks. Ask your administrator about a managed restriction.
Hooks run locally but not remotely	Install and configure Doomer where the remote checkout is edited. Local configuration does not install a remote executable.
Uploads still prompt after setup	Upload approval and Codex's command approval are separate. Check the active profile and any optional reviewer policy; a saved policy does not prove a running chat loaded it.
Setup or a review cannot connect	Check the exact hostname and operation reported by the CLI. Network access is separate from upload approval.

For a local diagnostic report without uploading it, run doomer doctor --repo . --no-upload. Never edit hook trust hashes by hand to force activation.

Before-installation reference screens

These screenshots show where to find hook controls before Doomer is installed. They are troubleshooting references, not examples of a working installation. After setup, look for the Doomer entries and verify a real review using the checklist above.

macOS terminal example, sanitized: unrelated hooks, local paths, and the update notice were removed. Doomer hooks are not installed in this view. After setup, inspect the Doomer entries and their trust state.

macOS desktop example before installation. Open Settings → Hooks to find this screen. After setup and reload, Doomer entries should appear here; this empty state does not confirm installation or activation.

Continue with Run your first quick review, or use the CLI reference for recovery commands.