Package Exports

superego-opencode
superego-opencode/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (superego-opencode) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Superego OpenCode Plugin

TypeScript adapter for running superego with OpenCode.

Status: In Development

This plugin enables superego's metacognitive oversight for OpenCode users, using the same .superego/ configuration as the Claude Code plugin.

Architecture

Superego uses a shared core with adapters pattern:

.superego/                    # Shared core (language-agnostic)
├── prompt.md                 # Evaluation criteria
├── config.yaml               # Settings (threshold, model, etc.)
├── sessions/<id>/            # Per-session state & decisions
│   ├── state.json
│   ├── feedback
│   └── decisions/
└── ...

plugin/                       # Claude Code adapter (shell scripts)
opencode-plugin/              # OpenCode adapter (TypeScript)

What's Shared

Evaluation prompt (prompt.md)
Configuration schema (config.yaml)
Decision format: DECISION: ALLOW|BLOCK\n\n<feedback>
Session state and decision journal structure

What Adapters Handle

Concern	Claude Code	OpenCode
Hook registration	Shell scripts in `plugin/`	TypeScript in `.opencode/plugin/`
LLM invocation	Claude CLI	Configurable (Gemini, etc.)
Transcript access	`$CLAUDE_TRANSCRIPT_PATH` env var	`client.session.messages()` SDK
Feedback delivery	Block hook with JSON	TBD

Hook Mapping

Superego Hook	Claude Code	OpenCode
Session start (inject contract)	`SessionStart`	`session.created`
Pre-tool evaluation	`PreToolUse`	`tool.execute.before`
Final evaluation	`Stop`	`session.idle`

Quick Start

Option A: Download from GitHub Release (easiest)

cd /path/to/your/project

# 1. Download pre-built plugin
curl -L -o superego.js https://github.com/cloud-atlas-ai/superego/releases/latest/download/index.js

# 2. Install plugin
mkdir -p .opencode/plugin
mv superego.js .opencode/plugin/

# 3. Start OpenCode
opencode

# 4. Initialize superego by asking OpenCode to use the 'superego' tool with the 'init' command.
# For example: "use the superego tool to initialize the project"

Option B: Build from source

# 1. Clone and build
git clone https://github.com/cloud-atlas-ai/superego.git /tmp/superego
cd /tmp/superego/opencode-plugin
bun install
bun build src/index.ts --outdir dist --target bun

# 2. Install plugin
cd /path/to/your/project
mkdir -p .opencode/plugin
cp /tmp/superego/opencode-plugin/dist/index.js .opencode/plugin/superego.js

# 3. Start OpenCode and ask it to initialize superego. For example: \"use the superego tool to initialize the project\"
opencode

Option C: Global install

# 1. Download plugin
curl -L -o superego.js https://github.com/cloud-atlas-ai/superego/releases/latest/download/index.js

# 2. Install globally
mkdir -p ~/.config/opencode/plugin
mv superego.js ~/.config/opencode/plugin/

# 3. In each project, ask OpenCode to initialize superego. For example: "use the superego tool to initialize the project"

Evaluation Modes

Superego supports two evaluation modes (default: pull):

Mode	Description
`pull`	On-demand evaluation only. Use `superego_review` tool at decision points. (Default)
`always`	Automatic evaluation on session idle (more aggressive).

To change modes: use the superego tool with mode command and specify always or pull.

Tool Commands

The plugin provides two tools:

`superego` - Management commands

Command	Description
`status`	Check if superego is initialized and enabled (default)
`init`	Initialize superego, creates `.superego/` and fetches prompt
`disable`	Temporarily disable superego (hooks won't fire)
`enable`	Re-enable superego after disable
`remove`	Remove superego from project (deletes `.superego/`)
`mode`	Show or change evaluation mode (`always` or `pull`)

Usage: To initialize superego, ask OpenCode: "use the superego tool with init".

`superego_review` - On-demand evaluation

Use this tool at decision points to get feedback:

Before committing to a plan or approach
When choosing between alternatives
Before non-trivial implementations
When the task feels complex or uncertain
Before claiming work is done

Requires the current session ID as argument.

Test Plan

After installation, verify each step in order:

Step	What to do	Expected log output
1. Plugin loads	Start OpenCode in a project with `.superego/`	`[superego] Plugin loaded`
2. Session created	Start a new chat	`[superego] Session created: <uuid>`
3. Contract injected	(automatic)	`[superego] Contract injected`
4. Have a conversation	Ask OpenCode to do something, wait for response	`[superego] Session idle: <uuid>`
5. Evaluation runs	(automatic on idle)	`[superego] Got N messages`, `[superego] Calling LLM via OpenCode...`
6. Response logged	(automatic)	`[superego] LLM response: DECISION: ALLOW...` or `BLOCK...`

Troubleshooting

"Not initialized, skipping": Create .superego/ directory with prompt.md
"No prompt.md found": Copy default_prompt.md to .superego/prompt.md
No logs at all: Check OpenCode console output, verify plugin file is named superego.js

Configuration

Requires:

.superego/prompt.md - evaluation criteria (same as Claude Code)
OpenCode configured with an LLM provider

Key architectural advantage: The OpenCode plugin uses OpenCode's own session/LLM API for evaluation. This means:

No separate API keys - uses whatever model/provider OpenCode is configured with
No sg binary required - pure TypeScript, no Rust toolchain needed
Same model for work and oversight - evaluation runs on the same LLM as the main session

This is a departure from the Claude Code plugin which shells out to claude -p. Consider backporting this pattern to Claude Code for consistency.

Known Limitations (Needs Validation)

session.created event structure assumed (properties.id)
client.session.messages() response structure assumed
client.session.prompt() API for contract injection untested
No UI notification for feedback (writes to file only)

Development

cd opencode-plugin
bun install
bun run typecheck  # Check types
bun build src/index.ts --outdir dist --target bun