Targeted recovery steps
Find the failed layer before changing shared state.
Open this resource →Codex handbook
Connect Codex and confirm native trust
Establish the device connection, review hooks in Codex, and inspect supported policy checks in a real repository session.
Betterloop uses the Codex plugin for approved resources and supported hook checks. Your provider account remains connected through Codex native authentication.
01 / Codex handbook
Bring installation, trust, and activation together
Check for Node.js 22 or later and npm. Obtain the personal enrollment command. Confirm the setup release supplied for your organization.
Setup reuses an installed Codex copy. It asks before installing a missing selected copy. Neither route depends on optional Mimir.
npx @betterloop/setup setup --harness codexFinish native Codex sign-in if needed. Betterloop does not copy the native credential file. Enrollment does not supply a provider account.
The shared native plugin installation is retained. The plugin installation result and native hook activation result describe separate steps.
Review what Codex is being asked to trust
Open /hooks inside Codex. Read the Betterloop definitions. Complete native trust for those hooks. Start a new session in the approved working repository.
Reload plugins if the host supports reload. Activation requires an actual supported hook invocation. The existence of installed files is insufficient.
Read the repository-specific inspection
npx @betterloop/setup doctor --harness codex --project /path/to/repositoryRead provider access, plugin state, signed cache, activation, and individual control support. Keep each result in the acceptance record.
If activation is pending, check trust and hook enablement. A signed-content refresh does not approve native hook trust for you.
02 / Codex handbook
Understand the checks available to this session
A covered tool event needs enabled trusted hooks for conditional restrictions. The host can permit execution after hook failures or timeouts.
For a covered exec action, the shell gate checks a literal executable. Existing shell sessions and hosted tools are outside that check.
The executable must satisfy all applicable organization and team program restrictions. The associated tool permission is evaluated independently.
rg --files docs
rg -g '*.md' docsQuoted patterns and escaped spaces are supported arguments. Pipelines, substitutions, redirection, and command chains are rejected as ambiguous syntax.
Executable approval does not authorize each argument individually. A permitted program can start other code. This mechanism does not isolate operating-system processes.
Keep model requirements in the rollout decision
The Codex adapter implements neither approved-model restrictions nor maximum reasoning limits. A configuration value cannot add a missing native action boundary.
If either control is mandatory, review compatibility with the administrator. The device cannot be accepted as fully governed for that requirement.
Interpret resources and reports at their actual scope
Skills remain advisory. Other local skills can still be discovered. Diagnostic counts exclude source paths and content from upload.
Session and policy metadata require supported hook observation. Reporting delivery is best effort. Full commands, arguments, local paths, prompts, and source are excluded.
These records are reports from the connected client. They supply neither independent device attestation nor proof that the agent obeyed every instruction.
03 / Codex handbook
Record support by control
| Configured control | Codex interpretation |
|---|---|
| Allowed tools | A trusted enabled hook can check a supported tool event. The result is conditional. |
| Allowed shell programs | A covered exec call can check its literal executable. Ambiguous syntax is rejected. Existing shells remain outside this check. |
| Approved models | The Codex integration has no implementation for this control. |
| Maximum reasoning level | The Codex integration has no implementation for this control. |
| Approved skills | Instructions are advisory and do not exclude other local skill discovery. |
| Session and policy events | Supported hooks can produce client metadata. Delivery is best effort and observation remains conditional. |
| Resource names and bounded failure-code reporting | This reporting feature is absent from the Codex adapter. |
A working provider account and trusted plugin do not change these support boundaries. Assess the agent against the controls your rollout actually requires.
04 / Codex handbook
Add one optional catalog selection
Open the device-connected catalog after enrollment. Browse the reviewed resource files. The browser is read-only and prepares a local installation command.
betterloop library browser
betterloop library list
betterloop library statusChoose the approved resource identity and exact version. Read its dependencies. Check whether native sign-in or hook trust is required before running the prepared command.
A new MCP definition can still need provider authorization. Account access does not grant permission to every exposed tool. Verify discovery separately.
After a resource changes hook trust requirements, complete the native trust step. Open a fresh session. Run doctor for the same repository.
If another agent installed successfully, keep its selection. Repair only the failed Codex step. Repeat the resource operation for Codex after that repair.
05 / Codex handbook
Follow the failure to the state that needs repair
| Observed issue | State involved | Action to take |
|---|---|---|
| Files installed but activation absent | Native trust or a session event | Read /hooks. Complete trust. Open a new session. Inspect doctor afterward. |
| Provider access unavailable | The native Codex account | Sign in through Codex without replacing the working device enrollment. |
| Release invalid or expired | The local signed cache | Refresh signed content. Inspect validity and recorded revocations. |
| One catalog selection failed | Codex installation, trust, or authentication | Complete the missing Codex step. Repeat the resource command for Codex alone. |
| Mandatory model restriction unavailable | The implemented adapter controls | Reassess the client choice and required control with the administrator. |
| Connection names another team | Organization/team enrollment | Disconnect the old connection explicitly. Enroll in the intended team. Open fresh sessions. |
betterloop sync --harness codex --project /path/to/repository
betterloop doctor --harness codex --project /path/to/repositoryIllustrative diagnosis: trust is unfinished
A Harbor developer sees the Codex plugin installed. Doctor still shows activation pending. The developer reads /hooks and finds the Betterloop trust step unfinished.
They review the definitions and complete native trust. They open a new search-api session. A supported hook invocation supplies activation evidence.
They repeat doctor and examine each required control. Trust does not add the missing model and reasoning checks. The rollout record keeps those limitations visible.
The --yes option can accept installation of a missing harness. It cannot complete native sign-in or trust. Review these results separately.
Use sync for a release refresh. Use betterloop uninstall --harness codex to stop managing Codex while retaining the native agent, credentials, and unrelated plugins.
Disconnect revokes the full device connection and requires fresh enrollment to reconnect. After changing resource credentials or trust, run sync and doctor.
Repeat the resource update when its client report needs refreshing. A changed credential alone does not establish a new installation or discovery result.