> 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/sessions/phase10-session01-cli-provider-selection-and-installer-split/spec.md). # Session Specification **Session ID**: `phase10-session01-cli-provider-selection-and-installer-split` **Phase**: 10 - Codex Product Integration **Status**: Not Started **Created**: 2026-05-31 **Package**: apps/cli, apps/hooks **Package Stack**: JavaScript CLI commands, hook installer fixtures, provider hook maps, Vitest node tests, Biome checks *** ## 1. Session Overview This session starts Phase 10 by adding explicit CLI provider selection to the FactionOS command line while preserving the current default Claude Code installation behavior for one release. Phase 09 already added provider-neutral protocol vocabulary, hook runtime normalization, and a source-controlled Codex hook map. Session 01 now creates the CLI routing boundary that lets later Codex installation work plug into the product without another command-shape migration. The work spans `apps/cli` and `apps/hooks`. In `apps/cli`, the session introduces `--cli claude|codex|all` parsing, help text, provider routing, and focused tests for init/install, uninstall, status, and doctor behavior. In `apps/hooks`, the session keeps Claude installer regression coverage stable and updates package documentation so the Codex map is described as source readiness until Session 02 implements safe user-level `~/.codex/hooks.json` mutation. This session does not implement Codex hook JSON merge, backup, restore, status counting, or trust-review diagnostics. Codex and `all` routing should be explicit and deterministic, but actual Codex install/uninstall file mutation belongs to Phase 10 Session 02. The main outcome is a tested provider-aware CLI boundary with no change to default Claude behavior and no mutation of Codex auth, provider, telemetry, model, profile, or OpenAI API settings. *** ## 2. Objectives 1. Add validated `--cli claude|codex|all` provider selection across provider-aware CLI commands. 2. Split Claude-specific install and uninstall behavior from provider-neutral command routing. 3. Add deterministic Codex and `all` routing placeholders without writing Codex hook configuration yet. 4. Update help, README, and focused tests for provider selection, defaults, invalid input, and no-overclaim wording. *** ## 3. Prerequisites ### Required Sessions * [x] `phase09-session01-contracts-and-naming-baseline` - provides `codex-cli`, provider-neutral hook event names, and CLI display metadata ownership. * [x] `phase09-session02-hook-runtime-normalization` - provides provider-aware hook runtime helpers and Codex-shaped payload handling. * [x] `phase09-session03-codex-hook-map-and-codex-specific-handlers` - provides `apps/hooks/hooks.codex.json`, Codex-specific handler coverage, and hook map readiness. * [x] `phase03-session06-cli-diagnostics-and-recovery-controls` - provides compact CLI diagnostics and local recovery boundaries. * [x] `phase01-session03-cli-lifecycle-parity` - provides current CLI lifecycle command behavior and default install flow. ### Required Tools/Knowledge * Node 20+ and npm workspace dependencies. * Current `apps/cli/src/index.js` flag parsing and top-level command dispatch. * Current `apps/cli/src/commands/init.js`, `uninstall.js`, `status.js`, and `doctor.js` behavior. * Current `apps/hooks/hooks.json`, `hooks.claude.json`, `hooks.codex.json`, and installer script tests. * Phase 10 command-shape requirements and Codex install deferral boundaries. ### Environment Requirements * No Codex, Claude, OpenAI, Anthropic, Cloudflare, hosted, or provider credentials are required. * Tests must use isolated temporary homes for CLI and hook installer fixtures. * Provider diagnostics must stay compact and must not print raw hook command bodies, local paths, tokens, settings contents, prompts, or payloads. *** ## 4. Scope ### In Scope (MVP) * CLI users can select a local agent CLI - add `--cli claude|codex|all` parsing for `init`, `install`, `uninstall`, `status`, and `doctor`. * Existing users keep default behavior - preserve current `factionos init` and `factionos install` as Claude-only setup unless a provider flag is supplied. * Installer code is provider-routed - move Claude-specific install behavior behind an explicit provider installer boundary while keeping backup, merge, atomic write, and env behavior stable. * Uninstall code is provider-routed - route Claude uninstall behavior through provider selection while preserving backup restore and surgical removal behavior. * Codex selection is recognized safely - accept Codex and `all` values at the routing layer, return explicit deferred or unavailable behavior where Session 02 owns mutation, and avoid writing `~/.codex/hooks.json`. * Provider-aware diagnostics are accepted - let `status` and `doctor` understand provider filters and print compact provider posture without raw commands or settings dumps. * Help and docs are synchronized - update command strings and README text without implying custom Codex slash commands or completed Codex hook installation. * Focused tests cover parser, help, routing, invalid provider input, default Claude behavior, and no Codex mutation. ### Out of Scope (Deferred) * Codex `~/.codex/hooks.json` merge, backup, restore, and atomic write behavior - *Reason: Phase 10 Session 02 owns safe Codex hook installation and uninstall.* * Codex managed-hook counting and `features.hooks = false` TOML detection - *Reason: Session 02 owns full Codex status and doctor diagnostics.* * Project-local `.codex/` generation or trust automation - *Reason: later sessions own installation scope and validation; users must review hooks with `/hooks`.* * `factionos codex init` and `factionos codex uninstall` aliases - *Reason: the PRD defers aliases until the flag path is stable.* * Server ingest, web labels, replay, export, or UI behavior - *Reason: Phase 10 Sessions 03 and 04 own server and web product integration.* * Mutating Codex auth, provider, telemetry, model, profile, API key, or OpenAI account settings - *Reason: explicitly excluded by Phase 10 safety boundaries.* *** ## 5. Technical Approach ### Architecture Centralize provider selection in `apps/cli/src/lib/cliProvider.js`. The helper should parse `--cli`, default to `claude` for install/init, validate the accepted values, expand `all` into ordered provider steps, and return compact error labels for unsupported values. Command handlers should consume this helper instead of reading provider flags ad hoc. Extract Claude setup into a provider installer module while preserving the current behavior in `runInit`: create `~/.factionos/`, write settings atomically, back up Claude settings once, merge managed hooks, preserve user-owned hooks and env values, and print existing next steps. Add a Codex provider module that exposes the same shape but returns explicit deferred behavior without touching Codex files. This keeps Session 02 focused on replacing the deferred Codex implementation with real backup and merge logic. Update `uninstall`, `status`, and `doctor` to accept provider selection without broadening sensitive output. Claude uninstall should preserve the existing backup restore and surgical removal semantics. Codex diagnostics in this session can report planned or deferred posture only; they must not claim installed support or print hook command bodies. Tests should prove invalid provider input fails early with a compact message, `install` remains an alias for `init`, default behavior stays Claude-only, and `--cli codex` does not create or overwrite Codex hook state. ### Design Patterns * Provider router: command handlers route through one provider plan instead of embedding provider-specific branching. * Backward-compatible default: absence of `--cli` means Claude for install/init during this release. * Deferred implementation module: Codex returns a deterministic not-yet-implemented result until Session 02 adds mutation. * Atomic local writes: preserve temp-file-plus-rename and backup-first behavior for Claude state. * Compact diagnostics: provider posture uses labels, counts, and booleans only. * Negative mutation tests: assert Codex selection does not touch `~/.codex` before Session 02. ### Technology Stack * JavaScript ES modules in `apps/cli` and `apps/hooks`. * Node process and direct module fixtures for CLI tests. * Vitest node tests through the root `vitest.config.ts`. * Biome formatting and linting. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ------------------------------------- | ------------------------------------------------------------------------------- | ---------- | | `apps/cli/src/lib/cliProvider.js` | Provider flag parsing, validation, defaults, labels, and `all` expansion | \~120 | | `apps/cli/src/lib/providerPosture.js` | Compact provider posture helpers for CLI diagnostics without raw command output | \~120 | | `apps/cli/src/installers/claude.js` | Claude-specific install and uninstall boundary preserving current behavior | \~240 | | `apps/cli/src/installers/codex.js` | Deferred Codex installer/uninstaller boundary with no Codex file mutation | \~90 | | `apps/cli/tests/cliProvider.test.js` | Focused parser, routing, invalid provider, and deferred Codex tests | \~180 | ### Files to Modify | File | Changes | Est. Lines | | ----------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------- | | `apps/cli/src/index.js` | Update help text, provider flag examples, and command dispatch for provider-aware commands | \~80 | | `apps/cli/src/commands/init.js` | Route init/install through provider plan and preserve default Claude behavior | \~120 | | `apps/cli/src/commands/uninstall.js` | Route uninstall through provider plan and preserve Claude backup/surgical removal behavior | \~120 | | `apps/cli/src/commands/status.js` | Accept provider filters and print compact provider posture | \~70 | | `apps/cli/src/commands/doctor.js` | Accept provider filters and check compact provider posture | \~90 | | `apps/cli/tests/cliRuntime.test.js` | Add runtime coverage for default, Claude, Codex, all, install alias, status, and doctor routing | \~220 | | `apps/hooks/tests/installScripts.test.js` | Preserve Claude hook installer regression coverage after CLI installer split | \~60 | | `apps/cli/README_cli.md` | Document provider selection, default Claude behavior, and deferred Codex mutation boundary | \~90 | | `apps/hooks/README_hooks.md` | Clarify Codex hook map readiness versus Session 02 installer support | \~50 | *** ## 7. Success Criteria ### Functional Requirements * [ ] `factionos init` and `factionos install` remain Claude-only by default. * [ ] `factionos init --cli claude` and `factionos install --cli claude` preserve current Claude hook installation behavior. * [ ] `factionos init --cli codex` and `factionos uninstall --cli codex` are recognized and return explicit deferred behavior without writing `~/.codex/hooks.json`. * [ ] `factionos init --cli all` and `factionos uninstall --cli all` expand through a deterministic provider plan and do not duplicate Claude work. * [ ] Invalid provider values fail before mutation with a compact privacy-safe error. * [ ] `status` and `doctor` accept provider filters and print provider posture without raw hook command bodies. * [ ] Help and README command strings include `--cli claude|codex|all` without claiming custom Codex slash commands. * [ ] Claude backup, merge, malformed-settings fallback, reinstall idempotency, and uninstall behavior stay stable. ### Testing Requirements * [ ] Provider parser and routing tests cover default, explicit Claude, Codex, all, aliases, and invalid values. * [ ] CLI runtime tests cover init/install alias behavior, uninstall routing, status/doctor provider filters, and no Codex file mutation. * [ ] Hook installer tests continue proving Claude backup, merge, reinstall, and uninstall behavior. * [ ] Focused CLI and hooks tests pass. * [ ] Focused Biome check passes for touched CLI/hook files. ### Non-Functional Requirements * [ ] No Codex auth, provider, telemetry, model, profile, API key, or account settings are read or written. * [ ] CLI diagnostics remain local-first, compact, and credential-free. * [ ] Provider selection does not imply hosted identity, hosted transfer, production validation, trusted erasure, or real executor support. * [ ] Existing Claude Code users see no behavior change unless they pass `--cli`. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `git diff --check` passes. *** ## 8. Implementation Notes ### Key Considerations * Preserve the current default for one release. The PRD explicitly keeps `factionos init` backward-compatible until a later session changes that decision. * Keep Codex mutation deferred. Session 01 should create a routing surface, not a partial `~/.codex/hooks.json` implementation. * Make invalid provider input fail before any write path starts. * Do not use raw hook command bodies as diagnostics. Provider posture can use status labels and managed/unmanaged counts only where already safe. * Keep `factionos codex init` and `factionos codex uninstall` out of the CLI until the flag path is validated. ### Potential Challenges * Splitting current `runInit` can drift Claude behavior: mitigate with direct regression tests for backups, malformed settings, env preservation, and reinstall idempotency. * `all` routing can partially succeed before Codex is implemented: mitigate with deterministic ordering, clear deferred results, and no duplicate Claude triggers. * Status and doctor may accidentally overclaim Codex readiness: mitigate with explicit planned/deferred wording and no hook trust claims until Session 02. * Provider selection can be parsed inconsistently across commands: mitigate by using one shared parser and test matrix. * Existing hook scripts and CLI installer code can diverge: mitigate by preserving hook installer tests and documenting package ownership. ### Relevant Considerations * \[P03-apps/cli+apps/hooks] **Lifecycle state is local and file-based**: installer and diagnostics changes must keep local state recoverable and stale-state tests intact. * \[P07] **Redaction is boundary-specific**: status, doctor, and installer output must expose labels and counts only, never raw env values, hook commands, paths, tokens, prompts, or payloads. * \[P03] **Stable docs are the current contract**: CLI behavior and privacy claims should be reflected in package READMEs before release. * \[P08] **Release-candidate evidence is claim-scoped**: provider routing is not production-hosted validation, trusted erasure, or live Codex end-to-end proof. * \[P09-apps/hooks] **Provider-specific map files make boundaries explicit**: keep the Codex map as a source template until the installer session wires safe user-level writes. * \[Security] **P06-S07-ERASURE**: uninstall and recovery must not be described as trusted erasure or broad state deletion. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Provider parsing could start writes before invalid input is rejected. * `all` routing could duplicate Claude installation or leave unclear partial results. * Codex selection could imply real install support before safe backup and merge behavior exists. * Status, doctor, or error output could leak local hook commands, env values, paths, or settings contents. *** ## 9. Testing Strategy ### Unit Tests * Test provider parser defaults, allowed values, alias handling, `all` expansion, and compact invalid-provider errors. * Test Claude provider installer boundaries with existing settings, malformed settings, missing hooks package, and reinstall. * Test Codex deferred provider boundaries for no `~/.codex` writes and explicit planned status. * Test provider posture helpers for compact labels and no raw command bodies. ### Integration Tests * Run focused CLI and hook tests: * `npx vitest run apps/cli/tests/cliProvider.test.js apps/cli/tests/cliRuntime.test.js apps/hooks/tests/installScripts.test.js` * Run focused Biome check for touched CLI and hook paths. * Run `git diff --check`. ### Manual Testing * Review `factionos help` output for default Claude behavior and provider flag examples. * Review `apps/cli/README_cli.md` and `apps/hooks/README_hooks.md` for no Codex install, custom slash command, hosted transfer, or production validation overclaim. * Manually confirm Codex provider selection does not create, overwrite, or back up `~/.codex/hooks.json` in this session. ### Edge Cases * `--cli` missing a value, unknown values, mixed case, and whitespace. * `install` alias with explicit provider selection. * `uninstall --cli all` when Claude settings are absent or malformed. * Codex selection when `~/.codex/hooks.json` already exists. * Status and doctor with missing, malformed, or absent local FactionOS settings. *** ## 10. Dependencies ### External Libraries * No new external libraries are required. ### Other Sessions * **Depends on**: `phase09-session01-contracts-and-naming-baseline`, `phase09-session02-hook-runtime-normalization`, `phase09-session03-codex-hook-map-and-codex-specific-handlers`. * **Depended by**: `phase10-session02-codex-hook-install-uninstall-and-diagnostics`, `phase10-session03-server-ingest-codex-lifecycle`, `phase10-session04-web-codex-awareness`. *** ## Next Steps Run the implement workflow step to begin AI-led implementation. --- # 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/sessions/phase10-session01-cli-provider-selection-and-installer-split/spec.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.