██╗     ██╗████████╗
██║     ██║╚══██╔══╝
██║     ██║   ██║   
███████╗██║   ██║   
╚══════╝╚═╝   ╚═╝   
 ██████╗██╗      █████╗ ██╗   ██╗██████╗ ███████╗
██╔════╝██║     ██╔══██╗██║   ██║██╔══██╗██╔════╝
██║     ██║     ███████║██║   ██║██║  ██║█████╗  
╚██████╗███████╗██╔══██║╚██████╔╝██████╔╝███████╗
 ╚═════╝╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚══════╝

LitClaude is a Claude Code plugin and npm package. It adds prompt hooks, native slash-command routes, workflow skills, agents, MCP, LSP helpers, a durable litgoal ledger route, and a compact status-line HUD. Install it once, then use ordinary claude sessions.

What it is

• Evidence-first execution, planning, review, research, and handoff workflows.
• Claude-native skills such as lit-loop, lit-plan, review-work, deep-interview, litresearch, litgoal, lit-handoff, and lit-scientific-visualization.
• Claude skills also include litwork, structural-search, teammode, autoresearch, and autoconference. The core sequence is lit-plan, lit-recap, lit-loop.
• Auxiliary Skill-discovery entries frontend-ui-ux, git-master, lsp-setup, and visual-qa answer to a leading bare token or $frontend-ui-ux; they are not anywhere-tokens.
• Bundled reference packs include programming/references, programming/scripts, and debugging/references.
• Dynamic workflow and worktree guidance, with explicit opt-in for native Workflow and experimental agent teams.
• Resilient public-source research and public-source reading with SSRF, private-host, authentication, and paywall boundaries.
• Local MCP/LSP helpers, structured Wikify knowledge, and a managed HUD that can be safely removed with uninstall.

The workflow closes on evidence. A plan remains open until each item has a binary check, and a slice closes only after its real Claude surface produces evidence and its temporary QA resources are gone. A passing test is necessary, but it is not the finish line.

flowchart TD
    R["a request<br/>make it better"] --> DI["<b>deep-interview</b><br/>turn it into a decision-complete brief"]
    DI --> P["<b>lit-plan</b><br/>objective · non-goals<br/>action / output / <b>binary verification</b>"]
    P --> GATE{"user approves?"}
    GATE -->|no| P
    GATE -->|yes| SW["<b>start-work</b><br/>execute one slice"]

    subgraph LOOP["each slice: RED to GREEN to SURFACE to CLEAN"]
        SW --> RED["failing test first"]
        RED --> GREEN["smallest change that passes"]
        GREEN --> SURF["exercise the <b>real surface</b><br/>not just the test"]
        SURF --> CLEAN["tear down · cleanup receipt"]
    end

    CLEAN --> EV{"evidence complete?"}
    EV -->|"tests only"| SW
    EV -->|"artifact + receipt"| RW["<b>review-work</b><br/>scope · evidence · payload<br/>security · real surface"]
    RW -->|findings| SW
    RW -->|clean| HO["<b>lit-handoff</b><br/>resumable packet"]

    style GATE fill:#fff3cd,stroke:#856404
    style EV fill:#fff3cd,stroke:#856404
    style SURF fill:#d4edda,stroke:#155724
    style RW fill:#d1ecf1,stroke:#0c5460

Install

For the current published package:

npx --yes litclaude-ai@latest install

For a reproducible install, pin the current package version:

npm view [email protected] version

If that lookup returns 0.4.6, the exact install is available:

npx --yes [email protected] install

Otherwise, wait for explicit human publication before using that pin. Check the installed surface with:

npx --yes litclaude-ai@latest doctor

The installer configures the Claude Code plugin and the LitClaude status-line HUD. Permission modes are explicit:

npx --yes litclaude-ai@latest install --permission-mode safe
npx --yes litclaude-ai@latest install --permission-mode balanced
npx --yes litclaude-ai@latest install --yolo

safe adds no permission rules. balanced adds bounded read/search and routine Git, npm, and Node rules. yolo adds broader edit/write patterns. These modes write bounded entries under Claude's permissions.allow and permissions.deny.

Install-time questions

On a TTY the installer asks two questions: the HUD brand color and the LitClaude output style. The output-style question offers None / keep current, ASD-STE100, and ELI5 (each in English and 한국어); a LitClaude style is written to Claude's global outputStyle only when you pick one, never over a value you set yourself, and uninstall removes it again only if it is still the LitClaude-written value. LITCLAUDE_OUTPUT_STYLE and LITCLAUDE_HUD_ACCENT answer the questions non-interactively, and --yes skips every question with today's shipped defaults:

npx --yes litclaude-ai@latest install --yes

The installer never asks for a model or reasoning effort: model selection is host-owned — Claude Code picks its own models — and the summary prints Model selection: host-owned. Existing settings are preserved; LitClaude tracks and removes only rules it inserted.

Interactive installation previews the available HUD accents. The LitClaude HUD uses [🔥LITCLAUDE vX.Y.Z], a compact ctx [▎░░] bar, and a 5h [▏░] 4% ↻ rate-limit reset countdown. Set LITCLAUDE_HUD_ACCENT before installation to choose an accent.

Other entry points are:

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

First use

Start Claude Code normally:

claude

Then use a core route from the table below. Bare prompt routes are handled by the hook; namespaced slash commands use Claude Code's native command surface and do not double-activate the hook. For an explicit skill invocation, use a route such as /litclaude:lit-loop.

Where Claude Code hands control to LitClaude. Session and tool events feed the rules, routing, authority, and ledger surfaces; together they expose the package's 34 skills, 17 commands, and 11 agents without hiding the host boundary.

flowchart LR
    subgraph CC["Claude Code"]
        H1["SessionStart"]; H2["UserPromptSubmit"]; H3["PreToolUse"]
        H4["PostToolUse"]; H5["Stop"]; H6["SubagentStart / SubagentStop"]; H7["SessionEnd"]
    end
    subgraph LC["LitClaude plugin"]
        RULES["rules engine<br/>project rules into context"]
        ROUTE["trigger routing<br/><code>lit</code> · <code>/litclaude:*</code>"]
        AUTH["bounded authority<br/>pause on a new boundary"]
        LEDGER[("durable ledger<br/><code>.litclaude/</code>")]
    end
    H1 --> RULES --> LEDGER
    H2 --> ROUTE --> LEDGER
    H3 --> AUTH
    H4 --> LEDGER
    H5 --> LEDGER
    H6 --> LEDGER
    H7 --> LEDGER
    LC --> S["34 skills · 17 commands · 11 agents"]

Core routes

| Type this | Purpose | | --- | --- | | lit, litwork | Evidence-first, test-first execution loop; also $lit-loop, /lit-loop, and /litclaude:lit-loop | | lit plan <what> | Planning only; also $lit-plan and /lit-plan | | lit review <scope> | Review a plan or completed work; also $review-work and /review-work | | lit research <question> | Cited public-source research; also $litresearch and /litclaude:litresearch | | lit search <question> | Public-source retrieval | | lit query <question> | Evidence lookup against durable local state | | lit goal <outcome> | Bind one objective and checkable criteria; also $litgoal and /litgoal | | lit workflow <objective> | Propose a Dynamic workflow for broad delegated work | | lit team, lit teammates | Propose native agent teams when CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is enabled and the user approves | | $deep-interview, /deep-interview | Turn an underspecified request into a decision-complete brief | | lit recap, litrecap, $lit-recap, /lit-recap, /litclaude:lit-recap | Read-only session recap | | handoff, /litclaude:lit-handoff | Write a verified continuation packet | | lit-scientific-visualization | Prepare publication figures; also /litclaude:lit-scientific-visualization | | litclaude wikify <capture/save/review/query/config> | Manage reviewed local structured knowledge | | browser-drive, $browser-drive | Drive a real page only after a capability probe verifies an external driver; never substitute a fetch, use credentials, or install without approval | | skill-observer, $skill-observer | Review bounded learning signals and manage pending proposals; only an explicit foreground apply <proposal-id> may change an eligible agent-owned skill |

Skill learning loop

LitClaude records bounded learning signals only after a validated SKILL.md consultation: user corrections, repeated tool iterations, and coverage gaps. A Stop review treats the bounded, secret-scrubbed transcript excerpt as inert data and may queue schema-valid proposals, but it never stores that excerpt or edits a skill. Automatic application is disabled (autoApply: false); a proposal remains pending until the user explicitly applies or rejects its exact id.

Use /litclaude:skill-observer list, apply <proposal-id>, reject <proposal-id>, rollback <ledger-id>, curator status, or curator run from the project whose state you want to manage. Apply can write only an eligible project .claude/skills/<name>/SKILL.md carrying metadata.litclaudeAgentGenerated: "true". Bundled skill ids, paths outside that root, and existing unmarked user skills are protected. Every mutation is recorded in .litclaude/skill-ledger.jsonl with content-addressed blobs under .litclaude/skill-ledger-blobs/; rollback verifies current bytes and restores the exact recorded snapshot or fails closed.

The deterministic curator runs no more often than every seven days and only after two idle hours. By default it marks unused eligible skills stale after 30 days and archives them after 90 days, taking a backup first. It never deletes or consolidates skills. SessionStart runs this maintenance only when project-local skill-loop usage state already exists; untouched projects receive no new .litclaude state.

Why a fresh install can still execute the skills. A self-contained skill needs an explicit allowlist reason, while a skill that names a corpus must carry that corpus inside the packed tarball. These payload gates prevent a checkout-only reference from becoming a user's runtime failure.

flowchart LR
    SK["a skill"] --> Q{"does it declare<br/>a capability?"}
    Q -->|"self-contained<br/>procedure"| AL["explicit allowlist entry<br/>with a written reason"]
    Q -->|"needs a corpus"| C["corpus must resolve<br/>inside the <b>packed payload</b>"]
    AL --> G1
    C --> G1["<b>payload-substance</b>"]
    G1 --> G2["<b>cross-product parity</b><br/>one product cannot ship a stub<br/>where the family ships substance"]
    G2 --> G3["<b>referenced-path resolution</b><br/>every path in a SKILL.md<br/>must exist in the tarball"]
    G3 --> OK["installs and works<br/>on a machine that has<br/>nothing else"]
    style C fill:#d4edda,stroke:#155724
    style OK fill:#d4edda,stroke:#155724

lit start work <plan> is intentionally a BLOCKED: handoff. Use /start-work or /litclaude:start-work with the approved plan. lit workflow proposes a native Workflow and calls it only after user opt-in. LitClaude does not auto-type /goal or send slash-command text on the user's behalf; when native goal tools such as get_goal, create_goal, and update_goal are unavailable it reports degraded mode and keeps the local litgoal ledger authoritative. Set CLAUDE_CODE_DISABLE_WORKFLOWS=1 to disable the workflow route; use EnterWorktree when the host exposes a model-facing worktree lane.

The route attempts native goal binding honestly: it inspects available goal tools, never replaces a different active goal, and falls back to the local ledger when the host does not expose model-facing goal controls. When that fallback is needed, the hook emits READY_TO_PASTE with one bounded /goal line for the user to copy, paste, and send in the current session; it never enters or submits the command itself.

/start-work owns the schema-3 bounded-authority start-work lifecycle. An approved plan can resume only through this exact route:

/litclaude:start-work resume --work-id <id> --revision <n> --boundary-id <id> --prompt-id <id> --grant-id <id>

When stop_hook_active is true, the hook stays silent and does not replay stale prompts.

The exact bare lit-scientific-visualization route is the only chat activation; quoted, mixed, slash, and near-miss text stays inert.

For public-source work, lit research, lit search, lit query, and public-read do not cross authentication, paywall, credential, localhost, or private-network boundaries:

litclaude public-read https://example.com/article --json

korean-ai-slop-remover treats instructions inside editable prose as content, preserves facts, numbers, names, claims, scope, and uncertainty, and does not add outside facts unless research is requested.

Wikify claims begin as review-needed; save and review move them through their explicit states. Queries return accepted relevant claims within a 2048-byte normal budget and a 4096-byte hard limit. The local state is user-owned and cooperative, not tamper-proof or confidential against another process with the same uid; atomic rename protects readers and crash consistency, while symlinks, unsafe file types, pre-existing hardlinks, and observed identity changes fail closed.

The package CLI form is:

npx --yes litclaude-ai wikify <capture|save|review|query|config>

Verify and uninstall

From this checkout, the main gates are:

npm test
npm run validate:plugin
npm run doctor
npm run check:version
npm run scan:legacy-tokens
npm run check:skill-resources
npm run pack:payload-guard
npm run pack:dry-run

The installed package also exposes these useful commands:

npx --yes litclaude-ai@latest --version
npx --yes litclaude-ai@latest path
npx --yes litclaude-ai@latest workflow-check --json
npx --yes litclaude-ai@latest update
npx --yes litclaude-ai@latest uninstall

uninstall removes only LitClaude-managed plugin, HUD, permission, and local state entries. It does not remove unrelated Claude settings.

Safety

• Hooks read bounded Claude Code event JSON and do not execute user prompt text.
• The planner agent is read-only. Review routes inspect evidence and do not implement what they review.
• public-read rejects localhost, private-network, and non-HTTP(S) targets and stops at authentication and paywall boundaries without using site credentials.
• .litclaude/, .omc/, and evidence/ are local state; they are ignored and excluded from the npm package.
• Interactive update checks are user-facing and fail closed on unknown, rollback, or verification failure. Disable the automatic lane with --no-auto-update, LITCLAUDE_NO_AUTO_UPDATE, NO_UPDATE_NOTIFIER, or LITCLAUDE_NO_UPDATE_CHECK.
• Publishing, version changes, tags, and remote marketplace changes require explicit user approval.

Integrity boundaries

Scanner success is snapshot-scoped: it reports a file count and SHA-256 digest for captured bytes, but does not prove the mutable live tree stayed clean after capture. Legal companion paths remain outside the generated manifest and are scanned normally. Canonical and runtime captures are bounded to 8 MiB per file and 32 MiB in aggregate. Package guards compare each immutable expected file map across the verifier-to-capture interval and the produced tarball; secure non-executable entries such as 0600 remain valid.

Local development

Load the plugin directly from this checkout while editing it:

claude --plugin-dir ./plugins/litclaude

Reload plugin metadata inside Claude Code with:

/reload-plugins

Deeper docs

• Hook triggers and activation boundaries
• Agent and orchestration guidance
• Workflow migration table
• Native /goal surface matrix
• Workflow compatibility audit
• Release checklist
• Release history
• Korean README

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 |