<p align="center"><img src="./cover.png" width="100%" /></p>

<h1 align="center">LazyClaude</h1>
<p align="center">
  <em>Claude Code-native LazyClaude workflows: prompt hooks, ultrawork skills, agents, MCP, and LSP helpers.</em>
</p>
<p align="center">
  <a href="#quick-start">Quick Start</a> · <a href="#ulw-usage">ULW Usage</a> · <a href="#commands">Commands</a> · <a href="./README_ko-KR.md">한국어</a>
</p>
<p align="center">
  <img src="https://img.shields.io/badge/npm-lazyclaude--ai-cb3837" />
  <img src="https://img.shields.io/badge/version-0.1.14-2ea44f" />
  <img src="https://img.shields.io/badge/Claude%20Code-plugin-blueviolet" />
  <img src="https://img.shields.io/badge/license-MIT-blue" />
</p>

---

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

This checkout is prepared as `lazyclaude-ai@0.1.14` for personal install
convenience. The repo can remain private and quiet; publishing to npm here does
not imply public repo promotion, marketplace publication, or advertisement.
Future package releases still require explicit user approval.
The v0.1.14 release materials are source-origin-free and describe LazyClaude in
its own terms.

## Features

- **Natural Claude launch** - install once with `npx`, then run plain `claude`
- **ULW prompt hooks** - type `ulw`, `ultrawork`, `$ulw-plan`, or `$ulw-loop`
- **Native goal guidance** - ULW 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
- **Dynamic workflow/worktree guidance** - large or parallel tasks are steered
  toward Claude Code Dynamic workflow orchestration and Dynamic worktree
  isolation
- **Claude skills** - a richer LazyClaude-owned corpus: `programming`,
  `debugging`, `refactor`, `ai-slop-remover`, `remove-ai-slops`, `review-work`,
  `frontend-ui-ux`, `comment-checker`, `rules`, `lsp`, `ultragoal`,
  `ulw-plan`, `ulw-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 lazyclaude@lazyclaude-ai`
- **MCP and LSP helpers** - plugin-local stdio MCP plus TypeScript-family LSP doctor
- **LazyClaude HUD** - npm install configures a compact Claude Code statusLine
  based on `pretty-claude-hud`, branded as `[💤LAZYCLAUDE vX.Y.Z]`
- **Safe uninstall** - removes only LazyClaude-managed state

## Quick Start

### Install

```bash
npx --yes lazyclaude-ai install
```

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 lazyclaude-ai@0.1.11 install` could resolve the local same-name
source checkout and fail with `sh: lazyclaude-ai: command not found`. Current
checkout builds include a local npx shim, and from a fresh directory the normal
install command works:

```bash
cd /tmp
npx --yes lazyclaude-ai@0.1.14 install
```

Validate the installed plugin:

```bash
npx --yes lazyclaude-ai doctor
```

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

```text
[💤LAZYCLAUDE v0.1.14] | O4.8 │ ctx ▄░░░░░ 9%/1000k │ 5h [░░░]4% │ 1w [█░░]35% │ git main +3 ✓
```

Launch Claude Code normally:

```bash
claude
```

### Alternative Entrypoints

```bash
bunx lazyclaude-ai install
npm install -g lazyclaude-ai
lazyclaude 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:

```bash
npm exec --prefix "$(mktemp -d)" --yes --package lazyclaude-ai -- lazyclaude install
```

Remove only LazyClaude-managed install state:

```bash
npx --yes lazyclaude-ai uninstall
```

## How Install Works

The installer registers `lazyclaude@lazyclaude-ai` in Claude Code's user plugin
registry under `~/.claude/plugins`, enables it in `settings.json`
`enabledPlugins`, and writes a LazyClaude-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 `LAZYCLAUDE_HOME=/some/path` only for
isolated tests.

## ULW Usage

After install, start Claude Code:

```bash
claude
```

Then type one of these prompts:

```text
ulw
ultrawork
$ulw-plan <what you want planned>
/ulw-plan <what you want planned>
$ulw-loop <what you want executed with evidence>
/ulw-loop <what you want executed with evidence>
$start-work plans/lazyclaude-retrofit.md
/start-work plans/lazyclaude-retrofit.md
```

Expected behavior: LazyClaude's prompt hook adds `ULTRAWORK MODE ENABLED`
context and shows `LazyClaude ULW hook active` as a visible hook message. The
hook also tells Claude to treat plain `ulw` as `/lazyclaude:ulw-loop` /
`Skill(ulw-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.

LazyClaude does not auto-type `/goal` or send slash command text for you.
Instead, the hook and ULW 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,
LazyClaude 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, LazyClaude applies the same principle to Claude
Code's available orchestration surfaces: when `Workflow` is exposed, call the
`Workflow` tool; 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`.

Plain `ulw` 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 LazyClaude skill activation:

```text
/lazyclaude:ulw-loop <what you want executed with evidence>
/lazyclaude:ulw-plan <what you want planned>
/lazyclaude:start-work plans/lazyclaude-retrofit.md
```

Those namespaced commands are shipped as real Claude Code command files under
`plugins/lazyclaude/commands/`, so `/lazyclaude:ulw-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 `ulw` loop fallback.

## Commands

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

The package alias can be inspected without installing anything globally:

```bash
node bin/lazyclaude-ai.js --dry-run install
node bin/lazyclaude-ai.js --dry-run doctor
```

## Local Development

Use the plugin directly from this checkout while editing it:

```bash
claude --plugin-dir ./plugins/lazyclaude
```

Inside Claude Code, reload local plugin metadata after edits:

```text
/reload-plugins
```

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

## Verification

```bash
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 ultrawork prompt hook returns constant guidance and does not echo prompt text.
- `.omc/`, `.omo/`, 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/lazyclaude-ai.js` |
| Claude plugin | `plugins/lazyclaude/` |
| Skills | `plugins/lazyclaude/skills/` |
| Agents | `plugins/lazyclaude/agents/` |
| Hooks | `plugins/lazyclaude/hooks/hooks.json` |
| MCP | `plugins/lazyclaude/.mcp.json` |
| LSP | `plugins/lazyclaude/.lsp.json` |

See `README_ko-KR.md` for Korean setup notes, `REFERENCE.md` for the pinned
private snapshot metadata, `docs/migration.md` for the reference-to-Claude migration table,
`docs/workflow-compatibility-audit.md` for the current compatibility audit, and `CHANGELOG.md`
for release notes.
