opencode-sdd-engram-manage 🚀

Interactive SDD model selection and profile management for opencode.

Features

1. SDD Profile Management

Manage SDD (Spec-Driven Development) profiles from gentle-ai directly from the opencode TUI.

• Create: Create an empty SDD profile for manual configuration.
• Activate: Apply a saved profile to the global runtime config instantly — no restart required. Changes are live immediately.
• Edit Models: Pick a different provider/model for any agent or fallback directly from the UI.
• Bulk Actions: Use Bulk actions... to assign primary models, fallback models, or both across the whole profile.
• Profile Versions: Use Profile versions... to preview and restore saved snapshots before risky changes.
• Rename & Delete: Full lifecycle management for your profiles.
• Per-Agent Fallbacks: Configure a fallback model per managed base agent: sdd-* (except sdd-orchestrator), review-*, and jd-*. On activation, the plugin ensures matching *-fallback agents exist and stay in sync with their base agent config. Primary models are applied first, so you can define new agents and their fallbacks in a single profile activation.
• Active Profile Detection: The plugin automatically detects and highlights which profile matches the current config.

Profile Format

Profiles are stored as JSON files under ~/.config/opencode/profiles/:

{
  "models": {
    "sdd-init": "openai/gpt-4o",
    "sdd-spec": "anthropic/claude-sonnet-4-6",
    "sdd-apply": "anthropic/claude-sonnet-4-6"
  },
  "fallback": {
    "sdd-init": "google/gemini-flash-2.0",
    "sdd-apply": "openai/gpt-4o-mini"
  }
}

• models: primary model per managed base agent (sdd-*, review-*, jd-*, plus gentle-orchestrator when present in the runtime config).
• fallback: optional fallback model override per managed base agent name. If omitted, the fallback agent inherits the base model.

Profile versions are stored separately under ~/.config/opencode/profile-versions/, or $XDG_CONFIG_HOME/opencode/profile-versions/ when XDG_CONFIG_HOME is set. Version metadata is not written into the main profile JSON file, so profile files stay portable and focused on runtime model configuration.

Legacy flat format is also supported for backwards compatibility:

{
  "sdd-init": "openai/gpt-4o",
  "sdd-apply": "anthropic/claude-sonnet-4-6"
}

---

2. Engram Project Memories

Full integration with the Engram memory system via its HTTP API.

• List: Browse all stored observations for the current project (resolved across git remote, git root, and cwd aliases). Calls the Engram server on port 7437.
• Read: View full memory content, type, scope, and timestamp.
• Delete: Logically remove a memory via the Engram API to prevent it from affecting the current session context.

---

Installation

Add the plugin to your tui.json:

~/.config/opencode/tui.json

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["opencode-sdd-engram-manage"]
}

Check current version

To check the latest published version on npm:

npm view opencode-sdd-engram-manage version

To check the version currently cached by OpenCode:

jq -r .version ~/.cache/opencode/packages/opencode-sdd-engram-manage@latest/node_modules/opencode-sdd-engram-manage/package.json

Note: the cache path above assumes you installed the plugin as opencode-sdd-engram-manage@latest (or without an explicit version). If you pin a version, the cache directory name will use that pinned spec instead.

Update

OpenCode installs npm plugins automatically and caches them. To force OpenCode to fetch the latest published version, remove the cached package and restart OpenCode:

rm -rf ~/.cache/opencode/packages/opencode-sdd-engram-manage@latest

You can also pin a specific version in tui.json:

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["opencode-sdd-engram-manage@1.2.0"]
}

---

Usage

Open the plugin with:

• Shortcut: Alt + K (Linux/Win) or Cmd + K (macOS)
• Slash command: /sdd-model

To customize the shortcut, create ~/.config/opencode/sdd-model-select.json:

{
  "shortcut": "ctrl+j"
}

Notes:

• shortcut accepts one binding string. If it starts with alt+, the plugin also registers the matching super+ binding for macOS compatibility.
• shortcuts accepts an explicit array when you want full control:

{
  "shortcuts": ["ctrl+j", "super+j"]
}

Workflow

1. Open the plugin (Alt+K / Cmd+K or /sdd-model).
2. Create a profile for your project, or Manage Profiles to activate/configure one.
3. From the profile detail, click any agent to change its model (provider → model picker).
4. Click any fallback entry to override its model.
5. Use Bulk actions... when you want to configure many agents at once.
6. Use Profile versions... to preview or restore previous snapshots.
7. Activate to apply the profile to the live runtime.

Bulk Profile Actions

From a profile detail screen, Bulk actions... lets you apply one model selection to many phase entries:

• Set all primary phases: fill missing primary phase models only.
• Set all fallback phases: fill missing fallback phase models only.
• Set all phases and fallbacks: fill missing primary and fallback phase models.
• Override all primary phases: replace every primary phase model after confirmation.
• Override all fallback phases: replace every fallback phase model after confirmation.
• Override all phases and fallbacks: replace every primary and fallback phase model after confirmation.

The difference is intentional:

• Set actions are fill-only. They keep existing values and only populate empty entries.
• Override actions are overwrite operations. They can replace existing choices, so the UI asks for confirmation before applying them.

Compact flow example:

Before: profile has mixed primary models and missing fallbacks.
Bulk action: Set all fallback phases → google/gemini-flash-2.0.
After: existing primary models stay untouched; empty fallbacks are filled.
Safety: Profile versions... → preview the saved snapshot → restore if the bulk change was not what you wanted.

Before any bulk operation is applied, the plugin saves a profile version automatically.

Compact text screenshots

These compact mockups show the new profile flows without relying on image assets:

Profile: team-default                         active
──────────────────────────────────────────────────
Primary phases
  sdd-spec      anthropic/claude-sonnet-4-6
  sdd-apply     openai/gpt-5.5

Fallback phases
  sdd-spec      google/gemini-flash-2.0
  sdd-apply     inherited from primary

[Activate]  [Bulk actions...]  [Profile versions...]

Bulk actions
──────────────────────────────────────────────────
Set
  Set all primary phases
  Set all fallback phases
  Set all phases and fallbacks

Override
  Override all primary phases        requires confirmation
  Override all fallback phases       requires confirmation
  Override all phases and fallbacks  requires confirmation

Profile versions: team-default
──────────────────────────────────────────────────
When                  Bulk                         Phase
2026-04-26 14:08      Set all fallback phases      all fallback phases
2026-04-26 13:52      Override all primary phases  all primary phases
2026-04-26 13:10      Manual edit                  sdd-apply

Preview version 2026-04-26 14:08
──────────────────────────────────────────────────
models.sdd-apply      openai/gpt-5.5
fallback.sdd-apply    google/gemini-flash-2.0

[Restore this version]  [Back]
Restore? This replaces the current profile file.

Profile Versions

Use Profile versions... from the profile detail screen to review saved profile snapshots.

• Versions are created automatically before bulk profile actions.
• Versions are also created automatically before individual primary or fallback phase model changes.
• Profile versions use one unified history for bulk actions and individual phase changes, retaining the latest 60 snapshots per profile.
• Each version can be previewed before restoring it.
• Restore writes the selected snapshot back to the profile file.

Version history is stored outside the profile JSON under ~/.config/opencode/profile-versions/, or $XDG_CONFIG_HOME/opencode/profile-versions/ when configured. The profile JSON itself only contains model data (models and fallback); version metadata is kept out of the main profile file.

---

Screenshots

This is what users will see after installing the plugin:

Main entry and profile management

Engram memory browser

Profile JSON preview

---

Orchestrator Fallback Policy Script

This repo includes a script to ensure the sdd-orchestrator prompt contains the fallback policy block required for managed *-fallback agents to work correctly when a primary sub-agent fails.

• Script: scripts/ensure-orchestrator-fallback-policy.ts
• Supports: Inline prompt text in opencode.json and external {file:...} references.

# Check mode (no changes)
npm run orchestrator:fallback:check

# Apply changes
npm run orchestrator:fallback:apply

# Custom config path
node ./scripts/ensure-orchestrator-fallback-policy.ts --config /path/to/opencode.json

---

Example Fixtures & Smoke Validation

Under examples/:

• opencode-inline.json — inline orchestrator prompt config
• opencode-external.json + sdd-orchestrator-example.md — external prompt file config
• profiles/*.json — profile payloads in new and legacy formats

Run smoke validation:

npm run examples

Validates:

1. Fallback policy injection for inline and external prompt configs.
2. Profile fixture readability for new (models + fallback) and legacy formats.

---

Development

Contributing

Community PRs are welcome, but they must follow the repository review policy:

• start from a GitHub issue
• use a focused branch such as feat/short_description or fix/short_description
• keep the diff as small as possible
• justify broader changes clearly in the PR description

See CONTRIBUTING.md for the full workflow and review requirements.

Running Tests

npm test

Test coverage:

• src/profiles.test.ts — profile read/write, fallback sync, validation, activation logic
• src/memories.test.ts — memory listing, deletion, normalization, sqlite query escaping
• src/utils.test.ts — formatting helpers, agent naming predicates, model resolution
• src/config.test.ts — path resolution, XDG support, project name detection
• scripts/ensure-orchestrator-fallback-policy.test.ts — fallback policy injection logic

Automated Releases

Uses semantic-release on pushes to main. See docs/publish.md for the full publish workflow and commit conventions.

---

Technical Details

• Package: opencode-sdd-engram-manage
• Current version: see CHANGELOG.md or npm
• Requires: opencode >= 1.3.13, Engram server running on port 7437.
• Peer dependencies: @opencode-ai/plugin >= 1.14.29, @opentui/core >= 0.2.0 < 1, @opentui/solid >= 0.2.0 < 1, solid-js 1.9.12
• License: MIT

Developed by j0k3r-dev-rgl.