OpenCode Toolkit

A small, OpenCode V2-native package containing a curated set of engineering workflows adapted from ECC, plus a read-only project-status tool and a conservative project installer.

This is a pre-release (0.1.0-rc.1) targeting OpenCode 2.0.24 and Node.js 20 or newer. It is not published to npm; install the package tarball attached to the repository release.

Included

Skills: coding standards, security review, and test-driven development.
Subagents: planner, code reviewer, and security reviewer.
Plugin tool: toolkit_project_status, implemented against OpenCode's V2 VCS API and exposed in the toolkit Code Mode namespace.
Optional memory tools, disabled by default. Session memory is isolated by project and session; shared project memory requires a separate opt-in.
Project installer with JSONC-preserving plugin registration, file ownership hashes, collision checks, and protection for locally modified files.

Provider/model selection remains the user's OpenCode configuration. The package does not enable hooks through a global install or configure credentials.

Optional memory

Memory is off unless enabled in the consuming project's plugin options. To turn on session memory, convert the installer-added plugin string into an object entry, keeping its existing local package path:

{
  "plugins": [
    {
      "package": "./node_modules/@sargatxet/opencode-toolkit",
      "options": {
        "memory": {
          "enabled": true,
          "retentionDays": 30
        }
      }
    }
  ]
}

If the project uses .opencode/opencode.json, retain the different relative path the installer registered (typically ../node_modules/...). The toolkit does not automatically capture prompts, tool results, or session summaries. Use toolkit_memory_save, toolkit_memory_list, toolkit_memory_get, and toolkit_memory_delete explicitly. Retrieval and list previews are returned to the current model session as tool output. Memory content is stored through OpenCode's plugin storage; do not store credentials or secrets.

Session scope is the default and is limited to the current project/session. Project-wide sharing remains disabled unless the options also contain "project": true inside memory. Project memories are shared by sessions and worktrees belonging to the same canonical OpenCode project. Retention defaults to 30 days and can be set from 1 to 3650 days. Expired records are not returned and are deleted when accessed; there is no background cleanup job. Delete individual records explicitly with toolkit_memory_delete.

Uninstall preserves a plugin object entry because it may contain user options. If you enabled memory by converting the installer-added string to an object, remove that plugin entry from the project config yourself when uninstalling.

Install the pre-release

From the project where you want to use the toolkit, run:

npm install --save-dev "https://git.sargatxet.cloud/sargatxet/opencode-toolkit/releases/download/v0.1.0-rc.1/sargatxet-opencode-toolkit-0.1.0-rc.1.tgz"
npx opencode-toolkit install .

This installs the prebuilt package and dependencies directly from the release; you do not need to clone the repository or build it. Node.js 20+ and npm must be installed. OpenCode itself should be version 2.0.24 for the validated setup.

The installer copies the selected skills and agents into .opencode/, registers the local package directory from node_modules in the applicable project config, and writes an ownership manifest. This avoids asking OpenCode to fetch the package from npm. It does not overwrite unmanaged files. If a managed file has been edited since installation, updates stop rather than replacing it. If both opencode.json and .opencode/opencode.json exist, installation stops until the project consolidates them; this avoids ambiguous V2 config precedence.

To remove managed content and the plugin entry when the installer added it:

npx opencode-toolkit uninstall .

Modified managed files are preserved and reported. The installer does not yet remove the npm dependency from the consuming project's package.json; remove that dependency separately if desired.

To update, install the newer checkout or tarball into the consuming project, then rerun the installer. It updates files that still match their recorded hashes and refuses to overwrite a locally modified current file:

npm install --save-dev /path/to/new-opencode-toolkit.tgz
npx opencode-toolkit install .

Verify a package tarball

For a release candidate, build the package and create a tarball from the checkout:

npm pack

This creates sargatxet-opencode-toolkit-0.1.0-rc.1.tgz for the current pre-release. In a disposable project, install that tarball rather than linking the checkout:

npm install --save-dev /path/to/sargatxet-opencode-toolkit-0.1.0-rc.1.tgz
npx opencode-toolkit install .
npx opencode-toolkit install .

The second install should make no content changes. Check that the expected toolkit-* agents and skills are present under .opencode/, and that the project config contains the local package plugin path. To verify removal, first edit one installed toolkit file, then run:

npx opencode-toolkit uninstall .

The edited file should be reported as preserved; unmodified managed files and the toolkit plugin entry should be removed. These install/uninstall checks need no model credentials. Plugin activation and tool execution were separately smoke-tested with OpenCode 2.0.24 and a local mock OpenAI-compatible endpoint. Provider-backed agent delegation and skill behavior remain unverified. Memory behavior is covered by deterministic storage-contract tests; persistence inside a running OpenCode profile and provider-backed learning flows are not yet verified.

Safety boundaries

The installer rejects unmanaged-file collisions, symlinked install paths, and managed files changed since installation. Its ownership manifest is local bookkeeping, not a signed security boundary. Path checks do not protect against another process changing the project tree concurrently; use it on a project directory whose filesystem is trusted. Uninstall removes files incrementally, so resolve any reported I/O error and rerun it rather than deleting the manifest manually. See docs/SECURITY-REVIEW.md for the review scope and limitations.

After installation, restart or reload OpenCode and select the installed toolkit-* skills or subagents as needed. The plugin exposes its namespaced tool through Code Mode. Configure and authenticate your provider normally in OpenCode.

Development

npm install
npm run typecheck
npm test
npm run test:coverage
npm pack --dry-run

The package is tested against OpenCode 2.0.24 and Node.js 20+. The unit and installer tests are deterministic and do not call an LLM. Plugin activation and tool execution were smoke-tested with a local mock OpenAI-compatible endpoint; provider-backed agent delegation and skill behavior remain unverified.

Provenance and security

docs/PROVENANCE.md: ECC source revision, attribution, adaptations, and content hashes.
docs/SECURITY-REVIEW.md: review scope, result, and operational limitations.

License

The new implementation is MIT licensed. Adapted ECC material remains subject to the preserved MIT notice and attribution described in NOTICE.md.

7.4 KiB Raw Blame History