OpenCode-Hi

Türkçe README

Install in 20 seconds

Run this inside the project you want OpenCode-Hi to manage:

npx --yes opencode-hi@latest setup .

That is the clean project-registration path. It creates or preserves the project-root opencode.json and adds the exact published Hi package, for example:

{
  "plugin": [
    "[email protected]"
  ]
}

Hi-owned lifecycle/provenance files stay under .opencode/hi/**. The command does not create a project-root package.json, package-lock.json, or persistent root node_modules.

Do not use npm i opencode-hi as the OpenCode project setup command. Plain npm i is npm dependency installation: it creates/updates package.json, package-lock.json, and node_modules, and it does not write opencode.json or .opencode/hi/** for you.

Then restart OpenCode and verify the installation:

npx --yes opencode-hi@latest doctor .

For the published 0.2.3 CLI, an existing Hi-owned older registration is upgraded explicitly with:

npx --yes opencode-hi@latest update .

Published 0.2.3 and development candidate 0.2.4 use the friendly install command with ensure semantics: no ownership means first setup, matching ownership at the target is NOOP, and a matching Hi-owned older registration is upgraded safely. setup remains the strict first-install command. All paths preserve unrelated OpenCode configuration and fail closed on ownership/config drift.

Development 0.2.4 keeps setup/install interactive only on a real terminal, but the normal-user wizard asks just one policy question: Auto, Working Manager, or Manager. Topology, execution depth, specialist thresholds, and parallelism are internal Hi runtime decisions. Provider authentication and the live model inventory remain OpenCode-owned. Child-model precedence is explicit task model → explicit ordered Hi role mapping → OpenCode agent model → ephemeral capability recommendation; automatic recommendations are never persisted as user preference, and cost/quality/feedback remain telemetry rather than routing authority. After OpenCode starts, type “Hi rol modellerini ayarla” in chat; Hi uses hi_role_models to list only effective connected models and persist explicit child-role choices. CI/piped automation remains deterministic with --non-interactive. Reopen the primary-mode question with npx --yes [email protected] reconfigure ..

OpenCode-Hi is the semantic and execution-control plane for evidence-aware AI software engineering on OpenCode. Hi owns the meaning of the work—Mission, Task, Worker, Role, Methodology, Authority, Evidence, Verification, recovery and completion—while OpenCode remains the primary native execution host for sessions, models, tools, permissions, PTY, workspace and other host primitives.

The core rule is simple:

Hi decides product semantics; OpenCode executes the richest correct native primitive.

Hi is designed to use the minimum sufficient topology, model, context and verification for the task instead of maximizing agents, tokens or ceremony.

Current product truth

The current immutable public release is [email protected] / v0.2.3. The current development source has the distinct candidate identity 0.2.4; it is not public merely because source metadata says 0.2.4. GitHub Releases and the npm registry remain authoritative for public availability. The published 0.2.3 release stays bound to its immutable Git tag/source, successful Ubuntu/Windows Release Readiness, npm Trusted Publishing provenance, and fresh-registry exact OpenCode 1.18.19 acceptance. The current repository source is [email protected], a prepublication development candidate. It is not the published npm/GitHub release and must not be presented as T4-certified until its own release gates complete.

Current host capability truth is generated from exact receipts rather than hand-maintained here. See Host Support and data/validation/compatibility-matrix-0.1.0.json.

What Hi adds

Hi adds deterministic semantics around native AI execution:

• one canonical Mission/Task/Worker ownership model;
• adaptive direct, delegated and bounded multi-agent execution;
• independent Role, model, Methodology and topology decisions;
• exact Authority and monotonic host Permission boundaries;
• bounded Mission runtime projection, durable context artifacts, TypeScript Semantic Context, and evidence-backed project methodology learning;
• lazy methodology/skill discovery and loading;
• structured Evidence, VerificationEnvelope and deterministic completion;
• bounded recovery, WAIT and authoritative STOP;
• Hi-owned process, isolated-workspace and browser executor surfaces backed by exact-host acceptance;
• restart-safe durable state for lifecycle-significant Hi semantics;
• ownership-aware install, upgrade, reconfigure, uninstall, rollback and crash recovery.

A model saying “done”, a screenshot existing, a skill being installed, or a host API merely existing is never enough to manufacture product support or completion.

Hi and OpenCode

User intent
   |
   v
Hi semantic assessment
   |
   v
Mission -> TaskRuntime -> Worker
   |          |             |
   |          +--> Role / model / Methodology
   |          +--> Authority / Permission
   |          +--> Context / methodology learning
   |          |
   |          v
   |       Hi HostPort
   |          |
   |          v
   |       OpenCode native execution
   |          |
   |          v
   +<-- observed result / Evidence / Verification
              |
              v
        recovery / WAIT / STOP
              |
              v
         deterministic completion

Hi semantics are host-portable; OpenCode-specific types and uncertain host behavior stay at adapter boundaries. OpenCode-native concepts keep their real names instead of being cosmetically renamed as Hi concepts.

Capability summary

The machine-readable compatibility projection is the canonical mutable support view. At the current recorded exact-host acceptance boundary:

• Process lifecycle: supported on the Hi-owned ProcessContract / ProcessExecutor surface. It covers PID-bound spawn, bounded IO, event-driven WAIT, timeout, kill, separate cleanup, restart adoption and STOP reconciliation. Arbitrary native/model-facing bash is not retroactively owned by Hi.
• Workspace isolation: supported on the Hi-owned IsolationDecision / WorkspaceLease / WorkspaceRuntime surface. Required isolation provisions and binds an alternate workspace, verifies execution there, preserves the primary/user-dirty worktree and reconciles cleanup/restart fail-closed.
• Browser execution: supported on the Hi-owned, runtime-health-gated browser surface. When mandatory local browser verification needs Chromium and the executable is absent, the development 0.2.4 runtime performs at most one bounded bootstrap attempt through pinned [email protected] into a Hi-owned platform cache. A failed/unavailable bootstrap becomes explicit environment/capability state; it does not self-feed verification continuations. Browser observations and screenshots are never automatically Evidence or PASS.
• HumanDecision: the chat transport is supported. A deterministic structured OpenCode question-opening UI transport is currently unsupported because the required public host opener is not exposed on the accepted host API.
• Semantic Context: the explicit first-class adapter currently supports TypeScript/TSX only. JavaScript, LSP and Tree-sitter semantic adapters are not claimed.

Exact version/platform/architecture and receipt links belong to Host Support, not duplicated prose here.

Installation status and first use

OpenCode-Hi's normal-user path is npm-registry-first. It is a one-shot package-runner bootstrap: no repository checkout, Bun, external Python, project-root npm install, project package.json, or persistent project-root node_modules is required.

npm registry — normal user path

For release 0.2.2, run the package directly and let the setup command add one exact Hi registration while preserving unrelated OpenCode configuration:

npx --yes [email protected] setup /path/to/project

Then restart OpenCode. OpenCode owns registry package materialization/cache and native plugin loading. After restart, check the static registration/ownership state and then the live runtime surface:

npx --yes [email protected] doctor /path/to/project

Inside the loaded OpenCode session, hi_doctor is the authority for live provider/model inventory and runtime capability truth. Package doctor does not pretend that a configured model is authenticated or successfully callable.

To move an installation that Hi already owns to a newer exact release, run that release's package runner:

npx --yes [email protected] update /path/to/project

setup/update mutate only the exact Hi plugin registration plus Hi-owned provenance under .opencode/hi/**; foreign plugins, providers, MCP configuration and unknown user fields are preserved. OpenCode itself may create .opencode/.gitignore, .opencode/package.json or .opencode/node_modules for its host-owned plugin runtime; those paths are not Hi-owned bootstrap state.

Command surfaces: package lifecycle vs loaded Hi runtime

The package runner and the loaded OpenCode plugin are deliberately separate command surfaces.

| Package command | Purpose | |---|---| | install | development 0.2.4: ensure the target exact Hi registration (first setup, safe owned update, or NOOP) | | setup | strict first Hi-owned exact plugin registration; development 0.2.4 opens the bounded project wizard when attached to a terminal | | update | explicitly move an already Hi-owned registration to the requested exact release; upgrade is an accepted alias | | doctor | static registration/ownership/drift/transaction check | | reconfigure | development 0.2.4: reopen the bounded project configuration wizard | | state | read-only package/project registration + routing summary; live Mission state remains runtime-owned | | reprofile | change only executionPolicy in project-owned routing state | | roles | print/set explicit child-role model/fallback/variant mappings | | rotate | rotate one child role's configured fallback order; never credentials/provider keys | | check-update | read npm registry version metadata and report an advisory; never mutates the project | | plan | preview the exact registration mutation without applying it | | rollback | restore the one recorded lifecycle rollback point when hashes still match | | recover | reconcile a recorded interrupted setup/update transaction |

After OpenCode loads the plugin, the runtime exposes 31 hi_* tools. The main user-facing diagnostics are hi_doctor, hi_status, hi_readiness, hi_metrics, and hi_ledger. The remaining tools are bounded control-plane primitives for task/worker dispatch, process execution, browser execution, context artifacts, temporary mutations, semantic assessment, and direct progress. The exact loaded tool IDs are host-verifiable through OpenCode's documented /experimental/tool/ids endpoint.

For current published 0.2.3, installation ownership is inspected with package doctor; live Mission state is inspected with runtime hi_status, hi_readiness, and hi_ledger. Development 0.2.4 additionally exposes Node-only state, reprofile, roles, rotate, and check-update package commands so common project configuration no longer requires the legacy Python helper.

Examples for the 0.2.4 candidate:

npx --yes [email protected] reconfigure .
npx --yes [email protected] state .
npx --yes [email protected] reprofile . --profile balanced
npx --yes [email protected] roles . --set coder=provider/model-a,provider/model-b
npx --yes [email protected] rotate . --role coder
npx --yes [email protected] check-update .

rotate only changes the ordered model fallback prior for the named Hi child role. It is not credential, API-key, provider-account, or primary-model rotation. manager and working-manager model ownership remains OpenCode-native.

Published 0.2.3 keeps setup deterministic. Development 0.2.4 adds a bounded terminal wizard without taking over provider authentication or fabricating model availability:

setup/install (TTY) -> project wizard -> restart OpenCode -> package doctor -> runtime hi_doctor
setup/install (CI/non-TTY) -> deterministic registration -> restart -> doctor -> hi_doctor

The normal-user wizard asks only for primary behavior (auto / working-manager / manager). Hi owns task topology, specialist selection, verification depth, and parallelism internally. After restart, type “Hi rol modellerini ayarla” in the OpenCode chat. The runtime hi_role_models tool lists only effective connected models and can save explicit ordered child-role model/fallback mappings; visual-qa only accepts vision-capable models. Without an explicit Hi mapping, Hi uses the OpenCode agent model when one exists, otherwise an ephemeral capability/variant recommendation over the live inventory. Automatic choices are not written back as preferences and are not reranked by cost/quality/feedback telemetry. manager / working-manager primary model selection and provider authentication remain OpenCode-owned. Use reconfigure to reopen only the primary-mode question; use --non-interactive for automation. The package roles command remains a deterministic CLI fallback.

Published availability is external state, not inferred from source version metadata alone. For 0.2.2, GitHub Release, npm Trusted Publishing/provenance, and fresh-registry exact-host verification are complete.

Git source — contributor/development compatibility path

Direct Git loading remains useful for source/CI compatibility work, but it is no longer the normal-user onboarding path. Contributors may register an exact repository SHA/spec and must prove the host actually loaded the plugin; unpinned Git is not a release identity.

Development/source loading

For repository development, build the runtime first:

npm ci --prefix plugin
npm run build:plugin

OpenCode supports project-local plugins under .opencode/plugins/ and local/file plugin loading on the accepted host. Runtime verification must confirm the plugin, Hi agents, tools and native skills actually load.

After plugin configuration changes, restart OpenCode when the host does not hot-reload them.

Before any future tag/push/release/publish step, contributors can run the exact-SHA read-only preflight:

npm run release:preflight -- --sha "$(git rev-parse HEAD)"

A committed evidence projection may be consumed from an ancestor checkpoint only when every intervening commit is evidence-only under data/validation/**. Any source, documentation, package, script, test, or runtime drift requires regeneration before the preflight can pass.

It requires a clean committed SHA, runs the canonical source/evidence verification and packed-public-doc checks used by publication, verifies package/version identity plus local/remote tag and npm-version absence, then captures npm pack --dry-run identity. It fails if those checks generate uncommitted drift. It never creates a tag, pushes, creates a GitHub Release, or publishes to npm.

See Installation and Lifecycle for Git/npm installation, upgrade, reconfigure, doctor, uninstall, rollback and recovery behavior.

Installed the plugin? Continue with the complete Configuration Guide for Windows, Linux, macOS, every supported option, primary/worker roles, single-model and per-role routing, multiple fallback models, variants, provider/model policy, concurrency, CLI/manual configuration, and troubleshooting.

Türkçe: Kurulum ve Yapılandırma Rehberi.

Configuration

Hi configuration is current-only and fail-closed. The canonical machine inventory is data/hi-config-options.json; each runtime option must have a validator, precedence, consumer, executable effect, documentation and tests. Unknown or stale configuration is not silently accepted as a compatibility feature.

Major control surfaces include execution policy/topology, primary mode, model routing, concurrency limits, context policy, methodology policy and compatibility diagnostics. Safety constraints cannot be widened by a lower-precedence layer.

See Installation and Configuration and Architecture.

Roles, models, Methodologies and skills

ROLE != AGENT != MODEL != METHODOLOGY != TASK != WORKER != TOPOLOGY.

Hi ships 27 built-in Methodologies under the hi-* namespace. A Methodology is reusable HOW; an OpenCode skill is the primary-host primitive used to discover/load its content. Installed skill != admitted Methodology != selected Methodology != loaded Methodology.

Role selection does not itself select a model, and a Methodology cannot grant Authority or own completion. See Methodologies and Skills.

Safety and control

Permission and Authority are different. OpenCode Permission governs what the host may execute; Hi Authority binds sensitive or external effects to the exact action/target/parameters/scope that were approved. Hi may narrow host permission but cannot silently widen a denial.

User dirty, staged and unrelated files remain user-owned. Hi never treats a broad reset/stash/checkout/restore or git add -A snapshot as a safe ownership shortcut.

Evidence is also different from prose. Worker/model output, Context, project methodology-learning state, Methodology content and browser observations do not become Evidence merely because they look convincing. Completion requires current obligations and fresh admissible proof to reconcile deterministically.

See Human Decisions and Authority, Verification, Security model.

State and recovery

Hi-owned project state lives under .opencode/hi/ according to explicit storage ownership. OpenCode-native plugin/skill directories remain OpenCode-owned. Durable state is current-schema only; restart reconciliation adopts exact owned resources or quarantines mismatches instead of inventing continuity.

See Architecture.

Documentation

• Documentation index
• Installation and configuration
• Architecture
• Host support
• Methodologies and skills
• Human decisions and authority
• Verification
• Security model
• Release engineering
• Contributing · Security · Support

Verification

Canonical repository checks are run from the repository root:

npm run check
python -m pytest -q tests/test_hi.py
python scripts/validate.py

Fresh test counts belong to command output, not hand-maintained documentation. Host-bound capability claims require exact T3 receipts; real external publication claims require T4 evidence.

See Verification Strategy.

License

OpenCode-Hi is Apache-2.0 licensed. External mechanisms, clean-room/reference-only decisions and attribution boundaries are recorded in Third-Party Notices.