Last active
February 14, 2026 03:27
-
-
Save wblazer/25eea3574fe4fd9502e875e9e4cf435f to your computer and use it in GitHub Desktop.
OpenCode plugin for autoloading DOCS.md files with the read tool
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| import type { Plugin } from '@opencode-ai/plugin' | |
| import { | |
| existsSync, | |
| readFileSync, | |
| writeFileSync, | |
| mkdirSync, | |
| unlinkSync, | |
| readdirSync, | |
| statSync, | |
| } from 'fs' | |
| import { join, dirname, resolve, relative, basename } from 'path' | |
| import { homedir } from 'os' | |
| const DOC_FILENAME = 'DOCS.md' | |
| const CACHE_DIR = join(homedir(), '.cache', 'opencode', 'docs-autoload') | |
| const CACHE_TTL_DAYS = 14 | |
| function getSessionCacheFile(sessionID: string): string { | |
| mkdirSync(CACHE_DIR, { recursive: true }) | |
| return join(CACHE_DIR, `${sessionID}.json`) | |
| } | |
| function loadSessionState(sessionID: string): Set<string> { | |
| const cacheFile = getSessionCacheFile(sessionID) | |
| if (!existsSync(cacheFile)) return new Set() | |
| try { | |
| const data = JSON.parse(readFileSync(cacheFile, 'utf-8')) | |
| return new Set(data.loadedNodes || []) | |
| } catch { | |
| return new Set() | |
| } | |
| } | |
| function saveSessionState(sessionID: string, loadedNodes: Set<string>) { | |
| const cacheFile = getSessionCacheFile(sessionID) | |
| writeFileSync( | |
| cacheFile, | |
| JSON.stringify({ | |
| loadedNodes: Array.from(loadedNodes), | |
| lastUpdated: new Date().toISOString(), | |
| }) | |
| ) | |
| } | |
| function cleanupOldCaches() { | |
| if (!existsSync(CACHE_DIR)) return | |
| const now = Date.now() | |
| const maxAge = CACHE_TTL_DAYS * 24 * 60 * 60 * 1000 | |
| try { | |
| for (const file of readdirSync(CACHE_DIR)) { | |
| if (!file.endsWith('.json')) continue | |
| const filePath = join(CACHE_DIR, file) | |
| if (now - statSync(filePath).mtimeMs > maxAge) { | |
| unlinkSync(filePath) | |
| } | |
| } | |
| } catch { | |
| // Ignore cleanup errors | |
| } | |
| } | |
| /** | |
| * Walk from `startDir` up to `root` (inclusive), collecting any DOCS.md files found. | |
| * Returns them in ancestor-first order (outermost directory first). | |
| */ | |
| function discoverAncestorDocs( | |
| startDir: string, | |
| root: string | |
| ): Array<{ absolutePath: string; relativePath: string }> { | |
| const found: Array<{ absolutePath: string; relativePath: string }> = [] | |
| let current = resolve(startDir) | |
| const resolvedRoot = resolve(root) | |
| while (current.startsWith(resolvedRoot)) { | |
| const docPath = join(current, DOC_FILENAME) | |
| if (existsSync(docPath)) { | |
| found.push({ | |
| absolutePath: docPath, | |
| relativePath: relative(resolvedRoot, docPath), | |
| }) | |
| } | |
| if (current === resolvedRoot) break | |
| current = dirname(current) | |
| } | |
| // Reverse so parent nodes come before child nodes | |
| found.reverse() | |
| return found | |
| } | |
| export const DocsAutoloadPlugin: Plugin = async ({ worktree }) => { | |
| cleanupOldCaches() | |
| return { | |
| 'tool.execute.after': async (input, output) => { | |
| if (input.tool !== 'read') return | |
| const filePath = (input as any).args?.filePath | |
| const sessionID = input.sessionID | |
| if (!filePath || !sessionID) return | |
| const resolvedPath = resolve(filePath) | |
| // Don't process files outside the worktree | |
| if (!resolvedPath.startsWith(resolve(worktree))) return | |
| const loadedNodes = loadSessionState(sessionID) | |
| const isExplicitDocRead = basename(resolvedPath) === DOC_FILENAME | |
| // For explicit DOCS.md reads, record the file itself as loaded. | |
| // Then still discover ancestors — the read file's own directory is the | |
| // starting point either way, but we exclude the file being read from | |
| // injection since the agent is already looking at its contents. | |
| if (isExplicitDocRead) { | |
| loadedNodes.add(resolvedPath) | |
| } | |
| // Discover ancestor DOCS.md files from the file's directory upward. | |
| // For explicit reads, start from the parent of the DOCS.md's directory | |
| // (the agent already has the content of the file they're reading). | |
| const startDir = isExplicitDocRead | |
| ? dirname(dirname(resolvedPath)) | |
| : dirname(resolvedPath) | |
| // Guard: if startDir fell outside worktree (e.g. DOCS.md at worktree root) | |
| const resolvedWorktree = resolve(worktree) | |
| const ancestors = startDir.startsWith(resolvedWorktree) | |
| ? discoverAncestorDocs(startDir, worktree) | |
| : [] | |
| const newNodes = ancestors.filter( | |
| (node) => !loadedNodes.has(node.absolutePath) | |
| ) | |
| if (newNodes.length > 0) { | |
| const parts = newNodes.map((node) => { | |
| const content = readFileSync(node.absolutePath, 'utf-8') | |
| return `<autoloaded-docs>\n<path>${node.relativePath}</path>\n<content>\n${content}</content>\n</autoloaded-docs>` | |
| }) | |
| output.output += `\n\n${parts.join('\n\n')}` | |
| for (const node of newNodes) { | |
| loadedNodes.add(node.absolutePath) | |
| } | |
| } | |
| saveSessionState(sessionID, loadedNodes) | |
| }, | |
| event: async ({ event }) => { | |
| if (event.type !== 'session.deleted') return | |
| const sessionID = event.properties?.info?.id | |
| if (!sessionID) return | |
| try { | |
| const cacheFile = getSessionCacheFile(sessionID as string) | |
| if (existsSync(cacheFile)) unlinkSync(cacheFile) | |
| } catch { | |
| // Ignore cleanup errors | |
| } | |
| }, | |
| } | |
| } |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment