oh-my-opencode/src/shared/AGENTS.md

SHARED UTILITIES KNOWLEDGE BASE

OVERVIEW

Core cross-cutting utilities for path resolution, token-safe text processing, and Claude Code compatibility.

STRUCTURE

shared/
├── logger.ts              # Persistent file-based logging (tmpdir/oh-my-opencode.log)
├── permission-compat.ts   # Agent tool restrictions (ask/allow/deny)
├── dynamic-truncator.ts   # Token-aware truncation with context headroom
├── frontmatter.ts         # YAML frontmatter parsing with JSON_SCHEMA safety
├── jsonc-parser.ts        # JSON with Comments support for config files
├── data-path.ts           # XDG-compliant storage paths (~/.local/share)
├── opencode-config-dir.ts # Resolve ~/.config/opencode for CLI/Desktop
├── claude-config-dir.ts   # Resolve ~/.claude for compatibility
├── migration.ts           # Legacy name mapping (omo -> Sisyphus)
└── opencode-version.ts    # Version comparison logic (e.g., >= 1.0.150)

WHEN TO USE

Task	Utility
Debugging/Auditing	log(message, data) in logger.ts
Limit agent context	dynamicTruncate(ctx, sessionId, output)
Parse rule meta	parseFrontmatter(content)
Load user configs	parseJsonc(text) or readJsoncFile(path)
Restrict tools	createAgentToolAllowlist(tools)
Resolve app paths	getOpenCodeConfigDir() or getClaudeConfigDir()
Update legacy config	migrateConfigFile(path, rawConfig)

CRITICAL PATTERNS

// Truncate large output based on 50% remaining context window
const { result } = await dynamicTruncate(ctx, sessionID, largeBuffer);

// Safe config loading with comment/trailing comma support
const settings = readJsoncFile<Settings>(configPath);

// Version-gated logic for OpenCode 1.1.0+
if (isOpenCodeVersionAtLeast("1.1.0")) { /* ... */ }

// Permission normalization for agent tools
const permissions = migrateToolsToPermission(legacyTools);

ANTI-PATTERNS

• Raw JSON.parse for configs (use jsonc-parser.ts)
• Hardcoded ~/.claude (use claude-config-dir.ts)
• console.log for background agents (use logger.ts)
• Unbounded tool output (always use dynamic-truncator.ts)
• Manual version parsing (use opencode-version.ts)