AGENTS.md — opencode-claude-mem

OpenCode plugin for Claude-Mem persistent memory system. Thin HTTP client that bridges OpenCode hooks to the Claude-Mem worker service (port 37777).

Project Overview

• Runtime: Bun
• Language: TypeScript (strict mode)
• Package manager: Bun (bun install, lockfile: bun.lock)
• Entry point: src/index.ts (plugin factory), src/worker-client.ts (HTTP client)
• Output: dist/ (compiled JS + declarations)
• CI: GitHub Actions (.github/workflows/ci.yml, .github/workflows/release.yml)

Build / Lint / Test Commands

# Install dependencies
bun install

# Build (type-check + emit)
bun run build          # runs: tsc

# Dev mode (watch)
bun run dev            # runs: tsc --watch

# Lint (code quality)
bun run lint           # runs: oxlint

# Format (code style)
bun run fmt            # runs: oxfmt --write src/
bun run fmt:check      # runs: oxfmt --check src/ (CI dry-run)

# CI install (frozen lockfile)
bun install --frozen-lockfile

Verification: tsc build succeeds, oxlint reports 0 errors, oxfmt --check passes.

If you add tests, use bun test (Bun's built-in test runner). Place test files alongside source as *.test.ts or in a __tests__/ directory.

TypeScript Configuration

• Target: ESNext
• Module: ESNext with bundler module resolution
• Strict: true (all strict checks enabled)
• Types: bun-types (Bun runtime globals)
• Declaration: true (emits .d.ts files)
• Output: dist/
• Include: src/**/*

Code Style Guidelines

Formatting

• Semicolons: none (enforced by oxfmt)
• Quotes: single quotes ('...')
• Indentation: 2 spaces
• Trailing commas: ES5 style (arrays/objects yes, function params no)
• Line length: 100 chars (enforced by oxfmt printWidth)
• Braces: same-line opening brace (K&R style)
• Curly braces: always required for if/else/for/while blocks (enforced by oxlint curly)
• Bracket spacing: { foo } not {foo} (enforced by oxfmt)

Imports

• Named imports only — no default exports in this codebase
• Relative imports without file extensions: import { WorkerClient } from './worker-client'
• External imports: import { type Plugin, tool } from '@opencode-ai/plugin'
• Use import type or inline type keyword for type-only imports

Naming Conventions

• Classes: PascalCase (WorkerClient)
• Methods/functions: camelCase (ensureSessionInit, extractTextFromParts)
• Variables/params: camelCase (projectName, contentSessionId)
• Constants: camelCase or UPPER_SNAKE for true constants (CONTEXT_CACHE_TTL)
• Types/Interfaces: PascalCase (Plugin)

Class Pattern

WorkerClient uses all-static methods — no instantiation. This is the established pattern for service clients in this codebase. Follow it for new service classes.

export class ServiceClient {
  private static readonly PORT = 37777
  private static readonly BASE_URL = `http://127.0.0.1:${ServiceClient.PORT}`

  static async methodName(): Promise<ReturnType> {
    // ...
  }
}

Error Handling

This plugin follows a "never throw, never log" pattern:

• All HTTP calls are wrapped in try/catch
• Catch blocks either return a fallback (null, false, empty string) or silently swallow
• Never use console.log, console.warn, or console.error — output corrupts the OpenCode TUI
• Use toast() helper for user-visible status messages (best-effort, never throws)
• Abort controllers with timeouts for health checks

// Correct pattern
try {
  const response = await fetch(url)
  if (!response.ok) {
    return null
  }
  return await response.json()
} catch {
  return null
}

// WRONG — never do this
console.error('Failed:', error)  // corrupts TUI
throw error                       // breaks OpenCode

Type Safety

• strict: true is enabled — respect it
• Avoid as any except when interfacing with untyped SDK APIs (e.g., client.tui)
• Use explicit return types on public/exported methods
• Use any for SDK callback parameters that lack proper types (e.g., hook event param)
• Prefer unknown over any when the type will be narrowed

Plugin Architecture

The plugin exports a single async factory function (ClaudeMemPlugin) that:

1. Receives context (project, directory, client)
2. Sets up internal state (session tracking, caches)
3. Returns an object of hook handlers

Hook handlers available:

• event — session lifecycle (session.created, session.idle)
• chat.message — session init with real user prompt
• experimental.chat.system.transform — inject memory into system prompt
• tool.execute.after — capture tool observations
• tool — custom tool definitions (mem-search)

Critical Implementation Details

• Field name: Worker API uses contentSessionId (NOT claudeSessionId) — wrong name causes silent failures
• Deferred toast: Never call client.tui.showToast() during plugin init — TUI isn't ready, crashes OpenCode
• Idempotent init: ensureSessionInit() tracks initialized sessions in a Set — safe to call repeatedly
• Context caching: getCachedContext() wraps WorkerClient.getContext() with a 30s TTL cache (CONTEXT_CACHE_TTL) to avoid redundant fetches between session.created (display) and experimental.chat.system.transform (LLM injection)
• Inline context display: On session.created, context is displayed in the chat flow via sendStatusMessage() using client.session.prompt({ noReply: true, parts: [{ ignored: true }] }) — visible to user, not sent to LLM. Falls back to toast if injection fails.
• Double notification suppression: contextDisplayedInline flag prevents checkWorkerAndToast() from showing a redundant "Memory active" toast when context is already displayed inline

Worker API Endpoints

All calls go to http://127.0.0.1:37777:

File Structure

src/
  index.ts          — Plugin entry: hooks, toast, session management
  worker-client.ts  — Static HTTP client for Claude-Mem worker API
dist/               — Build output (gitignored)

CI/CD

• CI (ci.yml): Runs on push/PR to main. Installs with frozen lockfile, builds, verifies dist output exists.
• Release (release.yml): Triggered by v*.*.* tags. Builds and creates GitHub Release with dist artifacts.

Common Pitfalls

1. Don't add console.* calls — they corrupt the OpenCode TUI
2. Don't call TUI methods during plugin initialization — defer to first hook invocation
3. Always use contentSessionId in worker API payloads, never claudeSessionId
4. The plugin is loaded as a single JS file via symlink — keep the dependency footprint minimal
5. Worker must be running (via Claude Code) before the plugin can function
6. Windows nul file: If you see a nul file in the project root, delete it (rm nul). Do not commit it. It is already in .gitignore.