huxlify-opencode

OpenCode adapter for Huxlify. The local SQLite/RAG persistence layer is documented in docs/persistence-rag.md.

Quick install

npx --yes huxlify-opencode@latest install

The installer checks for OpenCode, adds huxlify-opencode to your OpenCode plugin list, writes a small Huxlify config, then prints the OpenCode auth and model-refresh commands to run if needed.

By default Huxlify inherits OpenCode's current/global/session model. It does not ask beginners to choose a model provider during install.

For the full noob-friendly walkthrough, see docs/installation.md. For advanced pinned model presets and per-agent customization, see docs/configuration.md.

Bun users can alternatively run bunx huxlify-opencode@latest install.

After install:

opencode auth login
opencode models --refresh
opencode

Then try /hux-init in OpenCode to scaffold a writing project. If you are unsure what to do next, ask /hux-help or /hux-help setup. Terminal help is also available with npx --yes huxlify-opencode@latest help [topic].

The /hux-init runtime command uses the bundled huxlify-scaffold CLI; huxlify-scaffold does not need to be on your shell PATH.

Project planning layout

New OpenCode projects use this user-facing planning layout:

huxlify/
  story-brief.md
  planning/
    story-architecture.md   # global structure and pacing authority
    timeline.md             # human-readable chronology/backstory backbone
    sprints/
      A.md                  # short-work sprint target
      1A.md                 # chapterized sprint target

Use /hux-sprint <target> to create or refresh a concise Writer-facing sprint under huxlify/planning/sprints/. Targets use sprint grammar such as A, B, 1A, 1B, or 1AA; lower-case input normalizes to uppercase and old chapter/scene names are rejected.

Task sprints are author-editable projections of the architecture for one drafting unit, not a second source of truth or style matrix. They prioritize key_scenes and stay concise.

New scaffolds use the canonical huxlify/planning/ paths.

Parallel drafting and assembly

Use /hux-multi-write <target> when you want several Writer takes against the same sprint. It writes drafts/{target}/writer-01.md, writer-02.md, writer-03.md, etc.; it does not promote anything to manuscript/ or run later prose passes.

When you explicitly want to combine strong spans, run /hux-cherry-pick <target> and describe the preference naturally, such as “use writer-02 as backbone” or “balanced, no single backbone.” It assembles a human-editable candidate at drafts/{target}/assembled.md and records source/seam notes at drafts/{target}/assembled.notes.md. @line-editor can run copycheck, humanize, or opt-in macro roughen for over-complete/smooth assembled drafts if requested. Manuscript promotion remains a separate explicit step.

Scene Catalyst

Use /hux-scene-catalyst to run a guided scene simulation before drafting prose. The helper CLI initializes scene state, writes prompt packets, ingests character JSON, can inject public director/world events, and can finish with:

huxlify-scene-catalyst handoff . --run-id <runId> --json

Public Scene Catalyst artifacts are written under drafts/<target>/scene-catalyst/<runId>/: transcript.md, transcript.json, and prose-handoff.md. Private run state, prompt packets, checkpoints, raw outputs, hidden motive traces, and hidden director rationale stay under huxlify/.huxlify-sys/scene-catalyst/<runId>/ and must not be treated as manuscript or retrieval-safe public material.

Scene Catalyst has no manuscript writes by default. It feeds each character only that character's own private continuity and asks character/director turns to preserve the scene language. Use the generated prose-handoff.md as downstream context for Writer, Multi-write, Cherry-pick, Line Editor, and Tuner when you explicitly want to draft or refine prose from the simulation.

See docs/scene-catalyst.md for the full command workflow.

What gets installed

The installer only writes or edits these files:

• ~/.config/opencode/opencode.json (or .jsonc) — adds huxlify-opencode to plugin[]. JSONC comments/formatting are preserved when the plugin array can be patched safely.
• ~/.config/opencode/huxlify.jsonc — Huxlify plugin config with modelMode, format, and videoTutorialUrl, plus commented examples for per-agent model overrides. Preset blocks are only written when you install with --preset=<name>.
• .bak backups next to files it overwrites.

It never writes OpenCode agent/, skill/, or command/ files. Huxlify agents and slash commands are provided by the runtime plugin while OpenCode is running.

Pinned model presets (advanced)

Default installs omit agent model fields so OpenCode chooses the model. Advanced users can deliberately pin Huxlify's role-group models later:

npx --yes huxlify-opencode@latest install --reset --preset=<name>

See docs/configuration.md for pinned preset names and per-agent model overrides.

Switch presets later by editing:

vi ~/.config/opencode/huxlify.jsonc

Change the active pinned preset, for example:

"preset": "your-preset-name"

Then restart OpenCode.

Doctor

Run diagnostics with:

npx --yes huxlify-opencode@latest doctor

For machine-readable output:

npx --yes huxlify-opencode@latest doctor --json

Doctor checks OpenCode detection, plugin registration, huxlify.json(c) schema validity, active preset presence when configured, bundled/PATH scaffold resolution, tutorial URL, and stale legacy materialized files.

Tutorial URL

Generated configs include a placeholder tutorial URL:

https://example.invalid/huxlify-tutorial-placeholder

When a real walkthrough URL is available, re-run:

npx --yes huxlify-opencode@latest install --reset --video-url=<real-url>

Cleanup help for older installs

If you previously used a Huxlify version that wrote global OpenCode agents, skills, or commands, print manual cleanup guidance with:

npx --yes huxlify-opencode@latest install --print-cleanup-help

The installer and doctor only report stale files; they do not delete anything.

API surface

The package export is the OpenCode plugin entry (dist/index.js) plus ./package.json. Bundled helper CLIs (dist/scaffold.js, dist/retrieve.js, dist/reindex.js, dist/distill.js) are bins, not supported import subpaths.

New scaffolds create huxlify/style/prose-guide.md, huxlify/style/style-harness.md, and huxlify/style/distill-ref/. Use /hux-prose-spawn for initial prose-tone setup; /hux-tune remains opt-in calibration against prose-guide.md plus style-harness.md. Writer drafting and /hux-cherry-pick assembly use compact prose-guide basics by default; style-harness calibration remains a later opt-in pass. Existing projects may keep legacy style-exemplars.md and style-metrics.md; /hux-tune and /hux-distill write the consolidated harness and can merge legacy content when needed. Raw distill-ref/ files are advisory tuning references, excluded from default retrieval unless explicitly requested with --kind style_reference. Large distill-ref/ folders increase local scanning and embedding work.

Planning files under huxlify/planning/, including planning/sprints/*.md, are indexed as the existing architecture document kind. The SQLite/RAG layer remains a rebuildable cache over markdown.

Memory search works out of the box with local keyword search. Recommended enhanced memory setup:

# install/start Ollama first, then:
ollama pull bge-m3
huxlify-reindex embeddings

Useful maintenance commands after install/build:

huxlify-reindex status
huxlify-reindex all
huxlify-retrieve "query" --mode auto