llm-cure

Source code · npm package

One canonical set of coding-agent principles, with two ways to use it: install small pointers in supported agents' global instructions, or install an on-demand Agent Skill for Claude Code and Codex. The global installer targets documented user or agent-wide instruction files and lets you opt in to another Markdown instruction file explicitly.

principles/LLM_BOOST.md contains general guidance. principles/LLM_CURE.md records learned failure modes and cures. These are the canonical documents maintained in this project; the installed and skill reference copies mirror them byte-for-byte. The original supplied files are archived unchanged in docs/originals/. CURE grew from a particular codebase and retains concrete examples from it, but its guidance is meant to be evaluated in each new context.

Use

Requires Node.js 22 or newer and npm. To install global instruction pointers:

npx llm-cure
npx llm-cure@latest update
npx llm-cure doctor

To use the optional skill instead, without changing global instruction profiles:

npx [email protected] skill --agents claude,codex
npx [email protected] skill doctor --agents claude,codex

The skill is available to Claude Code as /llm-cure and to Codex as $llm-cure, and may also be selected when a task matches its description. Its guidance loads when selected; global instruction pointers remain the broader route for the other supported harnesses. Choose one route per harness if you want to avoid duplicate guidance. The skill follows the Agent Skills format; its source is in skills/llm-cure.

The default command installs or updates the bundled principles and configures detected harnesses. init, install, and update do the same reconciliation. Repeating a command with unchanged inputs makes no changes.

Prompt updates are manual. Editing the GitHub repository or publishing a new npm version does not change files or skills already installed on your machine. The CLI has no daemon, background fetch, or registry polling. When you choose to update, run the version you reviewed: use @latest for the newest release, or pin an exact version for a reviewed, reproducible update. The update command installs the version being executed; it does not fetch Markdown from GitHub.

For example, preview, apply, and check a global update:

npx llm-cure@latest update --dry-run
npx llm-cure@latest update
npx llm-cure@latest doctor

Or update the optional skill:

npx llm-cure@latest skill --dry-run --agents claude,codex
npx llm-cure@latest skill --agents claude,codex
npx llm-cure@latest skill doctor --agents claude,codex

--dry-run lists the paths that would change; it does not show a content diff. Before running a new npx version, review the tagged documents and release diff in the repository. For an exact reviewed release, replace @latest in the commands with that version, such as @0.3.1.

For reproducible setup across machines, use the same explicit version everywhere:

npx [email protected] --agents all

There is no background synchronization, global CLI installation, daemon, submodule, or nested repository. Edit the canonical documents in this project, publish a new package version, then manually run that version on each machine. Local edits are not uploaded or merged.

Preview and inspect

npx llm-cure --dry-run
npx llm-cure status --json
npx llm-cure doctor
npx llm-cure --agents claude,codex,omp
node bin/llm-cure.js --target /absolute/path/to/other-agent/global.md

--agents explicitly selects harnesses, including ones not yet installed; --agents all selects every built-in adapter for global mode and Claude Code plus Codex for skill mode. The default selects detected harnesses supported by the chosen mode. Repeat --target for additional absolute paths to Markdown instruction files that your agent reads globally; custom targets are not a skill-mode feature. A custom target is explicit, so pass it again when running global doctor or status for that file. status and doctor inspect local state without writing; they compare against the executing package, not the npm registry. doctor exits 1 when changes are needed; status exits 0 for a valid inspection and reports drift through ok: false in JSON. Invalid configuration and conflicts exit 1. Start a new harness session after installation. In global mode, ask the agent to read the two referenced documents; in skill mode, invoke the skill when needed. The tool verifies files and pointers, not model obedience or a live authenticated session.

Files and profiles

Canonical copies live at ~/.llm-cure/LLM_BOOST.md and ~/.llm-cure/LLM_CURE.md, with an installation manifest. These are distributed copies; principles/ in this repository remains the source of truth.

Skill mode installs SKILL.md and self-contained reference copies under ~/.claude/skills/llm-cure/ and/or ~/.codex/skills/llm-cure/. The reference copies are byte-for-byte mirrors of principles/. Skill mode tracks its own manifest in ~/.llm-cure/skill-manifest.json; it does not edit CLAUDE.md or AGENTS.md or install global instruction pointers. Repeating skill installation with the same package is a no-op. A locally edited skill file or an unrelated existing llm-cure skill causes a conflict rather than an overwrite.

| Harness | Default global instruction file | Relocation | | --- | --- | --- | | Claude Code | ~/.claude/CLAUDE.md | CLAUDE_CONFIG_DIR, --claude-dir | | Codex | ~/.codex/AGENTS.md, or a nonempty AGENTS.override.md | CODEX_HOME, --codex-dir | | OMP | ~/.omp/agent/AGENTS.md | PI_CODING_AGENT_DIR, --omp-dir | | Gemini CLI | ~/.gemini/GEMINI.md | --gemini-dir | | OpenCode | ~/.config/opencode/AGENTS.md | --opencode-dir | | GitHub Copilot CLI | ~/.copilot/copilot-instructions.md | COPILOT_HOME, --copilot-dir | | Cline | ~/.cline/rules/llm-cure.md | --cline-dir | | Roo Code | ~/.roo/rules/llm-cure.md | --roo-dir | | Amp | ~/.config/amp/AGENTS.md | --amp-dir | | Kilo Code | ~/.config/kilo/AGENTS.md | --kilo-dir | | Qwen Code | ~/.qwen/QWEN.md | QWEN_HOME, --qwen-dir | | Kiro | ~/.kiro/steering/llm-cure.md | KIRO_HOME, --kiro-dir | | Junie | ~/.junie/AGENTS.md | --junie-dir | | OpenClaw | ~/.openclaw/workspace/AGENTS.md | OPENCLAW_WORKSPACE_DIR, --openclaw-dir | | Hermes Agent | ~/.hermes/SOUL.md | HERMES_HOME, --hermes-dir |

Paths are resolved for the machine on which you run the installer. Copying an installed profile to another machine is not the synchronization mechanism; run the tool there instead. Native path operations support Windows, macOS, and Linux; see verification for what was actually exercised.

Use --home to isolate all default destinations and ignore host configuration environment variables and host executable detection:

node bin/llm-cure.js --home /absolute/path/to/scratch-home --agents all
node bin/llm-cure.js doctor --home /absolute/path/to/scratch-home --agents all

Explicit directory overrides deliberately select those destinations even with --home. Use only scratch directories for development. Run --help for the exact supported options.

Configuration safety

In global mode, only a clearly delimited llm-cure block is added or replaced. Existing text outside it is retained. Existing changed profiles are backed up before replacement. Duplicate or broken markers produce an error instead of guessing what to delete. Skill mode manages only its named skill files and refuses unrelated or locally changed content. Symlinked destinations or ancestors are refused instead of following them into unrelated configuration. Use physical paths (for example /private/tmp rather than /tmp on macOS) when an operating-system alias is a symlink. Changed-profile backups use the adjacent .llm-cure.bak suffix and retain the most recent pre-change contents.

Locally modified installed principles produce a conflict rather than being overwritten. Preserve your changes elsewhere, reconcile them into the canonical project if desired, then remove the conflicting installed copy and rerun. Do not delete your harness profile to resolve a principles conflict.

OMP selects one global context file; its native file can shadow Claude/Codex context. The managed OMP block also points to those existing user instruction files. Review any other global provider guidance you rely on (for example Gemini), because OMP may shadow it too. Agent settings that disable instruction discovery or limit context can still prevent loading. Gemini may be configured to use a different global context filename; point --gemini-dir at its config root only if that filename remains GEMINI.md. Kiro custom agents need steering resources explicitly. Cloud sessions need their own installation or provider-specific sync.

OMP_PROFILE or PI_PROFILE selects ~/.omp/profiles/<name>/agent; an explicit --omp-dir selects the intended agent directory directly. OpenClaw can set a workspace in its own configuration, and multiple agents may use different workspaces. The automatic adapter uses the default workspace or OPENCLAW_WORKSPACE_DIR / OPENCLAW_STATE_DIR; use --openclaw-dir for a configured workspace, and rerun for each agent workspace you want to cover. Hermes uses SOUL.md for durable behavior and identity, so review the short pointer in that file alongside your existing persona. Command-line profile choices made when launching OMP are not visible to this installer, so select the same directory here.

To remove global llm-cure, delete only its marked blocks from the affected profiles, then remove ~/.llm-cure if no profile still references it. To remove the skill, delete only its llm-cure skill folder in each harness and its skill manifest, after checking for local changes. Backups are recovery copies, not live instructions. Restore one only after checking for newer user edits.

Other agents

Aider and Continue load guidance through their own structured configuration or explicit invocation. Cursor and Windsurf manage global user rules through their apps, without a documented stable global Markdown path. --target is for a known file your harness reads automatically; it does not cause an arbitrary agent to discover that file. See source notes for the documented boundaries.

Develop and review

Open this folder as a project in Codex. There is no build step and no runtime dependency installation:

npm test
node bin/llm-cure.js --help
npm pack --dry-run

The small test suite invokes the actual CLI in temporary directories. See architecture, source provenance, and verification.

Release

llm-cure is published on npm. To release another version, review both documents for public distribution, bump the package version, run the small smoke suite and inspect npm pack --dry-run, then publish from the project root. npm may require account authentication and 2FA.

No repository or npm package is published by the installer. No lifecycle install script modifies user profiles: configuration changes happen only when you run the CLI.