Keyboard-first ODD profiles for OpenCode: create, version, and activate model profiles across the V2 agent suite.
Quick Start · Installation · Usage · Documentation · Credits
About ODD
ODD (Organic-Driven Development) is this project's organic default: explore before code, keep understood changes lightweight, give each authorized substantial task one recoverable feature document, check results, and maintain progress. Proportional implementation and verification apply throughout. Upstream SDD remains optional and supported;
sdd-*agent IDs, storage paths, and changelog/spec history below are legacy identifiers and are intentionally retained for compatibility.
Project Lineage
This repository is an independently maintained derivative of
j0k3r-dev-rgl/sdd-engram-plugin. The original MIT copyright and license are preserved inLICENSE. See Origin and Attribution.
When developing complex systems with OpenCode, orchestrating multi-phase ODD workflows requires distinct AI models, varying reasoning effort levels, resilient fallback policies, and continuous visibility over project progress. Managing these configurations across disparate JSON files is error-prone, fragile, and difficult to audit.
The OpenCode ODD Profile Manager unifies these capabilities into an integrated, keyboard-driven terminal user interface (OpenTUI) and offline dashboard ecosystem:
- ODD Profile Manager (Host Plugin) (legacy package ID
opencode-sdd-profile-manager): Centralized profile creation, model assignment, reasoning effort configuration, fallback routing, version snapshots, and Engram memory inspection. - Suite de Agentes (Agent Suite): Dynamic agent catalog, custom agent authoring, per-agent provider selection, and turn-scoped security consent boundaries.
- Task Manager Portable: Offline single-file HTML project cockpit with Kanban boards, ODD phase trackers, Git commit lineage, and CodeGraph architectural mapping.
- Session Vault: Retention management with pin locks, configurable quota profiles, local gzip backups, and direct Alt+V TUI for managing OpenCode conversation databases.
- Agent Task Manager: Automated project task synchronization via structured JSON island state without runtime dependencies.
- GitHub Integration: Issue triage, PR readiness checks, CI/CD diagnosis, and automated semantic release workflows.
- Native Agents: Direct management of standard OpenCode built-in agents alongside ODD Core, Judgment Day, and Reviewer agents.
| Component | Identifier / Package | Version | Distribution Location | Role & Purpose |
|---|---|---|---|---|
| ODD Profile Manager | opencode-sdd-profile-manager (legacy package ID, unchanged) |
2.1.0 |
Root / dist/tui.js |
Principal plugin pack, OpenTUI host, profile versioning, Engram browser |
| Suite de Agentes | opencode-agent-suite |
1.1.0 |
plugins/suite-de-agentes |
Agent catalog, custom agent authoring, per-turn consent enforcement |
| Task Manager Portable | task-manager-portable |
1.1.0 |
plugins/task-manager |
Single-file offline project cockpit, Kanban, Git history, CodeGraph maps |
| Session Vault | opencode-session-vault |
0.1.0 |
plugins/opencode-session-vault |
Retention management with pin locks, quota profiles, local backups, and Alt+V shortcut |
| Agent Task Manager | task-tracker-manager |
1.1.0 |
Embedded Skill / Adapter | Automated task synchronization and JSON island state updates for AI agents |
| GitHub Integration | gh-actions-workflows |
2.0.1 |
.github/workflows |
Semantic release automation, CI/CD verification, issue/PR management |
| Native Agents Manager | built-in-agents |
2.0.1 |
src/catalog.ts |
Unified management of OpenCode built-ins (build, plan, general, etc.) |
The following sections provide a complete visual walkthrough of all components included in the plugin pack.
Legacy screenshots below still show SDD branding in the captured UI; asset paths are retained for compatibility. Replacement captures are pending where marked.
The core OpenTUI interface provides fast, keyboard-first navigation for profile lifecycle management, model mapping, and fallback synchronization.
Quickly switch the active ODD profile from anywhere within OpenCode. The active configuration is persisted across restarts with a distinct ✓ Active marker.
Create new profiles, clone existing templates, edit agent assignments, inspect version history, or delete deprecated profiles.
View all 25 ordered agents categorized into Orchestrator, ODD Core (legacy sdd-* IDs), Judgment Day, Reviewers, and Auxiliaries with their active model assignments. The roster renders as a text list grouped by category; no screenshot asset is bundled.
Inspect per-agent fallback models, reasoning effort levels, and runtime eligibility status. Details render inline as text fields in the dialog; no screenshot asset is bundled.
Review automatic snapshot histories before applying bulk changes or restoring a prior stable configuration.
Assign models across entire agent categories simultaneously in either Complete Missing or Overwrite mode.
Configure model reasoning effort (low, medium, high, xhigh, max) per agent according to provider metadata.
Configure explicit fallback models for resilient sub-agent failure recovery during long-running ODD executions.
Access integrated companion plugins—including Suite de Agentes and Task Manager—directly from the principal TUI interface.
Suite de Agentes provides an OpenTUI catalog to browse built-in and custom agents, inspect operational prompts, assign models, and enforce per-turn security consent boundaries.
Search, filter, and navigate across all registered seed and custom agents with continuous pagination and keyboard control.
Filter agents by category, search by name or skill, and inspect operational metadata.
Inspect detailed agent configurations, including prompt instructions, assigned provider models, and role boundaries.
Audit registered agent skills, tool permissions, and consent requirements before dispatching tasks.
Task Manager Portable provides a standalone, single-file offline HTML cockpit that visualizes project health, task progress, CodeGraph architecture, and Git commits directly in the browser via file://.
Monitor global sprint progress, status distributions, active risks, and task columns in an interactive HUD.
Filter tasks by phase, owner, tag, or status with real-time token telemetry and execution diagnostics.
Track ODD lifecycle progression across proposal, specification, design, task planning, implementation, and verification phases.
Visualize codebase modules, symbol dependencies, and impact boundaries derived from CodeGraph intelligence.
Document repository folder structure, architectural boundaries, and component layout in a clean tree view.
Audit declared Git commits, branch synchronization, and receipt verification history without touching .git directly.
Access offline documentation, keyboard shortcuts, legend descriptions, and state export tools.
The ODD Profile Manager plugin pack (legacy package ID opencode-sdd-profile-manager, unchanged) can be deployed via release archives, npm packages, or built directly from source.
Release availability: npm/release artifacts below refer only to published GitHub Releases or npm packages. The V2 source is committed on
main(PR #34); the archivedsdd-profile-manager-v2.0.1bundle predates V2 and does not include the V2 host bridge. Use the latest release for current archives.
Download the latest versioned release archive from GitHub Releases (the archived sdd-profile-manager-v2.0.1.zip/.tar.gz predates V2 and does not include the V2 host bridge).
-
Extract the release archive into your OpenCode plugins directory:
- Linux / macOS:
~/.config/opencode/plugins/sdd-profile-manager - Windows:
C:\Users\<user>\.config\opencode\plugins\sdd-profile-manager
- Linux / macOS:
-
Register the plugin in
tui.json(~/.config/opencode/tui.jsonor%USERPROFILE%\.config\opencode\tui.json):{ "$schema": "https://opencode.ai/tui.json", "plugin": [ "~/.config/opencode/plugins/sdd-profile-manager/dist/tui.js" ] }Windows example:
{ "$schema": "https://opencode.ai/tui.json", "plugin": [ "C:\\Users\\<user>\\.config\\opencode\\plugins\\sdd-profile-manager\\dist\\tui.js" ] } -
Restart OpenCode.
The
opencode-sdd-profile-managerpackage is not published to the npm registry. Do not expectnpm installor automatic host resolution to find it. Thetui.jsonsnippet below is the intended entry once published; until then use themain-branch source directory installer in Option C.
{
"$schema": "https://opencode.ai/tui.json",
"plugin": [
"opencode-sdd-profile-manager"
]
}Migration from v1.x (
opencode-sdd-engram-manage): If upgrading from legacyopencode-sdd-engram-manage, update the plugin name intui.jsontoopencode-sdd-profile-manager. All existing profiles in~/.config/opencode/profiles/and snapshots in~/.config/opencode/profile-versions/remain fully compatible.
git clone https://github.com/RamonsDka/opencode-sdd-profile-manager.git
cd opencode-sdd-profile-manager
nvm use
npm ci
npm run buildThe build compiles the main TUI bundle into dist/tui.js and synchronizes vendored plugin assets into dist/plugins/.
Add the absolute path to dist/tui.js in your tui.json and restart OpenCode.
V2 local source install (this
maincheckout path only):node scripts/install-v2-local.mjsis a dry-run by default and prints the plannedcli.json/opencode.json(c)directory entry for this checkout. Pass--applyexplicitly to write the change; unrelated entries are preserved and no build step runs. This describes the localmainsource only, not a published release.
For detailed deployment guidance, see docs/installation.md.
- Open OpenCode and press
Alt+K(or run/sdd-modelin chat). - Select Manage ODD profiles.
- Choose Create new ODD profile and enter a name (e.g.
team-production). - Select individual agents or use Bulk actions to assign models, reasoning effort, and fallbacks.
- Choose Activate profile to apply the configuration to OpenCode.
- Reopen the profile list to confirm the
✓ Activemarker. - To access companion plugins, choose Plugins... to launch Suite de Agentes, Task Manager, or Session Vault (direct
Alt+V).
Profiles and version snapshots are stored cleanly outside the repository:
~/.config/opencode/profiles/ # Portable profile JSON files
~/.config/opencode/profile-versions/ # Version snapshot history
The ODD Profile Manager operates as a modular TUI plugin and orchestrator. It does not overwrite global OpenCode configuration arbitrarily; it applies changes safely through validated host APIs while preserving declarative {file:...} prompt references.
OpenCode Host (TUI & Server Runtime)
│
├── index.tsx # Lifecycle, command registry, status badge
│
└── src/dialogs.tsx # OpenTUI workflows, sizing, and navigation
│
├── src/catalog.ts # 25-agent ordered catalog & eligibility rules
├── src/profiles.ts # Profile I/O, atomic persistence, version snapshots
├── src/profile-reasoning.ts # Reasoning effort provider resolution
├── src/orchestrator.ts # Orchestrator prompt aliases & fallback policy
├── src/host-compat.ts # OpenTUI screen-aware dialog sizing & graceful degradation
├── src/memories.ts # Engram HTTP client for project observations
├── src/config.ts # Configuration paths & project resolution
│
└── src/plugins/ # Integrated Sub-Plugin Hub
├── registry.ts # Plugin discovery & path security guards
├── suite-adapter.ts # Suite de Agentes runtime bridge
├── task-manager-*.ts# Task Manager dispatcher, coordinator, git & telemetry
└── offline-help.ts # Self-contained documentation renderer
- Host API Isolation: Profile activation reads on-disk configuration, applies verified model overrides, configures reasoning effort, and updates OpenCode state without modifying unrelated agent configurations.
- Offline Dashboard Independence: Task Manager Portable (
Task-Manager-Portable.html) runs entirely client-side viafile://. It contains zero runtime network dependencies, does not execute shell scripts, and reads only its embedded#tm-stateJSON island. - Agent Consent Enforcement: Suite de Agentes enforces an internal allowlist for ODD agents (legacy
sdd-*IDs) and requires per-turn user authorization for external sub-agents, preventing untrusted task executions.
See docs/architecture.md for data flows and subsystem responsibilities.
Security, privacy, and deterministic execution are fundamental architectural principles of this plugin pack:
- Zero Credential Exposure: Never stores API keys, authentication tokens, passwords, or personal credentials in profile JSON, version history, or repository files.
- Local-First Processing: All profile switching, catalog indexing, and task management run locally on the user's workstation without third-party cloud telemetry.
- Engram HTTP Boundary: Communicates with the local Engram instance (
http://127.0.0.1:7437) over loopback HTTP. No memory contents leave the local machine. - NotebookLM Containment & Exclusions: When interacting with external documentation or research sources such as NotebookLM, operations are strictly sandboxed and read-only. NotebookLM workflows are bounded: no private codebase secrets, authorization cookies, local usernames, or proprietary source code are exported or transmitted to external endpoints.
- Safe Path Resolution: Profile names and file references are strictly sanitized to prevent directory traversal (
../) and unauthorized filesystem access. file://Sandbox Compliance: Task Manager Portable adheres to opaque origin restrictions in modern browsers, ensuring that opening the HTML dashboard locally never exposes the host filesystem to remote scripts.
This project follows Semantic Versioning (SemVer) and automated release management via semantic-release:
- Automated Changelogs & Tags: Pushes to
mainevaluate commit messages following the Conventional Commits standard. - Release Automation:
fix:triggers a Patch release (e.g.2.0.0->2.0.1).feat:triggers a Minor release (e.g.2.0.0->2.1.0).feat!:orBREAKING CHANGE:triggers a Major release (e.g.2.0.0->3.0.0).
- Synchronized Plugin Assets: Release packaging (
scripts/package-release.mjs) generates verifiable ZIP/tar.gz bundles containing the main bundle, vendored sub-plugins, documentation, and SHA-256 checksums.
For detailed release workflows, see docs/publish.md.
The repository maintains strict test coverage and package hygiene validation:
# Install clean dependencies
npm ci
# Run strict TypeScript type checking
npm run typecheck
# Run full Vitest test suite
npm test
# Run plugin pack integration and smoke verification
npm run verify:plugins
# Test fallback policy mechanics
npm run test:fallback
# Check and apply orchestrator fallback policy
npm run orchestrator:fallback:check
npm run orchestrator:fallback:apply
# Build production bundle and copy plugin assets
npm run buildFor complete testing guidance, see docs/testing.md.
| Symptom | Cause | Resolution |
|---|---|---|
Alt+K does not open the TUI |
Shortcut intercepted or plugin not registered | Use /sdd-model or :sdd-model. Ensure dist/tui.js is registered in tui.json and OpenCode was restarted. |
| Active profile indicator missing | Profile not yet activated or renamed externally | Open the profile in the manager and select Activate profile. The state is stored in OpenCode KV state. |
| Reasoning effort disabled for an agent | Model does not support configurable effort | Ensure a model that advertises reasoning effort (e.g. Claude 3.7 Sonnet, o-series, Gemini Flash Thinking) is selected. |
| Engram project memories empty | Engram server not running or wrong directory | Verify Engram is running locally on port 7437. Profile management continues working independently. |
| Task Manager displays blank dashboard | Corrupted JSON state in HTML island | Verify the #tm-state JSON structure matches Schema 1.0. Check browser developer console for JSON syntax errors. |
| Browser blocks Task Manager file access | Normal browser file:// security policy |
Task Manager is intentionally self-contained; provide data through the embedded #tm-state script tag. |
For detailed troubleshooting scenarios, see docs/troubleshooting.md.
| Document | Purpose & Contents |
|---|---|
docs/installation.md |
Comprehensive installation, release archives, npm packages, and platform setup |
docs/usage.md |
Step-by-step user guide for profile lifecycle, bulk actions, and reasoning effort |
docs/architecture.md |
Technical architecture, plugin pack integration, data flows, and subsystem boundaries |
docs/troubleshooting.md |
Diagnostic runbooks for keybindings, plugin loading, Engram, and dialogs |
docs/testing.md |
Test suite organization, coverage standards, and verification commands |
docs/compatibility.md |
Host API contracts, graceful degradation, and OpenTUI version compatibility |
docs/dialogs.md |
Screen-aware dialog sizing, UX tiers, and responsive layout rules |
docs/dependencies.md |
Dependency graph, locked peer versions, and Node 24 runtime policies |
docs/profile-reasoning-effort.md |
Reasoning effort configuration, model metadata, and runtime behavior |
docs/publish.md |
Automated semantic release workflow, commit standards, and artifact distribution |
docs/engram-http-migration.md |
Engram HTTP API architecture, endpoint specifications, and integration design |
docs/npm-vulnerability-audit.md |
Security audit analysis, transitive peer dependency reviews, and upstream status |
plugins/suite-de-agentes/README.md |
Suite de Agentes sub-plugin documentation, catalog, and consent controls |
plugins/task-manager/README.md |
Task Manager Portable documentation, JSON island architecture, and features |
This codebase is an independently maintained derivative of:
- Original Repository:
j0k3r-dev-rgl/sdd-engram-plugin - Original Package:
opencode-sdd-engram-manage - Original Author & License Holder:
j0k3r-dev-rgl - License: MIT
The original MIT copyright and license notices are fully preserved in LICENSE and NOTICE.md.
Credit: ODD methodology inspiration by Alan Buscaglia (Gentleman Programming) and Gentle-AI. This is an independent project with no official endorsement.
We welcome contributions! Please review CONTRIBUTING.md for commit standards, issue-first workflow, and testing requirements before opening a pull request.
Please report security issues responsibly. Never share private tokens, API keys, or proprietary codebase contents. See SECURITY.md for full reporting guidelines.
Distributed under the MIT License.















