> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_10/prd_phase_10.md). # PRD Phase 10: Codex Product Integration **Status**: Complete **Sessions**: 4 **Estimated Duration**: 4-8 days **Progress**: 4/4 sessions (100%) *** ## Overview Phase 10 wires the provider-neutral Codex foundation into the product surface. It owns CLI provider selection, safe Codex hook installation and uninstall, Codex diagnostics, server lifecycle ingest, and web labels and filtering. The phase must keep installer behavior reversible and respectful of user-owned Codex configuration. FactionOS may merge managed hooks, create backups, and remove its own managed hooks, but it must not mutate Codex auth, provider, telemetry, model, profile, or OpenAI API settings. Sessions 03 and 04 are complete and validated. Phase 10 is complete and ready for archive. *** ## CLI Command Shape Maintain backward compatibility: ```bash factionos init factionos init --cli claude factionos init --cli codex factionos init --cli all factionos install --cli codex factionos uninstall --cli codex factionos uninstall --cli all factionos doctor factionos status ``` Default `factionos init` should remain Claude for one release unless a later session explicitly resolves the open question differently. Add aliases only after the flag path is stable: ```bash factionos codex init factionos codex uninstall ``` *** ## Codex Install Behavior `factionos init --cli codex` should: 1. Ensure `~/.factionos/`, `sessions/`, and `spool/` exist. 2. Write or merge `~/.factionos/settings.json` with `cli: "codex-cli"` only when the user selected Codex as the default local agent CLI. 3. Resolve the hook package root. 4. Read `apps/hooks/hooks.codex.json`. 5. Create `~/.codex/` if missing. 6. Back up the first raw `~/.codex/hooks.json` to `~/.codex/hooks.backup.factionos.json` when no FactionOS backup exists. 7. Parse existing Codex hooks. If malformed, preserve the backup and write a fresh hooks object, matching the current Claude malformed-settings policy. 8. Remove only FactionOS-managed Codex command hooks. 9. Merge the managed Codex hook map with user-owned hook entries. 10. Interpolate the absolute hook package root and prepend `FACTIONOS_CLI=codex-cli`. 11. Include `FACTIONOS_SERVER_URL`, `FACTIONOS_AUTH_TOKEN` when present, `FACTIONOS_FACTION` when selected, and `FACTIONOS_HOME` only when set. 12. Write `~/.codex/hooks.json` atomically. 13. Print next steps that include starting FactionOS, launching Codex, and using Codex `/hooks` to review and trust the new hooks. The installer must not write OpenAI API keys, ChatGPT auth config, model providers, telemetry, profiles, or Codex model settings. *** ## Codex Uninstall Behavior `factionos uninstall --cli codex` should: * Restore the FactionOS-created Codex hooks backup if present. * Otherwise surgically remove only FactionOS-managed hook commands from `~/.codex/hooks.json`. * Preserve user-owned Codex hooks and inline config hooks. * Leave `~/.factionos` session, spool, logs, archive, and browser state alone. * Report malformed `~/.codex/hooks.json` without overwriting it unless a backup restore is available. *** ## Diagnostics `factionos doctor` and `factionos status` should report: * Claude hook install posture. * Codex hook install posture. * Codex hooks file presence and JSON validity. * Count of FactionOS-managed Codex hook commands. * Whether `~/.codex/config.toml` appears to set `features.hooks = false` locally, if this can be detected without unsafe TOML rewriting. * A guidance line when hooks are installed but may need trust review: `Open Codex and run /hooks to trust newly installed FactionOS hooks.` * No raw hook command bodies beyond a compact managed/unmanaged count and provider label. *** ## Server Ingest Details Update `apps/server/src/lib/eventIngest.ts` so Codex events use existing hero and mission paths: * Recognize `SubagentStart` with `type: "subagent_spawn"`. * Normalize `toolName` and Codex `tool_name` to the existing `tool` field. * Normalize `turnId` and Codex `turn_id` only as bounded metadata where needed. * Preserve current `eventName ?? hook` dispatch behavior. * Keep unknown Codex named events as bounded opaque `mission_event` frames. * Ensure `cli: "codex-cli"` is accepted as a real first-class CLI value, not a generic string fallback. *** ## Web And UX Details Update web surfaces so Codex is visibly first-class: * Add CLI display labels: `Claude Code`, `Codex CLI`, `Cursor`, `OpenCode`, `OpenClaw`, `Web`. * Add a Codex visual treatment that fits the existing cockpit style without creating a new palette system. * Ensure mission log filters, hero cards, hero detail, leaderboard, standings, exports, replay, and search handle `codex-cli`. * Treat OpenAI model IDs as external by default unless the product adds a provider-neutral model tier taxonomy. * Make tool usage categorize `apply_patch` as file edit, `Bash` as terminal, and `mcp__*` as custom/MCP. * Update fixture builders and tests that default to `claude-code` so Codex is covered without changing every unrelated test. * Keep raw prompt, command, and path redaction unchanged in replay/export. No landing page or marketing surface is needed. The first user-visible value is that a Codex session appears in the existing cockpit. *** ## Progress Tracker | Session | Name | Status | Est. Tasks | Validated | | ------- | ---------------------------------------------- | -------- | ---------- | ---------- | | 01 | CLI Provider Selection and Installer Split | Complete | \~14-22 | 2026-05-31 | | 02 | Codex Hook Install, Uninstall, and Diagnostics | Complete | \~18-25 | 2026-05-31 | | 03 | Server Ingest Codex Lifecycle | Complete | \~16-24 | 2026-05-31 | | 04 | Web Codex Awareness | Complete | \~14-22 | 2026-05-31 | *** ## Completed Sessions 1. Session 01: CLI Provider Selection and Installer Split 2. Session 02: Codex Hook Install, Uninstall, and Diagnostics 3. Session 03: Server Ingest Codex Lifecycle 4. Session 04: Web Codex Awareness *** ## Upcoming Sessions None. Phase 10 is complete and archived. *** ## Objectives 1. Add explicit `--cli claude|codex|all` behavior across CLI lifecycle commands. 2. Install and uninstall user-level Codex hooks safely and idempotently. 3. Persist Codex lifecycle events into server missions and heroes. 4. Render Codex heroes, tools, filters, replay, and exports without fallback labels or privacy regressions. 5. Validate and close the Codex web surface without phase regressions. *** ## Prerequisites * Phase 09 completed and validated. * Codex hook map and hook handlers available for installer wiring. * Existing Claude installer, status, doctor, and uninstall behavior captured in tests or fixtures. * Server and web redaction contracts reviewed before adding Codex UI surfaces. *** ## Technical Considerations ### Architecture CLI provider selection should dispatch into provider-specific install and uninstall modules while keeping shared status, doctor, backup, logging, and privacy behavior compact. Server ingest should normalize Codex fields into existing hero and mission event paths rather than creating a separate event store. ### Technologies * JavaScript CLI in `apps/cli` * Hook maps and handlers in `apps/hooks` * Node 20 Express ingest in `apps/server` * React/Vite cockpit in `apps/web` * Shared protocol contracts in `packages/protocol` ### Risks * Installer corruption of user Codex hooks: backup first, merge managed entries only, and remove only managed commands. * Hook trust can block first-run events: status and doctor should surface likely trust-pending posture without bypassing Codex review. * Web labels can overfit Claude assumptions: model and tool display should stay provider-neutral. ### Relevant Considerations * \[P03-apps/cli+apps/hooks] **Lifecycle state is local and file-based**: installer and diagnostics changes must keep local state recoverable. * \[P03] **Stable docs are the current contract**: CLI behavior and privacy claims must be reflected in docs before release. * \[P07] **Redaction is boundary-specific**: status, doctor, server ingest, web, replay, and export all need Codex-specific minimization checks. *** ## Success Criteria Phase complete when: * [ ] All 4 sessions completed and validated. * [ ] `factionos init --cli codex` installs managed Codex hooks safely. * [ ] `factionos uninstall --cli codex` preserves user-owned Codex hooks. * [ ] A fixture-driven Codex lifecycle materializes a `codex-cli` hero and mission. * [ ] Web surfaces render Codex labels, tools, filters, replay, and export without privacy regressions. *** ## Dependencies ### Depends On * Phase 09: Codex Provider-Neutral Foundation ### Enables * Phase 11: Codex Hardening and Validation --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_10/prd_phase_10.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.