[!NOTE] LitClaude is a quiet Claude Code-native workflow package for prompt hooks, skills, agents, MCP, LSP, and LIT discipline. It installs as litclaude@litclaude-ai, so normal claude launches can load the LitClaude skills and hooks without a long --plugin-dir command.

This checkout is prepared as [email protected] for personal install convenience. The repo can remain quiet; preparing npm package metadata here does not imply public repo promotion, marketplace publication, or advertisement. Future package releases still require explicit user approval. The v0.3.8 release materials preserve the v0.2.2 Dynamic workflow hardening work, add the lit-family vocab rename and neon HUD on top of v0.2.2, describe LitClaude in its own terms, and do not claim that npm publication has completed.

Features

• Natural Claude launch - install once with npx, then run plain claude
• LIT prompt hooks - type lit, litwork, $lit-plan, or $lit-loop
• Deep interview mode - type /deep-interview or $deep-interview to turn broad intent into a spec before planning or implementation
• v0.2.0 workflow parity - adds review-work 5-lane review discipline and litgoal runtime docs without claiming a package publication has completed
• v0.2.2 Dynamic workflow hardening - adds stricter subagent assignment contracts, start-work-next, context-pressure resume guidance, precise mutated-file detection, and richer workflow-check --json readiness checks
• 5-lane review - /review-work checks goal/constraint verification, hands-on QA execution, code quality, security, and local-first context mining
• Native goal guidance - LIT context points Claude toward /goal or model-facing get_goal, create_goal, and delayed update_goal when those surfaces exist, and gives a clear fallback when goal tools are unavailable
• Litgoal CLI/state - plugins/litclaude/lib/litgoal/ records durable criteria, evidence, checkpoints, steering, and review blockers under .litclaude/litgoal/
• Dynamic workflow/worktree guidance - large or parallel tasks are steered toward Claude Code Dynamic workflow orchestration, subagent delegation, and Dynamic worktree isolation
• Claude skills - a richer LitClaude-owned corpus: programming, debugging, refactor, ai-slop-remover, remove-ai-slops, review-work, frontend-ui-ux, comment-checker, rules, lsp, litgoal, deep-interview, lit-plan, lit-loop, and start-work
• Auxiliary workflow packs - ships programming/references, programming/scripts, and debugging/references for deeper language and runtime guidance
• Workflow agents - planner, executor, verifier, reviewer, librarian, and QA runner
• Local marketplace registration - Claude can resolve claude plugin details litclaude@litclaude-ai
• MCP and LSP helpers - plugin-local stdio MCP plus TypeScript-family LSP doctor
• LitClaude HUD - npm install configures a compact Claude Code statusLine based on pretty-claude-hud, branded as a neon [🔥LITCLAUDE vX.Y.Z] (truecolor hot-pink→cyan gradient, bright-magenta on 256-color terminals), with install-time vivid color selection, live mini-HUD previews, compact context bars, visible low-usage rate-limit bars, broader brand accent coverage, and spaced reset countdowns
• Safe uninstall - removes only LitClaude-managed state

Quick Start

Install

npx --yes litclaude-ai install

During an interactive npx install, LitClaude shows every HUD brand color as a vivid live terminal preview and writes the selected accent into the managed Claude statusLine command. Animated installs also use colored setup, plugin, marketplace, registry, and cache labels so progress is easier to scan. Noninteractive installs keep deterministic plain INSTALL_STEP lines.

If you are currently inside this repository checkout, which has the same package name as the registry package, older published builds such as npx --yes [email protected] install could resolve the local same-name source checkout and fail with sh: litclaude-ai: command not found. This checkout intentionally does not track a node_modules/.bin shim. From a fresh directory, the normal install command works:

cd /tmp
npx --yes [email protected] install

Validate the installed plugin:

npx --yes litclaude-ai doctor

The installer also sets Claude Code's statusLine command to the packaged LitClaude HUD. A typical no-color render starts like:

[🔥LITCLAUDE v0.3.8] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓

The ↻ suffix is a compact rate-limit reset countdown. It is separated from the percentage for readability, and low non-zero percentages still get a partial bar glyph instead of looking empty. The context bar uses three cells and the rate-limit bars use two cells so the HUD stays tight in Claude Code's status-line space. Claude Code reports reset windows as epoch seconds, and LitClaude also accepts ISO reset timestamps for compatibility with test fixtures and older status-line helpers.

To override the accent without the picker, set LITCLAUDE_HUD_ACCENT to one of cyan, blue, teal, green, lavender, rose, gold, orange, slate, or gray before installing.

Launch Claude Code normally:

claude

Alternative Entrypoints

bunx litclaude-ai install
npm install -g litclaude-ai
litclaude install

If you need the explicit npm exec form while standing inside the source checkout, use a fresh prefix so npm does not confuse the registry package with a same-name source checkout:

npm exec --prefix "$(mktemp -d)" --yes --package litclaude-ai -- litclaude install

Remove only LitClaude-managed install state:

npx --yes litclaude-ai uninstall

How Install Works

The installer registers litclaude@litclaude-ai in Claude Code's user plugin registry under ~/.claude/plugins, enables it in settings.json enabledPlugins, and writes a LitClaude-managed local marketplace entry in known_marketplaces.json. That marketplace metadata is what lets Claude show the skill and hook inventory in claude plugin details.

Use CLAUDE_CONFIG_DIR=/some/path and LITCLAUDE_HOME=/some/path only for isolated tests.

LIT Usage

After install, start Claude Code:

claude

Then type one of these prompts:

lit
litwork
$lit-plan <what you want planned>
/lit-plan <what you want planned>
$lit-loop <what you want executed with evidence>
/lit-loop <what you want executed with evidence>
$deep-interview <what needs clarification>
/deep-interview <what needs clarification>
$dynamic-workflow <parallel or delegated objective>
/dynamic-workflow <parallel or delegated objective>
$review-work <scope to review>
/review-work <scope to review>
$litgoal <goal operation>
/litgoal <goal operation>
$start-work plans/example-plan.md
/start-work plans/example-plan.md

Expected behavior: LitClaude's prompt hook adds LITWORK MODE ENABLED context for LIT routes and shows LitClaude lit hook active as a visible hook message. For /deep-interview, the hook adds DEEP INTERVIEW MODE ENABLED context and routes Claude toward /litclaude:deep-interview / Skill(deep-interview). Plain lit still maps to /litclaude:lit-loop / Skill(lit-loop) semantics before ordinary task execution, then the matching skill and agent instructions steer Claude toward test-first work, native goal handling, manual QA evidence, cleanup receipts, and explicit approval before future release steps.

LitClaude does not auto-type /goal or send slash command text for you. Instead, the hook and LIT skills add run-context guidance: use Claude Code's native goal surface when available, inspect get_goal, call create_goal only when no matching goal is active, and reserve update_goal for verified completion or a genuine blocker. When goal tools are unavailable or not exposed, LitClaude keeps the local evidence ledger authoritative and may suggest an exact /goal <completion condition> before long execution without repeatedly printing fallback chatter. For large independent work, LitClaude applies the same principle to Claude Code's available orchestration surfaces: when Workflow is exposed and the task is broad, risky, parallel, or long-running, LitClaude proposes a Dynamic workflow and calls the Workflow tool once you opt in. The tool can fan out many subagents and spend a large token budget, so it asks first — this opt-in gate (not a host limitation) is why a Dynamic workflow only starts after the proposal. When isolated edits need a model-facing worktree lane, use EnterWorktree. If only the CLI surface is available for a fresh isolated lane, use claude --worktree <short-name> --tmux.

For v0.2.2 Dynamic workflow hardening, /dynamic-workflow is the consolidated bootstrap route for broad delegated work. It keeps /goal user-controlled, checks model-facing goal tools when exposed, asks for an exact fallback /goal <completion condition> when needed, and maps subagent delegation to prometheus-planner, boulder-executor, oracle-verifier, qa-runner, quality-reviewer, and librarian-researcher. Child assignments are expected to start with TASK: and include DELIVERABLE, SCOPE, and VERIFY, so delegated work has a concrete artifact, bounded scope, and verification path. Run the package diagnostic from the checkout or an installed package before full QA:

litclaude-ai workflow-check --json

When a long $start-work run is interrupted, compacted, or resumed in a new terminal pane, use the continuation helper from the checkout:

litclaude-ai start-work-next --json

It reads .litclaude/boulder.json and .litclaude/start-work/ledger.jsonl, then prints the active plan, ledger path, and first unchecked top-level task. If the plan is complete, it returns {"status":"idle","directive":null}.

For v0.2.0 workflow parity, review-work is the dedicated review route. It is a 5-lane review: goal/constraint verification, hands-on QA execution, code quality, security, and local-first context mining. The lanes bind to oracle-verifier, qa-runner, quality-reviewer, and librarian-researcher, then aggregate evidence into a PASS, FAIL, or NEEDS-CONTEXT verdict. Manual-QA channels must write artifacts, and every tmux session, server, port, browser tab, or temp directory needs a cleanup receipt before review completion.

litgoal is the durable local state route for long goals. The runtime lives in plugins/litclaude/lib/litgoal/, stores state in .litclaude/litgoal/, and keeps current docs/test reads authoritative when stale state disagrees with the checkout. Common commands are:

litclaude litgoal create-goals --brief "<brief>" --json
litclaude litgoal record-evidence --criterion <id> --status pass --json '{"artifact":"...","cleanup":"..."}'
litclaude litgoal checkpoint --status active --note "<progress>" --json
litclaude litgoal steer --kind scope --note "<what changed and why>" --json

record-review-blockers captures unresolved review findings. Malformed JSON, unknown criteria, corrupt state, and invalid steering kinds return controlled errors instead of silently reporting success.

Plain lit is hook context activation. Claude may still show it as hook guidance rather than a separate Skill tool invocation in history. Use visible namespaced commands when you want explicit LitClaude skill activation:

/litclaude:lit-loop <what you want executed with evidence>
/litclaude:dynamic-workflow <parallel or delegated objective>
/litclaude:lit-plan <what you want planned>
/litclaude:deep-interview <what needs clarification>
/litclaude:review-work <scope to review>
/litclaude:litgoal <goal operation>
/litclaude:start-work plans/example-plan.md

Those namespaced commands are shipped as real Claude Code command files under plugins/litclaude/commands/, so /litclaude:lit-loop should load the command body, then the matching skill guidance. The shorter slash aliases above are also recognized by the prompt hook and route to the matching discipline instead of the plain lit loop fallback.

Use /deep-interview before /lit-plan when the request is broad, underspecified, or missing non-goals and acceptance criteria. It writes a requirements artifact under deep-interview/ and then hands off to planning or execution without building directly.

Commands

| Command | Purpose | | --- | --- | | npx --yes litclaude-ai install | Install and enable the Claude Code plugin | | npx --yes litclaude-ai --version | Print the packaged LitClaude version | | npx --yes litclaude-ai doctor | Validate files, Claude plugin validation, and plugin details | | npx --yes litclaude-ai path | Print the installed Claude plugin path | | npx --yes litclaude-ai run -- --help | Run plain claude after verifying install state | | npx --yes litclaude-ai update | Reinstall the current package version | | npx --yes litclaude-ai uninstall | Remove LitClaude-managed install state |

The package alias can be inspected without installing anything globally:

node bin/litclaude-ai.js --dry-run install
node bin/litclaude-ai.js --dry-run doctor

Local Development

Use the plugin directly from this checkout while editing it:

claude --plugin-dir ./plugins/litclaude

Inside Claude Code, reload local plugin metadata after edits:

/reload-plugins

If an OMC/omc Claude plugin is installed, do not co-load it with LitClaude while testing. Local checkout tests use --plugin-dir, and npm installs create only a LitClaude-managed local marketplace under the user's LitClaude home. The checkout does not ship a root Claude marketplace skeleton. If user-level OMC creates a local .omc/ state directory during smoke tests, LitClaude ignores and excludes that directory from git and npm package surfaces.

Verification

npm test
npm run validate:plugin
npm run qa:tmux
npm run qa:portable
npm run pack:dry-run

validate:plugin and qa:tmux are local checks. If Claude Code is not available on the machine, the smoke harness records a controlled skip with the version probe evidence instead of failing mysteriously.

Safety Model

• Hooks read Claude Code event JSON from stdin and return bounded JSON context.
• Hooks do not execute user prompt text.
• The litwork prompt hook returns constant guidance and does not echo prompt text.
• .omc/, .litclaude/, and evidence/ local state are ignored and excluded from the npm package.
• The planner agent is read-only and has no edit tools.
• MCP and LSP helpers are local stdio commands.
• Future publication, remote marketplace mutation, and package releases require explicit user approval.

Project Map

| Surface | Path | | --- | --- | | CLI | bin/litclaude-ai.js | | Claude plugin | plugins/litclaude/ | | Skills | plugins/litclaude/skills/ | | Agents | plugins/litclaude/agents/ | | Hooks | plugins/litclaude/hooks/hooks.json | | MCP | plugins/litclaude/.mcp.json | | LSP | plugins/litclaude/.lsp.json |

See README_ko-KR.md for Korean setup notes, docs/migration.md for the workflow migration table, docs/workflow-compatibility-audit.md for the current compatibility audit, and CHANGELOG.md for release notes.