litcodex-ai

What it is

litcodex-ai installs the LitCodex Codex plugin, its UserPromptSubmit hook, and the bundled marketplace payload. A bare lit injects <lit-loop-mode> and starts lit-loop. Goals, criteria, and evidence live under .litcodex/lit-loop in the current project; completion requires evidence for every criterion.

The package is self-contained: it does not forward to another package, require an account, or clone a source repository. Release history is maintained in CHANGELOG.md; published versions are listed on the npm versions page. Tests, fixtures, test helpers, and Vitest configuration remain tracked repository coverage and are excluded from npm and installed marketplace payloads.

Install

The recommended path does not require a global install:

npx --yes litcodex-ai install

This registers the marketplace and plugin, wires UserPromptSubmit, installs the bundled runtime, and updates ~/.codex/config.toml without overwriting unrelated keys. Preview the plan first:

npx --yes litcodex-ai --dry-run install

For a persistent litcodex command, install globally and then register the plugin:

npm install -g litcodex-ai
litcodex install

First lit

In the Codex composer, type:

lit add input validation to the signup form

The hook selects a bounded mode and starts the evidence loop. split, literal, and litmus do not trigger it. Code spans, code fences, and ordinary slash-style mentions remain inert; the explicit /litresearch research route is the exception.

Core commands

| Command | Purpose | | --- | --- | | litcodex install | Register the plugin and hook | | litcodex doctor | Diagnose installation, host capabilities, and effective config | | litcodex uninstall | Remove the plugin and LitCodex-managed config | | litcodex config migrate | Preview or apply managed Codex config keys | | litcodex hook user-prompt-submit | Run the host hook entrypoint | | litcodex loop create | Derive goals and criteria from a brief | | litcodex loop status --json | Inspect loop state as JSON | | litcodex loop run | Select the next runnable goal | | litcodex loop record-evidence | Record a criterion result | | litcodex loop checkpoint | Complete a goal after all criteria pass | | litcodex loop doctor | Diagnose or recover loop state |

Without a global install, use npx --yes litcodex-ai <command>, for example npx --yes litcodex-ai doctor.

Loop state

.litcodex/lit-loop/
├── brief.md       # original task brief
├── goals.json     # goals, criteria, and status
├── ledger.jsonl   # append-only audit trail
└── evidence/      # real-surface evidence per criterion

Writes are atomic. A damaged goals.json is preserved as .bak and reported rather than silently replaced. Project .litcodex/ state is gitignored and excluded from the npm and installed marketplace payloads.

Verify it worked

litcodex doctor
litcodex loop doctor

doctor reports plugin registration, hook wiring, config state, and loop health. The credentialless installed probe packs this package in an isolated home, runs litcodex install --no-tui --codex-autonomous --json, and requires a healthy litcodex doctor --json; model execution is NOT_REQUESTED in that scope.

Safety and compatibility

• Completion is evidence-bound: every success criterion must pass before a goal is complete.
• doctor diagnostics never modifies Codex config, install state, or plugin state.
• Unrelated keys in ~/.codex/config.toml are preserved. Use --dry-run before reviewed reconfiguration.
• The installer backs up managed config before writing and fails closed when host preflight is not accepted.
• An eligible interactive doctor may show a cached advisory notice. A detached worker performs a fixed registry refresh and records it at ~/.litcodex/update-check.json; it never installs an update automatically.
• Failed, --json, --dry-run, non-TTY, CI, and opt-out paths stay side-effect-free.

On a fresh or default managed config, --model luna writes model = "gpt-5.6-luna"; LitCodex writes model_reasoning_effort = "max". This backend-compatibility mitigation follows current official Codex CLI/config guidance. It does not describe gpt-5.6-sol or gpt-5.6-terra as invalid, deprecated, or unsupported, and users need no recurring -m gpt-5.5 workaround.

Existing customized and provider-qualified root models that pass the existing safety policy remain preserved by a normal reinstall; Luna below high fails closed unchanged. Existing explicit Sol representations remain preserved by a normal install. A one-time reviewed litcodex install --reconfigure updates an existing root to the selected alias while preserving unrelated keys. Fresh installs and explicit managed reconfiguration leave model_context_window and model_auto_compact_token_limit unset so Codex applies host defaults.

Deeper docs and skills

The Codex skill picker exposes the bundled skills. Useful entry points include $litcodex:public-page-reader, $litcodex:korean-ai-slop-remover, $litcodex:structural-search, and $litcodex:coding-session-audit. Picker-native research and knowledge workflows include $litcodex:autoresearch, $litcodex:autoconference, and $litcodex:wikify; the exact bare handoff and lit-scientific-visualization inputs have their own hook routes. The picker also exposes $litcodex:lit-handoff and $litcodex:lit-scientific-visualization.

The exact bare lit-scientific-visualization hook route is separate from ordinary text.

The visualizer adapter does not install Python dependencies; host imports remain optional.

The package stages its runtime marketplace at ~/.codex/marketplaces/litcodex. Source-only tests and fixtures stay in the tracked repository and are not installed. See the npm versions page for published release history.

Uninstall

litcodex uninstall

This removes the registered plugin and LitCodex-managed config while leaving unrelated Codex settings untouched.

License

MIT — see LICENSE in the package.