Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
opencode Builtin Agent Implementation Plan
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Add opencode (opencode.ai) as a builtin agent with codex/gemini parity: menus + icon, --prompt launch, hook-driven status badges via a managed JS plugin, cold-restore resume, context-link, and canvas-control.
Architecture: nodeterm's agent system is a declarative registry (AGENT_CONFIG + capability membership lists) with per-agent seams: a normalizer for hook events, an installer that plants a managed hook artifact, and instruction-file targets for the context-link/canvas-control CLIs. opencode differs from codex/gemini in two ways: its hook artifact is a JS plugin file (not a JSON settings merge) and its transcript is read via opencode export <sessionID> (storage is SQLite in ≥1.18 — never parse disk).
Tech Stack: TypeScript, React, vitest (node env). opencode v1.18.2 is installed locally (opencode --help is ground truth).
Spec: docs/superpowers/specs/2026-07-15-opencode-agent-design.md
Global Constraints
- All code comments, UI strings, identifiers in English.
src/coremust never importelectronor../main/*(enforced bysrc/core/no-electron.test.ts).- claude/codex/gemini launch command strings must stay byte-identical — only the new
flag-promptbranch is added; gemini (declaredstdin-after-start) keeps today's argv behavior. - The managed opencode plugin must be env-gated (
NODETERM_NODE_ID/NODETERM_HOOK_TOKEN/NODETERM_HOOK_ENDPOINTall present, else return{}): opencode loads plugins on EVERY CLI command. - Payload field names from opencode events are NOT a contract — extract defensively; the event NAME is the contract.
- Gates:
npm run typecheck;npm test(known pre-existing flaky failures:src/core/workspace-watcher.test.tsfs-watch timing, occasionallylicensesetSystemTime — only-those failures are not yours). - This repo is edited concurrently by other sessions: work happens on an isolated worktree branch; verify unexpected test failures against the base commit before assuming your change caused them.
- Every commit message ends with:
Co-Authored-By: Claude Fable 5 <[email protected]>Claude-Session: https://claude.ai/code/session_019VnU4dDJZiCmAo7VCABceP
Task 1: Registry — id, config, capabilities, resume
Files:
- Modify:
src/shared/agents/config.ts:5(union),:19(BUILTIN_AGENT_IDS),:21-43(AGENT_CONFIG),:47-64(capability lists),:100-113(resumeCommand) - Test:
src/shared/agents/config.capabilities.test.ts,src/shared/agents/resume.test.ts(extend both, following each file's existing style)
Interfaces:
Produces:
'opencode'as aBuiltinAgentId;AGENT_CONFIG.opencodewithlaunchCmd: 'opencode',promptInjectionMode: 'flag-prompt',color: '#a78bfa',expectedProcess: 'opencode';hasHooks/canResume/canContextLink/canControlCanvas('opencode') === true;resumeCommand('opencode', sid) === \opencode --session ${sid}``. Every later task relies on these exact values.Step 1: Write the failing tests
Append to src/shared/agents/config.capabilities.test.ts (adapt imports to the file's existing list):
describe('opencode capabilities', () => {
it('is a builtin with the parity capability set', () => {
expect(BUILTIN_AGENT_IDS).toContain('opencode')
expect(AGENT_CONFIG.opencode).toEqual({
label: 'opencode',
color: '#a78bfa',
launchCmd: 'opencode',
promptInjectionMode: 'flag-prompt',
expectedProcess: 'opencode'
})
expect(hasHooks('opencode')).toBe(true)
expect(canResume('opencode')).toBe(true)
expect(canContextLink('opencode')).toBe(true)
expect(canControlCanvas('opencode')).toBe(true)
})
it('stays out of the claude-only capability lists', () => {
for (const can of [canSubagent, canRecur, canBranch, hasUsage, canChat, canTransferFrom, canRename, hasPermissionMode]) {
expect(can('opencode')).toBe(false)
}
})
})
Append to src/shared/agents/resume.test.ts:
it('resumes opencode via --session', () => {
expect(resumeCommand('opencode', 'ses_a1b2c3')).toBe('opencode --session ses_a1b2c3')
})
it('rejects an unsafe opencode session id', () => {
expect(resumeCommand('opencode', 'x; rm -rf /')).toBeNull()
})
- Step 2: Run tests to verify they fail
Run: npx vitest run src/shared/agents/config.capabilities.test.ts src/shared/agents/resume.test.ts
Expected: FAIL — 'opencode' not in BUILTIN_AGENT_IDS / TS error on AGENT_CONFIG.opencode (typecheck happens at vitest transform; if the type error blocks the run, that IS the expected RED).
- Step 3: Implement the registry entry
In src/shared/agents/config.ts:
export type BuiltinAgentId = 'claude' | 'codex' | 'gemini' | 'opencode'
export const BUILTIN_AGENT_IDS: readonly BuiltinAgentId[] = ['claude', 'codex', 'gemini', 'opencode']
Add to AGENT_CONFIG (after gemini):
opencode: {
label: 'opencode',
color: '#a78bfa',
launchCmd: 'opencode',
// A bare positional is a PROJECT PATH for opencode, so the initial prompt must go
// through --prompt (see createAgentNode's flag-prompt branch).
promptInjectionMode: 'flag-prompt',
expectedProcess: 'opencode'
}
Capability lists:
export const AGENT_HOOK_TARGETS = ['claude', 'codex', 'gemini', 'opencode'] as const
export const RESUMABLE_AGENTS = ['claude', 'codex', 'gemini', 'opencode'] as const
export const CONTEXT_LINK_CAPABLE = ['claude', 'codex', 'gemini', 'opencode'] as const
Update CANVAS_CONTROL_CAPABLE and its comment (opencode reads ~/.config/opencode/AGENTS.md):
// Agents allowed to drive the canvas via the `nodeterm` CLI (open/show/write/close).
// Discovery differs per agent: claude gets the manage-nodeterm-canvas skill; codex/gemini/
// opencode a marker block in ~/.codex/AGENTS.md / ~/.gemini/GEMINI.md /
// ~/.config/opencode/AGENTS.md (see canvas-control.ts).
export const CANVAS_CONTROL_CAPABLE = ['claude', 'codex', 'gemini', 'opencode'] as const
resumeCommand switch — add before default:
case 'opencode':
return `opencode --session ${sid}`
- Step 4: Run tests + typecheck
Run: npx vitest run src/shared/agents/ && npm run typecheck
Expected: PASS (all agent tests, including pre-existing ones).
- Step 5: Commit
git add src/shared/agents/config.ts src/shared/agents/config.capabilities.test.ts src/shared/agents/resume.test.ts
git commit -m "feat(agents): register opencode as a builtin (hooks, resume, context-link, canvas-control)"
Task 2: Honor flag-prompt at launch
Files:
- Modify:
src/renderer/state/workspace.ts:296-306(createAgentNode) - Test:
src/renderer/state/workspace.test.ts(extend)
Interfaces:
Consumes:
AGENT_CONFIG.opencode.promptInjectionMode === 'flag-prompt'(Task 1);agentConfig(id)andshellSingleQuote(both already imported/defined in workspace.ts).Produces:
createAgentNode('opencode', 0, undefined, undefined, 'do X')yieldsdata.initialCommand === "opencode --prompt 'do X'". claude/codex/gemini strings unchanged.Step 1: Write the failing tests
Append to src/renderer/state/workspace.test.ts (follow the file's existing createAgentNode test style):
describe('createAgentNode prompt injection', () => {
it('uses --prompt for flag-prompt agents (opencode)', () => {
const n = createAgentNode('opencode', 0, undefined, undefined, "rerank the results")
expect(n.data.initialCommand).toBe("opencode --prompt 'rerank the results'")
})
it('shell-quotes a flag-prompt safely', () => {
const n = createAgentNode('opencode', 0, undefined, undefined, "it's tricky")
expect(n.data.initialCommand).toBe("opencode --prompt 'it'\\''s tricky'")
})
it('keeps argv injection byte-identical for codex and gemini', () => {
expect(createAgentNode('codex', 0, undefined, undefined, 'do X').data.initialCommand).toBe("codex 'do X'")
expect(createAgentNode('gemini', 0, undefined, undefined, 'do X').data.initialCommand).toBe("gemini 'do X'")
})
})
- Step 2: Run tests to verify they fail
Run: npx vitest run src/renderer/state/workspace.test.ts
Expected: FAIL — opencode command is opencode 'rerank the results' (positional, the bug this task fixes).
- Step 3: Implement the flag-prompt branch
In createAgentNode (workspace.ts:296-306), replace the withPrompt computation:
const { label, color, launchCmd } = resolveAgent(agentId)
const baseCmd = agentId === 'claude' ? claudeLaunchCommand() : launchCmd
// A flag-prompt agent (opencode) takes the initial prompt via its flag — a bare positional
// would be misread (opencode treats it as a project path). Everything else keeps the
// historical argv append, INCLUDING stdin-after-start agents (gemini has always launched
// via argv here; changing that is a separate decision).
const promptArg = initialPrompt
? shellSingleQuote(initialPrompt.replace(/\s+/g, ' ').trim())
: null
const withPrompt = promptArg
? agentConfig(agentId)?.promptInjectionMode === 'flag-prompt'
? `${baseCmd} --prompt ${promptArg}`
: `${baseCmd} ${promptArg}`
: baseCmd
(agentConfig may already be imported in workspace.ts via resolveAgent's import — check the import list; add agentConfig to the @shared/agents/config import if missing.)
- Step 4: Run tests + typecheck
Run: npx vitest run src/renderer/state/ && npm run typecheck
Expected: PASS, including every pre-existing workspace test (the argv regression net).
- Step 5: Commit
git add src/renderer/state/workspace.ts src/renderer/state/workspace.test.ts
git commit -m "feat(agents): honor flag-prompt injection at launch (opencode --prompt)"
Task 3: normalizeOpencode — hook events → shared state model
Files:
- Modify:
src/shared/agents/normalize.ts(new payload interface + normalizer afternormalizeGeminiat:228-244; dispatch innormalizeForat:246-251) - Test:
src/shared/agents/normalize.test.ts(extend)
Interfaces:
Consumes:
RawHookEnvelope/NormalizedAgentEvent(defined in the same file).Produces:
normalizeOpencode(env: RawHookEnvelope): NormalizedAgentEvent | null;normalizeFor('opencode', env)routes to it. The plugin (Task 4) POSTs payloads shaped{ event: string, sessionID?: string, role?: string }.Step 1: Write the failing tests
Append to src/shared/agents/normalize.test.ts (follow the file's existing envelope-builder style):
describe('normalizeOpencode', () => {
const env = (payload: Record<string, unknown>) => ({ nodeId: 'n1', agentId: 'opencode' as const, payload })
it('maps session.created to a session start with the id', () => {
expect(normalizeFor('opencode', env({ event: 'session.created', sessionID: 'ses_1' }))).toEqual({
nodeId: 'n1', agentId: 'opencode', sessionId: 'ses_1', kind: 'session', sessionPhase: 'start'
})
})
it('maps a user message.updated to working + newTurn', () => {
expect(normalizeFor('opencode', env({ event: 'message.updated', role: 'user', sessionID: 'ses_1' }))).toMatchObject({
kind: 'state', state: 'working', newTurn: true
})
})
it('maps tool.execute.before to working (no newTurn)', () => {
const e = normalizeFor('opencode', env({ event: 'tool.execute.before' }))
expect(e).toMatchObject({ kind: 'state', state: 'working' })
expect(e?.newTurn).toBeUndefined()
})
it('maps permission.asked to blocked and permission.replied back to working', () => {
expect(normalizeFor('opencode', env({ event: 'permission.asked' }))).toMatchObject({ state: 'blocked' })
expect(normalizeFor('opencode', env({ event: 'permission.replied' }))).toMatchObject({ state: 'working' })
})
it('maps session.idle and session.error to done', () => {
expect(normalizeFor('opencode', env({ event: 'session.idle' }))).toMatchObject({ state: 'done' })
expect(normalizeFor('opencode', env({ event: 'session.error' }))).toMatchObject({ state: 'done' })
})
it('ignores unknown events', () => {
expect(normalizeFor('opencode', env({ event: 'tui.toast.show' }))).toBeNull()
})
})
- Step 2: Run tests to verify they fail
Run: npx vitest run src/shared/agents/normalize.test.ts
Expected: FAIL — normalizeFor returns null for opencode.
- Step 3: Implement the normalizer
Add after normalizeGemini in normalize.ts:
// opencode plugin payload (see core/agents/hooks/opencode.ts). The managed plugin forwards
// { event, sessionID?, role? } per hook; field names beyond `event` are read defensively —
// opencode's event payload shapes are not a contract, so the event NAME carries the mapping.
interface OpencodePayload {
event?: string
sessionID?: string
session_id?: string
role?: string
}
export function normalizeOpencode(env: RawHookEnvelope): NormalizedAgentEvent | null {
const p = env.payload as OpencodePayload
const base = { nodeId: env.nodeId, agentId: env.agentId, sessionId: p.sessionID ?? p.session_id }
if (p.event === 'session.created') return { ...base, kind: 'session', sessionPhase: 'start' }
// The plugin forwards message.updated only for user messages — opencode's turn start
// (mirrors Claude's UserPromptSubmit), so per-turn fan-out clears once per turn.
if (p.event === 'message.updated' && p.role === 'user') {
return { ...base, kind: 'state', state: 'working', newTurn: true }
}
if (p.event === 'tool.execute.before') return { ...base, kind: 'state', state: 'working' }
if (p.event === 'permission.asked') return { ...base, kind: 'state', state: 'blocked' }
if (p.event === 'permission.replied') return { ...base, kind: 'state', state: 'working' }
if (p.event === 'session.idle' || p.event === 'session.error') {
return { ...base, kind: 'state', state: 'done' }
}
return null
}
Dispatch in normalizeFor:
if (agentId === 'opencode') return normalizeOpencode(env)
- Step 4: Run tests + typecheck
Run: npx vitest run src/shared/agents/normalize.test.ts && npm run typecheck
Expected: PASS.
- Step 5: Commit
git add src/shared/agents/normalize.ts src/shared/agents/normalize.test.ts
git commit -m "feat(agents): normalize opencode plugin events to the shared state model"
Task 4: Managed opencode plugin installer
Files:
- Create:
src/core/agents/hooks/opencode.ts - Modify:
src/core/agents/hooks/index.ts:10-20(installer/remover registries) - Test:
src/core/agents/hooks/opencode.test.ts(new)
Interfaces:
Consumes: nothing from other tasks (the hook server already routes
/hook/opencode→normalizeFor('opencode', …)generically).Produces:
installOpencodeHooks(): void,removeOpencodeHooks(): void, and exported-for-testbuildOpencodePlugin(): string,pluginPath(): string,PLUGIN_MARKER.Step 1: Write the failing tests
Create src/core/agents/hooks/opencode.test.ts:
import fs from 'fs'
import os from 'os'
import path from 'path'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { PLUGIN_MARKER, buildOpencodePlugin, installOpencodeHooks, removeOpencodeHooks } from './opencode'
let tmp: string
beforeEach(() => {
tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'nt-oc-'))
vi.spyOn(os, 'homedir').mockReturnValue(tmp)
})
afterEach(() => {
vi.restoreAllMocks()
fs.rmSync(tmp, { recursive: true, force: true })
})
const planted = () => path.join(tmp, '.config', 'opencode', 'plugins', 'nodeterm-status.js')
describe('opencode plugin install', () => {
it('writes the marker-bearing plugin file (idempotent)', () => {
installOpencodeHooks()
installOpencodeHooks()
const body = fs.readFileSync(planted(), 'utf8')
expect(body.startsWith(PLUGIN_MARKER)).toBe(true)
expect(body).toContain('NODETERM_NODE_ID')
expect(body).toContain('/hook/opencode')
})
it('never overwrites a user file without the marker', () => {
fs.mkdirSync(path.dirname(planted()), { recursive: true })
fs.writeFileSync(planted(), '// my own plugin\n')
installOpencodeHooks()
expect(fs.readFileSync(planted(), 'utf8')).toBe('// my own plugin\n')
})
it('remove deletes only a marker-bearing file', () => {
installOpencodeHooks()
removeOpencodeHooks()
expect(fs.existsSync(planted())).toBe(false)
fs.mkdirSync(path.dirname(planted()), { recursive: true })
fs.writeFileSync(planted(), '// my own plugin\n')
removeOpencodeHooks()
expect(fs.existsSync(planted())).toBe(true)
})
it('generated plugin is env-gated and fail-open', () => {
const body = buildOpencodePlugin()
expect(body).toContain('return {}') // missing env → no-op
expect(body).toContain('catch') // POSTs never throw into opencode
})
})
- Step 2: Run tests to verify they fail
Run: npx vitest run src/core/agents/hooks/opencode.test.ts
Expected: FAIL — module not found.
- Step 3: Implement the installer
Create src/core/agents/hooks/opencode.ts:
// opencode hook service. Unlike claude/gemini (JSON settings merge) and codex (hooks.json +
// trust hash), opencode's hook seam is its PLUGIN system: a JS module in
// ~/.config/opencode/plugins/ whose exported hooks fire on session/tool/permission events.
// nodeterm owns one whole plugin file (marker-gated — a user's own file is never touched).
// opencode loads plugins on EVERY CLI command, so the plugin is env-gated: without the
// NODETERM_* env of a nodeterm-spawned session it returns {} and does nothing.
import fs from 'fs'
import os from 'os'
import path from 'path'
export const PLUGIN_MARKER = '// nodeterm managed plugin — do not edit (reinstalled at app launch)'
export function pluginPath(): string {
return path.join(os.homedir(), '.config', 'opencode', 'plugins', 'nodeterm-status.js')
}
/** The managed plugin body. Mirrors the managed POSIX script's wire contract exactly
* (see managed-script.ts + hook-server.ts):
* - gate on NODETERM_NODE_ID (absent outside nodeterm-spawned sessions → no-op `{}`);
* - per POST, re-read the NODETERM_HOOK_ENDPOINT FILE (KEY=VALUE lines) for the LIVE
* port/token — tmux sessions outlive the app, so env-baked coords go stale after a
* restart (the restart handoff); fall back to the env vars;
* - POST application/x-www-form-urlencoded `nodeId` + `version` + `payload` (JSON) with
* the x-nodeterm-hook-token header to http://127.0.0.1:<port>/hook/opencode.
* Payload fields are extracted defensively — the event NAME is the contract with
* normalizeOpencode; sessionID/role are best-effort. message.updated forwards ONLY user
* messages (turn start) so assistant token streaming never floods the hook server.
* (NODETERM_HOOK_SOCK unix-socket transport is not implemented here — desktop buildPtyEnv
* advertises the TCP port; if only a socket is available the plugin no-ops, fail-open.) */
export function buildOpencodePlugin(): string {
return `${PLUGIN_MARKER}
import fs from 'node:fs'
export const NodetermStatus = async () => {
const nodeId = process.env.NODETERM_NODE_ID
if (!nodeId) return {}
const live = () => {
const conf = {
port: process.env.NODETERM_HOOK_PORT,
token: process.env.NODETERM_HOOK_TOKEN,
version: process.env.NODETERM_HOOK_VERSION
}
try {
const file = process.env.NODETERM_HOOK_ENDPOINT
if (file) {
for (const line of fs.readFileSync(file, 'utf8').split('\\n')) {
const m = line.match(/^NODETERM_HOOK_(PORT|TOKEN|VERSION)=(.*)$/)
if (m) conf[m[1].toLowerCase()] = m[2]
}
}
} catch {}
return conf
}
const post = (event, extra) => {
try {
const { port, token, version } = live()
if (!port || !token) return
const payload = JSON.stringify({ event, ...extra })
fetch('http://127.0.0.1:' + port + '/hook/opencode', {
method: 'POST',
headers: {
'content-type': 'application/x-www-form-urlencoded',
'x-nodeterm-hook-token': token
},
body:
'nodeId=' + encodeURIComponent(nodeId) +
'&version=' + encodeURIComponent(version || '') +
'&payload=' + encodeURIComponent(payload)
}).catch(() => {})
} catch {}
}
const sid = (x) =>
(x && (x.sessionID || x.session_id || (x.session && x.session.id) || (x.info && x.info.sessionID))) || undefined
return {
'session.created': async (input) => post('session.created', { sessionID: sid(input) }),
'session.idle': async (input) => post('session.idle', { sessionID: sid(input) }),
'session.error': async (input) => post('session.error', { sessionID: sid(input) }),
'permission.asked': async (input) => post('permission.asked', { sessionID: sid(input) }),
'permission.replied': async (input) => post('permission.replied', { sessionID: sid(input) }),
'tool.execute.before': async (input) => post('tool.execute.before', { sessionID: sid(input) }),
'message.updated': async (input) => {
const role = input && ((input.info && input.info.role) || input.role)
if (role === 'user') post('message.updated', { sessionID: sid(input), role: 'user' })
}
}
}
`
}
export function installOpencodeHooks(): void {
const p = pluginPath()
try {
const existing = fs.readFileSync(p, 'utf8')
if (!existing.startsWith(PLUGIN_MARKER)) return // a user's own file — never touch it
} catch {
/* absent — plant it */
}
fs.mkdirSync(path.dirname(p), { recursive: true })
fs.writeFileSync(p, buildOpencodePlugin(), 'utf8')
}
export function removeOpencodeHooks(): void {
const p = pluginPath()
try {
if (fs.readFileSync(p, 'utf8').startsWith(PLUGIN_MARKER)) fs.rmSync(p, { force: true })
} catch {
/* absent — nothing to remove */
}
}
Register in src/core/agents/hooks/index.ts:
import { installOpencodeHooks, removeOpencodeHooks } from './opencode'
export const MANAGED_HOOK_INSTALLERS: readonly HookInstaller[] = [
['claude', installClaudeHooks],
['codex', installCodexHooks],
['gemini', installGeminiHooks],
['opencode', installOpencodeHooks]
]
export const MANAGED_HOOK_REMOVERS: readonly HookInstaller[] = [
['claude', removeClaudeHooks],
['codex', removeCodexHooks],
['gemini', removeGeminiHooks],
['opencode', removeOpencodeHooks]
]
- Step 4: Run tests + typecheck + no-electron gate
Run: npx vitest run src/core/agents/hooks/ src/core/no-electron.test.ts && npm run typecheck
Expected: PASS.
- Step 5: Commit
git add src/core/agents/hooks/opencode.ts src/core/agents/hooks/opencode.test.ts src/core/agents/hooks/index.ts
git commit -m "feat(hooks): managed opencode plugin (env-gated, marker-owned, fail-open)"
Task 5: Instruction-file targets (context-link + canvas-control)
Files:
- Modify:
src/main/context-link.ts:103-108(installAgentInstructionstargets) - Modify:
src/main/canvas-control.ts:148-153(installAgentInstructionstargets) and the--agent claude|codex|gemini|<custom-id>prose incanvas-control.ts(skill body, ~line 66) andsrc/main/canvas-control-core.ts(buildCanvasControlInstructionsverbs list)
Interfaces:
Consumes: nothing new — the merge helpers are marker-generic.
Produces: both CLIs' discovery blocks land in
~/.config/opencode/AGENTS.md(opencode reads global AGENTS.md).Step 1: Add the target path in both installers
In src/main/context-link.ts installAgentInstructions:
const targets = [
path.join(os.homedir(), '.codex', 'AGENTS.md'),
path.join(os.homedir(), '.gemini', 'GEMINI.md'),
path.join(os.homedir(), '.config', 'opencode', 'AGENTS.md')
]
In src/main/canvas-control.ts installAgentInstructions:
const targets = [
path.join(os.homedir(), '.codex', 'AGENTS.md'),
path.join(os.homedir(), '.gemini', 'GEMINI.md'),
path.join(os.homedir(), '.config', 'opencode', 'AGENTS.md')
]
Also update the comment above each function that names the codex/gemini files, adding opencode's.
- Step 2: Update the
open-agentprose examples
In src/main/canvas-control.ts (skill body) and src/main/canvas-control-core.ts (buildCanvasControlInstructions), replace both occurrences of
open-agent --agent claude|codex|gemini|<custom-id> with
open-agent --agent claude|codex|gemini|opencode|<custom-id> (functional behavior is unchanged — open-agent accepts any id — this is discoverability prose).
- Step 3: Gate
Run: npm run typecheck && npx vitest run src/main/canvas-control-core.test.ts src/core/context-link-core.test.ts
Expected: PASS (marker/merge tests are prose-agnostic).
- Step 4: Commit
git add src/main/context-link.ts src/main/canvas-control.ts src/main/canvas-control-core.ts
git commit -m "feat(agents): opencode AGENTS.md gets the context-link + canvas-control blocks"
Task 6: Context-link CLI — opencode transcript via opencode export
Files:
- Modify:
src/core/context-link-core.ts— inside theCLI_SCRIPTtemplate literal: addlinesFromOpencodeExportnext tolinesFromCodex/linesFromGeminiFile(line 196-240) and branchline 267-277)readTranscript( - Test:
src/core/context-link-core.test.tsor the CLI test filesrc/core/context-link.cli.test.ts(follow where existing per-agent parser tests live; add the opencode fixture test beside them)
Interfaces:
- Consumes: link-file node entries already carry
agentandsessionId(per-entry).execFileSyncis already imported inside the CLI script. - Produces:
readTranscript(node)returns formatted lines fornode.agent === 'opencode'by spawningopencode export <sessionId>.
IMPORTANT — template-literal escaping: CLI_SCRIPT is a JS template literal; the existing parsers write \n as \\n and avoid backticks entirely (ES5-style var/function). Match that style exactly or the generated script breaks.
- Step 1: Write the failing test
The export JSON shape is defensive, not a version contract. Add to the test file that exercises the generated CLI's parsers (find where linesFromCodex behavior is tested — if parsers are only tested through the generated script, follow that harness):
describe('opencode export transcript', () => {
it('formats messages from an export payload', () => {
// Fixture mirrors the defensive shape linesFromOpencodeExport accepts:
// top-level messages array, each with role/parts-or-content.
const fixture = JSON.stringify({
messages: [
{ role: 'user', parts: [{ type: 'text', text: 'add rerank' }] },
{ role: 'assistant', parts: [{ type: 'text', text: 'done, added rerank.ts' }, { type: 'tool', tool: 'bash', state: { input: { command: 'npm test' } } }] }
]
})
const lines = runCliParser('opencode', fixture) // use the file's existing harness for invoking the generated parser
expect(lines.join('\n')).toContain('user: add rerank')
expect(lines.join('\n')).toContain('assistant: done, added rerank.ts')
})
})
If no such harness exists (parsers untested today), test instead at the string level: assert CLI_SCRIPT contains linesFromOpencodeExport and the opencode branch in readTranscript, plus execFileSync('opencode', ['export', — and note in the report that parser logic is exercised via the live CLI only.
- Step 2: Run to verify it fails
Run: npx vitest run src/core/context-link-core.test.ts src/core/context-link.cli.test.ts
Expected: FAIL on the new case.
- Step 3: Implement inside
CLI_SCRIPT
Add next to the other parsers (ES5 style, \\n escaping — this code lives INSIDE the template literal):
// opencode >=1.18 stores sessions in SQLite — never parse its disk. The CLI exports a
// session as JSON: `opencode export <sessionID>`. Shape read defensively: a messages array
// whose items carry role + parts[] (text / tool) or a plain content string.
function linesFromOpencodeExport(node) {
if (!node.sessionId) { out('"' + node.title + '" has no session id yet.'); return [] }
var raw
try {
raw = execFileSync('opencode', ['export', String(node.sessionId)], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] })
} catch (e) { out('Could not export "' + node.title + '" session (is opencode installed?).'); return [] }
var o
try { o = JSON.parse(raw) } catch (e) { out('Unreadable opencode export for "' + node.title + '".'); return [] }
var msgs = Array.isArray(o) ? o : (o && (o.messages || (o.data && o.data.messages))) || []
var res = []
msgs.forEach(function (m) {
if (!m) return
var role = (m.role || (m.info && m.info.role)) === 'user' ? 'user' : 'assistant'
var parts = m.parts || (Array.isArray(m.content) ? m.content : null)
if (typeof m.content === 'string' && m.content) { res.push(role + ': ' + m.content); return }
if (!Array.isArray(parts)) return
parts.forEach(function (c) {
if (!c) return
if (typeof c.text === 'string' && c.text && (c.type === 'text' || !c.type)) res.push(role + ': ' + c.text)
else if (c.type === 'tool' || c.type === 'tool_use' || c.tool) {
var name = c.tool || c.name || 'tool'
var input = c.state && c.state.input ? c.state.input : c.input
var a = input && (input.command || input.filePath || input.file_path || input.pattern || input.description)
res.push(' $ ' + name + (typeof a === 'string' ? ' ' + a.slice(0, 200) : ''))
}
})
})
if (!res.length) out('"' + node.title + '" export contained no readable messages.')
return res
}
Branch readTranscript FIRST (before path resolution — opencode has no transcript file):
function readTranscript(node) {
if (node.agent === 'opencode') return linesFromOpencodeExport(node)
var p = resolveTranscript(node)
...unchanged...
- Step 4: Run tests + typecheck
Run: npx vitest run src/core/ && npm run typecheck
Expected: PASS (workspace-watcher flake excepted).
- Step 5: Commit
git add src/core/context-link-core.ts src/core/context-link-core.test.ts src/core/context-link.cli.test.ts
git commit -m "feat(context-link): read opencode transcripts via 'opencode export' (SQLite-safe)"
(Stage whichever of the two test files you actually touched.)
Task 7: Icon
Files:
- Create:
src/renderer/assets/opencode.svg - Modify:
src/renderer/lib/agentIcons.tsx:1-12(import +AGENT_LOGOentry)
Interfaces:
Consumes: the existing
AGENT_LOGOmap + Vite SVG asset imports (same ascodex-color.svg).Produces:
AgentIcon({ agentId: 'opencode' })renders the mark instead of the terminal fallback.Step 1: Add the asset
Create src/renderer/assets/opencode.svg — an original terminal-bracket mark in the agent color (NOT a copied trademark file):
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="#a78bfa" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round">
<path d="M8 4H5a1 1 0 0 0-1 1v14a1 1 0 0 0 1 1h3" />
<path d="M16 4h3a1 1 0 0 1 1 1v14a1 1 0 0 1-1 1h-3" />
<circle cx="12" cy="12" r="2.2" fill="#a78bfa" stroke="none" />
</svg>
- Step 2: Register it
In src/renderer/lib/agentIcons.tsx:
import opencodeIcon from '../assets/opencode.svg'
const AGENT_LOGO: Partial<Record<string, string>> = {
claude: claudeIcon,
codex: codexIcon,
gemini: geminiIcon,
opencode: opencodeIcon
}
- Step 3: Gate + commit
Run: npm run typecheck
Expected: PASS.
git add src/renderer/assets/opencode.svg src/renderer/lib/agentIcons.tsx
git commit -m "feat(agents): opencode menu icon"
Final verification (after all tasks)
-
npm run typecheck && npm test— green (known flakes excepted). -
opencodeappears in the dock/pane/palette agent menus (derived fromBUILTIN_AGENT_IDS— no extra wiring should have been needed). - Live E2E (needs a provider key — post-merge manual, noted for the user): spawn an opencode node with a prompt →
--promptlands; run a turn → RUNNING/done badge flips;opencode exporttranscript readable through a context link.