▄▄▄▄
                   ▗███▌   ▗██████▖
 ▗▄▄▄▄▄          ▗▟████▌   ▝██████▘
 ▐█████        ▗▟██████▌    ▝▀▜█▀▘
 ▐█████      ▗▟███████▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
 ▐█████    ▗▟█████████████████████████ ▐█▀
 ▐█████    ████████████████████████████▀
 ▐█████    ██▛▘   ▄ ▄▄▄▄▖▄▄▄▄▄▄▄▄▄▄▄▄▄▖
 ▐█████    ▀    ▄██ ████▌█████████████▌
 ▐█████       ▄████ ████▌█████████████▌
 ▐█████     ▄█████▛
 ▐█████  ▗▟█████▀▘       ▄▄▄▄▄     ▗▖
 ▐█████ ▐█████▀          █████     ▐▛▀
 ▐█████ ▐███▀            █████
 ▐█████ ▐█▀              █████
 ▐█████ ▝                █████
 ▐█████▄▄▄▄▄▄▄▖          █████
 ▐███████████▛           █████
 ▐██████████▀            █████

LIT · codex

@litfamily/litcodex

Keep the work lit.

한국어 · Install · Quick start · Key features · Skills · Commands · Troubleshooting · Links

What is LitCodex

LitCodex adds planning, review, research, and a durable execution loop to Codex CLI.

Install

Install @litfamily/[email protected] with the scoped command below. See migration guidance.

With Node.js 22+ and Codex CLI installed, run:

npm exec --yes --package @litfamily/[email protected] -- litcodex install

The installer registers the plugin, hooks, and agents, then updates managed keys in ~/.codex/config.toml. It asks for the lead model, helper model, and output style. Codex authentication and model access are required when you run model work; installation itself does not require GitHub credentials.

Fresh installs default to gpt-6-astra at xhigh for the lead route and gpt-6-luna at max for ordinary helpers. The installer also accepts supported model and effort choices.

Preview changes with npm exec --yes --package @litfamily/[email protected] -- litcodex --dry-run install. For unattended setup, use npm exec --yes --package @litfamily/[email protected] -- litcodex install --yes. An explicit --style <id> still applies.

For a persistent command:

npm install -g @litfamily/litcodex
litcodex install

Without a global install, use npm exec --yes --package @litfamily/[email protected] -- litcodex <command>, such as npm exec --yes --package @litfamily/[email protected] -- litcodex doctor.

For an isolated trial apart from existing settings, follow the isolated trial guide. Changing only CODEX_HOME can still discover settings in your existing home.

Windows supports the installer and CLI shims. Descriptor-dependent Python routes require POSIX and fail closed on Windows with BLOCKED_UNSUPPORTED_PYTHON_POSIX_RUNTIME. See platform and prompt policy.

Activate lit

Open Codex in your project, approve the LitCodex hooks in startup review, and type:

lit add input validation to the signup form

A bare lit selects <lit-loop-mode>. The hook emits the same plain-text, five-row activation mark through UserPromptSubmit's systemMessage regardless of terminal color settings. The reply begins with 🔥 **LIT IGNITED · <discipline>** 🔥. split, literal, and litmus stay inert. Code spans and fences are ignored; slash-command-style mentions are ignored except the explicit /litresearch research route.

The exact bare lit-scientific-visualization hook route selects <lit-scientific-visualization-mode>; it does not install Python dependencies. Both this and exact bare handoff are exact-only routes.

Make one small thing

Start in an empty project with a task you can inspect:

lit build a single-file HTML task list in this folder. Do not install dependencies.
Check adding and completing a task, and record anything you could not verify.

Look for the result, the checks actually performed, and the unfinished work. A status mark confirms routing; it does not prove the page works. Ask for lit recap to read the recorded state. Before leaving the session, send exact bare handoff as its own message. In the next session, ask Codex to read that packet and the project goals before continuing.

| Step | What stays with the work | | --- | --- | | Plan | A goal with checks that can pass or fail | | Make | A small result you can inspect | | Verify | Evidence for each completed criterion; blockers stay open | | Hand off | Decisions, remaining work, and where to resume |

Native Codex goals and the local loop ledger have separate boundaries. A paused or blocked native goal needs the documented recovery step below; a handoff does not silently resume it.

Key features

You have been handed a spark. Bring it to the work you want to finish.

A bug to fix. A screen to build. A project to finish.

Starting takes a sentence. Picking up where you left off takes more: the decisions you made, the checks you ran, and the next thing to try.

LIT keeps that spark with your project. Goals, plans, checked results, and next steps stay in local records that a later session can read. An enduring spark means work you can return to; it is not a promise that an agent runs forever.

Where one conversation ends, the next stretch of work can begin.

Plan, execute, and verify work in Codex CLI. Type lit to keep goals, checks, and evidence with your project.

Its UserPromptSubmit hook routes your request into the right discipline; the bundled library provides 40 skills. A goal is complete only after every success criterion passes. The npm package is self-contained and installs without a GitHub clone.

Use lit to start a bounded task, handoff or /lit-handoff to carry checked work forward, lit-plan to set criteria before editing, lit start work <approved-plan> to execute an approved plan, review-work to inspect the change, and litresearch to record sources and uncertainty. Each route keeps its expected effect in project-local records; no new slash route is introduced here. Host limit: Codex CLI owns hook and agent execution, while authentication, model access, permissions, and any visual check remain host capabilities. A route mark or static editorial image is not completion evidence.

How it fits together

Codex hosts the plugin and runs its hooks. The hooks supply routing and context; skills guide the agent's work. The loop CLI keeps project records and prints instructions for native goal tools.

flowchart TD
    P["Installed LitCodex plugin"] --> H["Codex hooks: UserPromptSubmit and lifecycle"]
    P --> S["Bundled skills"]
    U["Your request in Codex"] --> H
    H --> A["Codex agent"]
    S --> A
    A --> L["lit-loop CLI: goals, evidence, checkpoints"]
    L --> R["Project records: .litcodex/lit-loop/"]
    L -. "goal instructions" .-> A
    A -. "native tools, when available" .-> G["Codex native /goal"]
    R -. "read when continuing" .-> A

The dotted native-goal connection is an agent protocol: the package does not call native goal tools itself. When those tools are unavailable, keep the local records and report that native goal sync was unavailable. A paused or blocked goal needs the documented recovery step; reading a handoff does not automatically resume it. Runtime and state reference.

Skills at a glance

Each row is a skill you can start by name or route, with how to start it and what you get. The last row groups the checks that run on their own.

A/B: plain Codex vs lit

Each prompt below is one casual Korean line. The baseline got the line as typed; the lit arm got the same line with lit added and nothing else. Both arms ran Codex CLI 0.157.1 with gpt-6-sol at high effort on 2026-09-26, one trial per arm, each in its own disposable home. The lit arm used a local pre-release build of LitCodex, not a published version. Where LitCodex was fixed and run again, the table compares the latest lit run with the same baseline. A blind judge (Claude Opus 5.5) compared each pair in both orders. The maintainer then looked at both outputs side by side and made the final call; the judge's verdict is kept next to it for reference.

S3 and S4 were run again in a later interface round, together with S11. S5 was run again in an office round, together with S8 and S9; there the lit arm used lit-pptx and lit-docx.

| Task | Prompt | Final verdict | Blind judge (same round) | | --- | --- | --- | --- | | S1 terminal to-do CLI | 터미널에서 쓰는 할 일 관리 CLI 만들어줘 | Baseline won | Baseline won | | S2 API server bugs | 이 API 서버 가끔 이상하게 동작하는데 고쳐줘 | Tie | Baseline won | | S3 budget dashboard | 개인 가계부 대시보드 웹페이지 만들어줘 | LitCodex won | Baseline won | | S4 café landing page | 동네 카페 브랜드 랜딩페이지 만들어줘 | LitCodex won | Tie | | S5 report and slides from sources | sources 폴더 자료로 보고서랑 발표자료 만들어줘 | LitCodex won | Tie | | S6 Node 22 to 24 research | Node 22에서 24로 올릴 때 달라지는 거 조사해줘 | LitCodex won | LitCodex won | | S7 order, payment and shipping diagram | 주문-결제-배송 서비스 구조도 그려줘 | LitCodex won (blind judge; not reviewed by eye) | LitCodex won | | S8 quarterly results deck | 분기 실적 발표자료 만들어줘 | LitCodex won | Baseline won | | S9 new product plan | 신제품 기획서 써줘 | LitCodex won | LitCodex won | | S11 meeting-room booking app | 회의실 예약 웹앱 만들어줘 | LitCodex won | Baseline won | | Total | | 8 won, 1 tie, 1 lost | 3 won, 2 ties, 5 lost |

The motion skill, lit-typographic-motion, was rebuilt after its first A/B and has no A/B result yet. The cover at the top was made with the LitFamily motion skill.

In the interface round the Codex sandbox blocked the browser, so the lit arm's interface probe could not measure its pages; neither arm checked its rendered screen. In the office round the renderer failed inside the sandbox, so the lit arm never saw previews of its slides and pages, and each reply said so. Looking at the office round as a whole, the maintainer found the LitCodex files much better suited to real work.

What each side produced

• S1, lost. The baseline CLI can add, list, edit, complete, reopen and delete items, with checked due dates. The LitCodex CLI had fewer commands (no editing, no due dates), claimed Python 3.10 support while importing a 3.11-only API, and its own tests did not pass in the checker. The blind judge also preferred the baseline over the two earlier LitCodex runs, and the maintainer called it a clear loss.
• S2, tie. Both sides fixed all six seeded bugs, with no failing visible tests. The judge leaned to the baseline because its reply mentioned that creating an item now returns 201 instead of 200, which the LitCodex reply left out. The maintainer called it a tie.
• S3, won. The LitCodex dashboard shows monthly income, spending and the budget, and lets you add, delete and search transactions and change the budget. The judge preferred the baseline's richer analysis: an income and expense line chart, a category donut and budgets per category. The maintainer preferred the LitCodex page.
• S4, won. The judge called it a tie: the baseline's shop-front photos and menu felt more finished, while the LitCodex page showed mock-up labels to visitors because the prompt gave no address or hours. The checker found no clipped text on the LitCodex page (9 items on the baseline) but more accessibility findings (38 against 29).
• S5, won. LitCodex made a Word report and a 7-slide deck, each with an editable Markdown source. The judge called it a tie: the baseline report was better built (a data-period box, an interpretation column and numbered citations), while the LitCodex slides looked more polished. The checker counted 12 of 12 facts right for the baseline and 11 of 12 for LitCodex, none wrong on either side, and 5 invented-number flags against 14.
• S6, won. LitCodex correctly lists dirent.path as removed, where the baseline called it only deprecated, and notes that require(esm) and type stripping already exist in Node 22. The checker found 3 of 10 expected facts against 2; 75% of LitCodex's links were official sources, against 100% for the baseline.
• S7, won (blind judge; not reviewed by eye). LitCodex saved a rendered PNG and an editable HTML diagram with labelled arrows and a payment-failure path. The baseline gave Mermaid code in its reply and no rendered file, although its architecture covered more services.
• S8, won. The prompt gave no figures. The baseline made a 10-slide fill-in template with blanks for every number, and the checker flagged 18 overflowing text boxes. LitCodex made an 8-slide deck for a fictional company with sample figures labelled as examples and 3 tables; the checker flagged one overflowing box and one overlap. The judge preferred the baseline's template.
• S9, won. The baseline answered in chat with a short plan and made no document. LitCodex wrote a 6-page Word plan with its Markdown source: decision gates, scope, schedule, risks and unit economics, with every figure marked as an assumption. The judge agreed, noting leftover checklist files, wrong numbering in one list and too many caveats.
• S11, won. The judge preferred the baseline: a weekly date strip and a room-by-time timeline with click-to-book, where the LitCodex app shows a large header and a room list with no view of existing bookings. LitCodex finds rooms by date, size and equipment, blocks overlapping bookings, includes unit tests and had 2 accessibility findings against 124.

Pictures

S3, budget dashboard (baseline left, LitCodex right).

S4, café landing page (baseline left, LitCodex right).

S5, first five slides (baseline above, LitCodex below).

S7, the LitCodex diagram. The baseline returned Mermaid code without a rendered file.

S8, first five slides (baseline above, LitCodex below).

S9, first three pages of the LitCodex plan. The baseline answered in chat and made no file.

S11, meeting-room booking app (baseline left, LitCodex right).

Commands

Start with one lit task

Append lit to a prompt to activate the Codex CLI hook. It routes the request into the durable loop; Codex still owns model execution.

| Prompt or route | Effect | | --- | --- | | lit | Start a bounded task with goals and checks in the project. | | handoff or /lit-handoff | Carry the checked result and next step to another session. | | lit-plan | Prepare a plan and success criteria before editing. | | lit start work <approved-plan> | Execute an approved plan. | | review-work | Review the change and its evidence. | | litresearch | Record source-backed research and uncertainty. |

The hook is an entry signal; it does not prove that a model result or visual check completed.

Select the poster for the optional film; this README keeps motion opt-in.

In the Codex composer

| Type this | Mode | What it does | | --- | --- | --- | | lit or lit-loop | lit-loop | Durable, evidence-checkpointed execution | | litwork | litwork | Outcome-first work with manual-QA evidence | | lit-plan or lit plan | lit-plan | Planning-only, bounded plan with evidence and a Final DoneClaim | | deep-interview or lit deep interview | deep-interview | Planning-only discovery for ambiguous briefs | | litgoal or lit goal | litgoal | Bind an objective and criteria into loop state | | lit-recap or lit recap | lit-recap | Read-only recap from .litcodex ledgers | | lit-comprehend or comprehend | lit-comprehend | Build a self-contained explainer outside the worktree | | review-work or lit review | review-work | Read-only plan or completed-work review | | litresearch, /litresearch, or lit research | litresearch | Research journal separating facts, hypotheses, sources, and uncertainty | | lit start work <plan-name> | Start Work | Execute an approved plan with durable evidence | | exact bare handoff | lit-handoff | Create or refresh a secret-safe continuation packet | | exact bare lit-scientific-visualization | lit-scientific-visualization | Load the publication plotting adapter through the hook | | $litcodex:lit-diagram-drawer | lit-diagram-drawer | Create and verify conceptual, workflow, and system diagrams; export Office-safe SVG or high-resolution PNG | | $litcodex:lit-docx | lit-docx | Create and edit Word reports with publisher profiles and visual review | | $litcodex:lit-pptx | lit-pptx | Compile and QA editable PowerPoint decks from Markdown |

Typing the same mode again in one session is idempotent. Standalone skills can also be selected by exact ID from the Codex picker or with a scoped mention, including $litcodex:lit-handoff and $litcodex:lit-scientific-visualization, $litcodex:lit-humanizer, and $litcodex:lit-fetch. For diagrams, select lit-diagram-drawer or use $litcodex:lit-diagram-drawer; ordinary product screens and measured-data plots stay on their dedicated skills. For Word reports use lit-docx; for slides use lit-pptx. A bounded lit request for both outputs loads both skills. litcodex install prepares the pinned Office runtime in the product cache before a Codex session. Check it with litcodex office-runtime status or litcodex doctor; if network was unavailable, run litcodex office-runtime install later outside the sandbox. The Office runner's doctor command reports optional host tools.

CLI commands

| Command | Purpose | | --- | --- | | litcodex install | Register the LitCodex plugin and hook | | litcodex doctor | Diagnose installation, loop state, 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 pass, fail, or blocked result | | litcodex loop checkpoint | Complete a goal only when every criterion passes | | litcodex loop doctor | Diagnose or recover loop state |

Use the Codex skill picker for the full library. Previous leading skill names redirect for one release; see rename compatibility and CHANGELOG.md.

Loop state

Project state stays under .litcodex/lit-loop/: brief.md, goals.json, ledger.jsonl, and evidence/. Writes are atomic; a damaged goals file is preserved as .bak. Local state is excluded from Git and packages. See state and recovery.

Verify it worked

npm exec --yes --package @litfamily/[email protected] -- litcodex doctor

litcodex doctor checks registration, hooks, config, and host capabilities. litcodex loop doctor checks project loop state. A successful installation check does not prove authenticated model or child execution.

Safety

• Plans and evidence stay reviewable. No criterion is marked complete merely because a test command ran.
• Installation preserves unrelated Codex settings. Preview changes before --reconfigure.
• The doctor diagnostic core never modifies Codex config, install state, or plugin state. An eligible interactive doctor may show a cached advisory notice. Its detached worker performs a fixed registry refresh at ~/.litcodex/update-check.json; that worker never installs packages. A separate foreground updater can install a newer global package after eligible interactive management commands. Set LITCODEX_NO_UPDATE_CHECK=1 to disable both update paths. Failed, --json, --dry-run, non-TTY, CI, and opt-out doctor paths stay side-effect-free. See privacy.
• Model routes are configuration choices, not guarantees of access or execution. See managed model compatibility.

Troubleshooting

• Pane closes before any output: the failing stage is unknown. In an already-open terminal, run help, install, and doctor separately and retain each exit status. Follow the staged trial, then launch the host yourself.
• No activation: run litcodex doctor and check hook approval in Codex.
• Command missing: use the npx form above or check the npm global bin directory in PATH.
• Native goal paused or blocked: use /goal resume, confirm it is active, then retry litcodex loop run --retry-failed. Preserve the unfinished goal. Recovery details.

Uninstall

npm exec --yes --package @litfamily/[email protected] -- litcodex uninstall

litcodex uninstall removes the plugin and LitCodex-managed config while preserving unrelated settings.

License

MIT

Links

Documentation

• Usage reference — complete routes, model configuration, platform limits, and recovery.
• LitCodex contract — hooks, native goal boundaries, and evidence requirements.
• Reference analysis — design and compatibility decisions.
• Release provenance, publish checklist, and CHANGELOG.md.

The bundled skill library also includes autoconference, autoresearch, browser-drive, coding-session-audit, comment-checker, debugging, frontend-ui-ux, lit-commit, lit-crucible, lit-init, lit-humanizer, lit-fetch, lit-docx, lit-pptx, litcodex-contribute-bug-fix, litcodex-doctor, litcodex-report-bug, lsp, lsp-setup, lit-code, refactor, lit-burnoff, readme-studio, structural-search, lit-team, visual-qa, and wikify.

Tests, fixtures, test helpers, and Vitest configuration remain tracked repository coverage and are excluded from npm and installed marketplace payloads.

Contributing · Security · Code of conduct · Support · Privacy

LITFAMILY

Five armored machines, one for each product in the LIT family.

Ignition motion

Select the poster to watch the 10-second film.

Animated GIF · Media and icon credits