[!NOTE] LitOpenCode is a TypeScript npm OpenCode plugin with an installer/doctor CLI. It adds lit, litwork, start-work, and review-work workflow surfaces, three primary OpenCode agents, a durable .litopencode/litgoal ledger, runtime skill discovery, and release guardrails for brand-clean OpenCode use.

Features

• Three-agent OpenCode surface -- Keep the visible agent switcher focused on lit-loop, lit-plan, and lit-implement.
• Durable goal ledger -- Persist resumable progress under .litopencode/litgoal/lit-loop/ledger.jsonl.
• OpenCode-native plugin hooks -- Register config, chat-message activation, tools, command activation, tool guards, and dispose lifecycle hooks.
• npx installer/doctor CLI -- Install the plugin into OpenCode with a branded terminal flow, create the editable LitOpenCode route config, or preview the exact config patch with dry-run.
• Agent model routing -- Manage per-agent and per-category provider/model/reasoning settings from ~/.config/opencode/litopencode.json.
• Explicit YOLO permission mode -- Optional --yolo install mode reduces OpenCode permission prompts for bash/edit/task/webfetch while keeping lit-plan edit/bash denied.
• Role aliases and specialists -- Keep deeper planning, implementation, verification, QA, review, research, and specialist roles available without crowding the default UI.
• Reference-grade workflow contract -- Add OpenCode-native explore-before-ask planning, maximum safe subagent delegation, DoneClaim verification, adversarial QA, cleanup receipts, and five-lane review while avoiding unbenchmarked behavioral-superiority claims.
• Benchmark-backed superiority claims -- Export a finite REFERENCE benchmark contract and claim guard so strong comparison wording is scoped to measured evidence instead of unconditional all-task superiority.
• Native goal verdict -- Treat OpenCode native goal support as unavailable unless the current CLI or plugin API exposes it; use the LitOpenCode ledger instead.
• Release guardrails -- Verify scanner, lockstep, packed payload, source gates, and dry-pack behavior before publication.

Quick Start

Install With npx

Install the latest published package into your OpenCode config:

npx litopencode@latest install

For an explicit autonomous/YOLO setup that reduces bash and tool approval prompts:

npx litopencode@latest install --yolo

Like the REFERENCE autonomous path, this is opt-in only. The default installer does not relax OpenCode permissions. YOLO mode writes permissionMode: "yolo" to litopencode.json; the plugin config hook then sets OpenCode top-level permission for bash, edit, task, and webfetch to allow. lit-plan remains planning-only because its agent-level edit and bash permissions stay deny and its write/edit/bash tools stay disabled. Restart OpenCode after changing this mode because OpenCode loads config at startup.

The installer runs a branded terminal flow, delegates plugin registration to OpenCode's own installer, and writes a version-pinned plugin entry such as litopencode@<published-version>. It also creates ~/.config/opencode/litopencode.json when missing so you can tune agent provider, model, variant, and verbosity without editing the package. Existing litopencode.json files are preserved on reinstall.

The interactive model picker intentionally keeps one verified preset: OpenAI / gpt-5.5. Other providers use direct model-id entry so LitOpenCode does not suggest stale Copilot, Anthropic, Google, or OpenCode routes. When the picker or explicit flags select OpenAI / gpt-5.5, the installer writes that same model to every category with the high variant and no reasoningEffort field.

After install, restart OpenCode and press Tab. The default agent switcher should show:

• lit-loop
• lit-plan
• lit-implement

For a preview without writing OpenCode config:

npx litopencode@latest install --dry-run

For health checks:

npx litopencode@latest doctor

If you prefer a global binary:

npm install -g litopencode
litopencode install
litopencode doctor

By default, OpenCode manages ~/.config/opencode/opencode.jsonc, or $XDG_CONFIG_HOME/opencode/opencode.jsonc when XDG_CONFIG_HOME is set. Use --root <dir> for a custom OpenCode config directory; custom roots use a direct opencode.json patch for deterministic tests and previews.

Agent Route Config

LitOpenCode reads ~/.config/opencode/litopencode.json for global agent routing, then merges optional project-local .litopencode/config.json overrides. The installer writes a conservative default route file with categories for planning, execution, review, and research. Add concrete model values only when they match models installed in your OpenCode runtime:

{
  "$schema": "https://litopencode.dev/config.schema.json",
  "agents": {
    "lit-loop": {
      "provider": "openai",
      "model": "gpt-5.5",
      "variant": "high"
    }
  }
}

Supported route fields include top-level permissionMode (safe or yolo) plus per-agent/per-category provider, model, variant, category, reasoningEffort, textVerbosity, thinking, temperature, topP, maxTokens, promptAppend, tools, permission, and providerOptions. Generated files use variant as the primary effort knob; reasoningEffort remains available for explicit provider-level overrides.

When LitOpenCode registers OpenCode agents, it converts this route config to OpenCode's host model format. For example, provider: "openai" plus model: "gpt-5.5" becomes model: "openai/gpt-5.5" on the agent. This avoids older OpenCode builds rejecting split provider/model agent fields at startup.

Local Source Probe

npm install
npm test
npm run typecheck
npm run scan:legacy-tokens
npm run check:version
npm run check:pack-payload
node bin/litopencode doctor --root .
node bin/litopencode install --dry-run --root .

Package Surface

| Surface | Value | | --- | --- | | Package name | litopencode | | Binary | litopencode | | OpenCode plugin id | litopencode | | Public export | dist/index.js | | Public types | dist/index.d.ts | | Runtime state | .litopencode/litgoal/lit-loop/ledger.jsonl | | Native goal binding | Not exposed by the verified OpenCode CLI/plugin surface; LitOpenCode uses .litopencode/litgoal | | OpenCode route config | ~/.config/opencode/litopencode.json | | User/global state root | ~/.litopencode | | Environment prefix | LITOPENCODE_ |

OpenCode Plugin

The default export is an OpenCode plugin function, and litopencode/server points at the same compiled server entrypoint for OpenCode's plugin installer. The packed artifact exports compiled JavaScript from dist/index.js, so installed npm consumers do not rely on Node's TypeScript stripping behavior for files under node_modules.

The server surface registers:

• config hook for LitOpenCode agents with optional model/provider/reasoning route overrides
• optional YOLO permission mode that applies OpenCode top-level allow permissions only when litopencode.json opts in, while preserving lit-plan deny guards
• lit, litwork, start-work, and review-work tools
• chat.message hook that injects mode-aware <lit-plan-mode> or <lit-loop-mode> guidance when a standalone lit trigger appears in a prompt
• command activation hook for /lit, /lit-plan, /litwork, /start-work, and /review-work
• tool guard hooks for before/after processing
• dispose lifecycle for local logging resources

The v0.1.8 schema hotfix keeps these tool argument schemas host-safe for fresh npm consumers: tool actions are advertised as optional strings, while LitOpenCode's before-hook guards and execute handlers preserve the runtime allowlist, missing-action defaults, and fail-closed invalid-action behavior. The package now depends on @opencode-ai/plugin at runtime so npm install --omit=dev litopencode receives the same plugin schema support as local development installs.

Agents

The primary OpenCode UI stays deliberately small:

| Agent id | Expected UI label | Role | | --- | --- | --- | | lit-loop | Lit Loop | Implement, verify, delegate to registered subagents when useful, and record durable progress. | | lit-plan | Lit Plan | Plan executable, evidence-backed work slices; edit/bash are denied until explicit user confirmation hands off to start-work. | | lit-implement | Lit Implement | Execute approved lit-plan plans from /start-work without redesigning scope; verify in slices and hand off to review-work. |

The post-plan path is: lit-plan produces a plan and waits for explicit user confirmation; /start-work or the start-work tool routes to lit-implement, LitOpenCode's execution-only approved plan handoff, where the agent must not redesign the approved plan unless evidence proves a blocker or contradiction; /review-work or the review-work tool performs the final five-lane review before completion claims.

Start Work Handoff

Use /start-work after approving a lit-plan plan. The command routes to lit-implement, executes only the approved plan, records evidence in verifiable slices, and should hand completion checks to /review-work before final claims.

Recommended role aliases are registered as discoverable OpenCode subagents for explicit delegation:

| Alias | Role | | --- | --- | | lit-architect | Planning architecture and acceptance criteria | | lit-forge | Scoped implementation | | lit-oracle | Verification replay and verdicts | | lit-prover | QA, tests, scanners, and surface probes | | lit-sentinel | Code review and regression risk | | lit-librarian | Local/API research and source-backed facts |

Advanced specialists cover exploration, archive research, strict verdicts, strategy, heavy forge work, systems design, critical review, context mapping, and persistence loops.

LitOpenCode's workflow contract is intentionally OpenCode-native. It exceeds the reference on plugin registration, discoverable subagents, brand-clean packaging, and permission hygiene, while adopting the reference-grade disciplines that matter for delivery: explore-before-ask planning, an approval gate, maximum safe subagent delegation, DoneClaim -> independent verifier -> FullyDone checks, cleanup receipt capture, adversarial QA, and five-lane review. This is not benchmarked behavioral superiority; it is a verifiable host-integrated workflow contract.

Benchmark-Backed Superiority Claims

LitOpenCode intentionally rejects unconditional all-task superiority claims such as “always better than the REFERENCE” or “모든 실제 개발 작업에서 무조건 더 잘한다.” A literal claim over every possible real development task is not mechanically provable from a finite package test suite.

The strongest unqualified-looking wording is still scope-bound: LitOpenCode may claim it dominates the measured OpenCode-native benchmark suite versus the REFERENCE only after the exported benchmark gate passes. The public API exposes litOpenCodeReferenceBenchmark, classifyReferenceSuperiorityClaim, benchmarkGateAllowsStrongClaim, certifyDeclaredBenchmarkUniverse, and renderDeclaredBenchmarkUniverseClaim so docs, release checks, and future eval runs can apply the same policy.

The benchmark contract requires replaying both systems on the same task inputs and constraints, preserving RED/GREEN test evidence, capturing a real-surface probe, collecting an independent review, and recording cleanup receipts. Its pass thresholds include minimumTasksPerCategory, requiredWinRate, and maximumCriticalRegressions, plus required REFERENCE replay, blind review, and packed OpenCode probe completion.

If a team declares a finite benchmark corpus as a declared benchmark universe, LitOpenCode can render the stronger scoped sentence “LitOpenCode는 선언된 benchmark universe의 모든 task에서 REFERENCE보다 우수하다” only when every declared task beats the REFERENCE, every category satisfies minimumTasksPerCategory, every required artifact is present, and no critical regression appears. That wording still means “all tasks in the declared benchmark universe,” not all possible real development tasks.

Durable Goal Loop

LitOpenCode owns its goal/loop state under .litopencode/litgoal. Ledger appends are durable JSONL writes with recovery for partial temporary files and fail-closed parsing for malformed durable lines.

The verified OpenCode host surface does not currently expose a native goal primitive through the local CLI command list or the @opencode-ai/plugin Hooks type surface. LitOpenCode therefore implements durable goal behavior as package-owned ledger state rather than claiming native host binding.

Runtime Skills

The visible static skills corpus lives under skills/*/SKILL.md and covers workflow loop, durable litgoal, agent roster, start-work, review-work, reference benchmark claims, native goal verdict, doctor installer, release guardrails, litwork activation, and tool guards without dynamic execution.

Release Readiness

Run these checks before treating the package as releasable:

npm test
npm run typecheck
npm run scan:legacy-tokens
npm run check:version
npm run check:pack-payload
npm pack --dry-run --json

The release process is intentionally no-publication by default. See docs/release-checklist.md for required guardrails and docs/migration.md for package, environment, state, and vocabulary migration notes.

The packed artifact is also probed directly: after npm pack, the extracted package must import dist/index.js; an installed temp-project consumer must import litopencode; and shipped guard scripts must either pass or explicitly skip source-only checks when source-only inputs are absent.

Current Status

This repository is in release-candidate status with W0 through W5, FV-ALL, packed-artifact import probes, npx installer behavior, prompt injection parity, OpenCode route config architecture, deeper agent prompts, and native goal verdict documentation complete. Final bootstrap verification evidence is recorded at .litcodex/lit-loop/evidence/start-work/FV-ALL-final.txt.

FV-ALL completed with npm test, npm run typecheck, npm run scan:legacy-tokens, npm run check:version, npm run check:pack-payload, dry pack review, CLI dry-run probes, and OpenCode-surface plugin probes. Evidence: .litcodex/lit-loop/evidence/start-work/FV-ALL-final.txt.

v0.1.15 orders the primary OpenCode agent switcher as lit-loop, lit-plan, then lit-implement, and updates the installer TUI lockup so start-work and review-work are shown as command surfaces rather than a mandatory sequence.

v0.1.14 adds the lit-implement primary agent and routes generated /start-work command aliases through it, separating approved-plan implementation from both planning and the general lit-loop execution loop.

v0.1.13 routes generated /start-work command aliases through the lit-loop agent so starting work from lit-plan switches into the execution agent instead of staying in planning mode.

v0.1.12 clarifies the post-plan workflow: start-work is now the LitOpenCode execution-only approved-plan handoff with a dedicated <start-work-mode> prompt, and the installer TUI logo uses LitOpenCode brand colors.

v0.1.11 adds explicit YOLO permission mode: npx litopencode install --yolo writes permissionMode: "yolo", the plugin config hook allows bash/edit/task/webfetch to reduce approval prompts, and lit-plan still keeps edit/bash denied. Restart OpenCode after changing the mode.

v0.1.10 strengthens the LitOpenCode workflow contract for OpenCode: lit-plan is planning-only with edit/bash guards, discoverable subagents support delegated execution, start-work and review-work encode DoneClaim/FullyDone and five-lane review gates, and benchmark-backed comparison claims are guarded by exported certification APIs.

v0.1.9 fixes a WSL2/OpenCode startup warning where the lit-loop agent's model could be reported as invalid when older OpenCode builds received split provider/model agent fields. Agent registration now emits OpenCode's single provider/model model string while preserving the separate provider/model route config file.

v0.1.8 fixes the WSL2/OpenCode function-schema failure where fresh consumer installs could expose fallback action schemas containing type: "enum", values, and defaultValue. The release QA includes a packed --omit=dev consumer install that imports litopencode, inspects hooks.tool, and executes hooks.tool.lit.execute({}, context).