opencode-reflect

OpenCode plugin that captures corrections, preferences, and learnings from sessions and queues them for consolidation into AGENTS.md.

How It Works

The plugin runs as hooks inside OpenCode:

1. Capture hook (chat.message) — Regex-based pattern detection on every user message. Matches corrections ("actually, use X"), preferences ("always do Y"), and guardrails ("never do Z"). Queued to ~/.local/share/opencode/reflect-queue.json.
2. Session start hook — Shows a toast if there are pending learnings from previous sessions.
3. Commit reminder hook (tool.execute.after) — Appends a reminder about pending learnings after git commit operations.
4. Compaction warn hook — Injects a context note when sessions are being compacted.

Commands

/reflect

Reads the queue + optionally scans session history, deduplicates, and writes approved learnings into AGENTS.md.

/view-queue

Read-only view of pending learnings.

/skip-reflect

Clears the queue without processing.

Tools

The plugin registers two tools:

reflect_queue(action)

Manage the learning queue.

Parameter	Type	Description
action	"read" | "count" | "clear"	read — return all queued entries. count — return queue size. clear — discard all entries.

reflect_scan(options?)

Scan session history for patterns the capture hook may have missed.

Parameter	Type	Default	Description
historyDays	number	—	Scan sessions from the last N days. Mutually exclusive with sessionId.
sessionId	string	—	Scan a single specific session by ID. Mutually exclusive with historyDays.
limit	number	5	Maximum number of sessions to scan (capped at 20).
includeToolRejections	boolean	false	Also match tool rejection patterns (e.g. "don't use X tool").

Installation

bun add opencode-reflect

Development

Tests run inside Docker to prevent polluting the host queue file. Never run bun test directly.

bun install           # install dependencies
just test             # run all tests (builds Docker image first)
just test-unit        # unit tests only
just test-integration # integration tests only
just coverage         # run tests with coverage report
bun run build         # build the plugin
bun run typecheck     # type-check src/

Environment Variables

Variable	Description
OPENCODE_REFLECT_DEBUG=1	Enable debug logging (verbose output to stderr).
OPENCODE_REFLECT_QUEUE_PATH	Override the default queue file path (~/.local/share/opencode/reflect-queue.json). Useful for testing or isolating environments.

License

MIT

Inspired by claude-reflect.