opencode-obsidian AGENTS.md

AGENTS.md - Obsidian OpenCode Plugin

Guidelines for AI coding agents working on the obsidian-opencode plugin.

Project Overview

Obsidian plugin that embeds the OpenCode AI assistant via an iframe. Spawns a local server process and displays its web UI in the Obsidian sidebar.

Tech Stack: TypeScript, Obsidian Plugin API, esbuild, Node.js child processes

Build Commands

bun install          # Install dependencies
bun run build        # Production (type-check + bundle)

Output: main.js (CommonJS bundle)

Project Structure

src/
├── main.ts           # Plugin entry, extends Plugin
├── types.ts          # Types and constants
├── OpenCodeView.ts   # Sidebar view (ItemView) with iframe
├── ProcessManager.ts # Server process lifecycle
└── SettingsTab.ts    # Settings UI (PluginSettingTab)

Coding guidelines

Naming Conventions

Type	Convention	Example
Classes	PascalCase	OpenCodePlugin, ProcessManager
Interfaces/Types	PascalCase	OpenCodeSettings, ProcessState
Constants	UPPER_CASE or camelCase	DEFAULT_SETTINGS, OPENCODE_VIEW_TYPE
Variables/functions	camelCase	getVaultPath, startServer
Private members	camelCase (no prefix)	private processManager
Files	PascalCase (classes), lowercase (entry)	ProcessManager.ts, main.ts

TypeScript Patterns

• strictNullChecks enabled - handle null/undefined
• Union types for state: "stopped" | "starting" | "running" | "error"
• async/await over Promises
• Explicit return types on public methods

getProcessState(): ProcessState {
  return this.processManager?.getState() ?? "stopped";
}

Obsidian API Patterns

• Extend Plugin with onload()/onunload() lifecycle
• Extend ItemView for views: getViewType(), onOpen(), onClose()
• Extend PluginSettingTab for settings: display()
• DOM helpers: createEl(), createDiv(), setIcon()
• Register in onload(), clean up in onunload()