helpgenai-host-claude-code

License: Polyform Free Trial 1.0.0. Free to evaluate for 32 consecutive days from first install. After that, any continued use (commercial, internal, personal — all of it) requires a paid license. Contact [email protected]. See LICENSE.

A reference agent host for helpgenai, implemented as a Claude Code skill.

helpgenai's CLI is host-agnostic by design: when the engine needs an LLM to run a pass, it exits with code 75 and emits a JSON action on stdout (generate_help_content, annotate_data_help_id, etc.). Any LLM host that implements the protocol can drive the engine — Claude Code, Cursor, Windsurf, a custom MCP server, a CI job. This package is one such implementation.

The authoritative protocol spec lives in helpgenai's CLI.md under "Agent protocol." Read that first if you want to build a different host.

What gets installed

helpgenai-host-claude-code install copies a single file into your project:

./.claude/skills/helpgen-build/SKILL.md

That SKILL.md is a prompt your Claude Code session reads when you invoke the helpgen-build skill. Its job:

1. Run helpgenai build <page>.
2. If the engine exits 75 with a JSON action, parse it.
3. For generate_help_content: read the inputs.json, run the three helpgenai passes (extract, context brief, generate bundle), write the named outputs.
4. For annotate_data_help_id: apply data-help-id attributes to the source files named in the payload.
5. Re-invoke the engine's resume_command until exit 0.

The skill is ~200 lines of prompt content; the installer is ~100 lines of Node. Most of the value is in the prompt.

Install

# From the consumer's project root (where you want .claude/ to live):
npx helpgenai-host-claude-code install

Idempotent: if SKILL.md is already present and matches what this package would install, install is a no-op. If it differs (you edited it locally, or upgraded the package), install warns and exits non-zero — re-run with --force to overwrite:

npx helpgenai-host-claude-code install --force

Uninstall

npx helpgenai-host-claude-code uninstall

Removes ./.claude/skills/helpgen-build/.

Versioning

The installed SKILL.md carries a helpgen-host-version: field in its frontmatter that matches this package's version. When the host package bumps, run install --force in each consumer project to pick up the new SKILL content.

Why not a postinstall script?

npm install helpgenai-host-claude-code will NOT automatically write into .claude/skills/. Postinstall scripts that touch the user's working tree are intrusive and surprising. The explicit install subcommand keeps the contract obvious: nothing changes until you ask.

Building a different host

The protocol is documented in helpgenai's CLI.md. The minimum a host needs to do:

• Spawn helpgenai build <page> and capture stdout/stderr/exit code.
• On exit 75, parse the last line of stdout as JSON.
• Dispatch on action; perform the LLM work; write the named outputs.
• Re-invoke resume_command (which is ["helpgenai", "build", "<page>"] by default).
• Loop until exit 0 (success) or any other exit code (failure).

Patches for helpgenai-host-cursor, helpgenai-host-mcp, etc., are welcome as peer packages.