Skip to main content
plugin CX Codex

dejavu-gates — Claude Code plugin: what it does, how to install

dejavu-gates catches repeating tool failures across sessions and turns them into automatic reminders followed by hard execution blocks.

MIT ★ 1,596 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install dejavu-gates@awesome-codex-plugins
Open on GitHub

What dejavu-gates does

The tool intercepts failing tool calls such as bash, read, write, or grep. Each call signature is stripped of variable paths and hashes to build a normalized pattern key. Once a specific failure happens three times across two different sessions, dejavu promotes it into an active gate. The next run triggers a reminder with corrective guidance, while an immediate repeat in the same session triggers a hard block.

Pattern detection uses purely deterministic rules rather than model inferences in the critical path. Gates live directly on disk: repository-specific issues are kept in <repo>/.opencode/dejavu/, while patterns detected across multiple folders migrate to ~/.config/opencode/dejavu/. If a failure does not reappear within 60 days, its gate expires.

Running test suites and CLI actions requires an environment with Bun or Node.js available.

What it helps with

  • prevent coding agents from repeating known tool execution failures
  • persist learned failure guards across distinct coding sessions
  • stop broken bash commands before they run in the workspace
  • share guardrails across platforms like Codex and Claude Code

Example prompts for the agent

  • Run dejavu report to inspect recurring failure patterns
  • Execute the test suite and review any triggered dejavu gates
  • Pass dejavu:proceed to bypass an active block when necessary

How to install dejavu-gates

Plugin marketplace

/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install dejavu-gates@awesome-codex-plugins

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about dejavu-gates

How to install dejavu-gates in Claude Code?

Run both commands in sequence: first /plugin marketplace add hashgraph-online/awesome-codex-plugins, then /plugin install dejavu-gates@awesome-codex-plugins.

What does dejavu-gates do?

It hooks into agent tool calls, tracks persistent failures across sessions, and halts execution when the agent tries repeating an identical mistake.

Where does dejavu-gates store its recorded gates?

Project-specific rules are stored under <repo>/.opencode/dejavu/, while patterns shared across projects reside in ~/.config/opencode/dejavu/.

Source text

dejavu-gates · MIT
> [!IMPORTANT]
> **[`opencode-dejavu`](https://github.com/WhiteBite/opencode-dejavu) has been RENAMED to [`dejavu-gates`](https://github.com/WhiteBite/dejavu-gates) — you are on the new home.**
> The old URL [github.com/WhiteBite/opencode-dejavu](https://github.com/WhiteBite/opencode-dejavu) redirects here permanently.
> - **OpenCode config:** `{ "plugin": ["opencode-dejavu"] }` → `{ "plugin": ["dejavu-gates"] }`
> - **git remote:** `git remote set-url origin https://github.com/WhiteBite/dejavu-gates.git`
> - **npm:** the old package [`opencode-dejavu`](https://www.npmjs.com/package/opencode-dejavu) is deprecated and frozen at 2.27.0; all releases from 2.39.0 are [`dejavu-gates`](https://www.npmjs.com/package/dejavu-gates)

<p align="center">
  <img src="logo/icon.svg" width="96" height="96" alt="dejavu logo — a lowercase d with two amber echo strokes">
</p>

<h1 align="center">dejavu — error gates for AI coding agents</h1>

<p align="center"><b>English</b> | <a href="README.ru.md">Русский</a></p>

<p align="center">
  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License">
  <img src="https://img.shields.io/badge/harnesses-10-green.svg" alt="OpenCode, Claude Code, Codex, Gemini CLI, Cursor, Copilot CLI, Crush, Devin CLI, Kiro, Cline">
  <img src="https://img.shields.io/badge/TypeScript-Bun-black.svg" alt="TypeScript + Bun">
  <img src="https://github.com/WhiteBite/dejavu-gates/actions/workflows/ci.yml/badge.svg" alt="CI">
</p>

Cross-session **memory prosthesis with teeth** for AI coding agents. Agents repeat the same mistakes because they forget between sessions — and markdown rules don't fix that. dejavu mechanically detects recurring tool-call failures (bash, read, edit, write, glob, grep) and promotes them into enforced gates: a reminder on the next attempt, a hard block on same-session repeat offense. One engine, many hosts: OpenCode (plugin), Claude Code, Codex CLI, Gemini CLI, Cursor, Copilot CLI, Crush, Devin CLI, Kiro (hook-handler CLI), Cline (in-package plugin). TypeScript + Bun, ships as source, no build step.

## Quickstart

```bash
npm install dejavu-gates
dejavu report
```

Tests: `npm run test`

## Supported harnesses

| Harness | Install | Block (pre) | Remind NOTE (post) | Notes |
|---|---|---|---|---|
| **OpenCode** | npm plugin / source | ✅ | ✅ | full integration: all channels, repeat guard, compaction context |
| **Claude Code** | `install-hooks.ts` | ✅ | ✅ | `additionalContext` annotations; `SessionStart` hook injects a gate digest (top enforced gates) at session start; hooks carry no exit codes → text detection |
| **Codex CLI** | `install-hooks.ts` | ✅ | ✅ | hooks are stable and on by default; Pre/PostToolUse fire for every tool (matcher covers `Bash` + `apply_patch`); a first-run trust prompt may still apply to project hooks |
| **Gemini CLI** | `install-hooks.ts` | ✅ | ✅ | BeforeTool/AfterTool |
| **Cursor** | `install-hooks.ts` | ✅ | ✅ | shell events + CC-compatible events |
| **Copilot CLI** | `install-hooks.ts` | ✅ | ✅ | camelCase + PascalCase payload families |
| **Crush** | `install-hooks.ts` | ✅ | ❌ degraded | upstream has PreToolUse only — enforcement + shared store still protect; no post annotations |
| **Devin CLI** | `install-hooks.ts` | ✅ | ✅ | `.devin/hooks.v1.json` root-event merge; Claude-format hooks also auto-import from `.claude/settings.json` |
| **Kiro** | `install-hooks.ts` | ✅ | ✅ | `.kiro/hooks/dejavu-gates.json`; the NOTE rides raw hook stdout (Kiro's context channel); project scope only |
| **Cline** | `cline plugin install --npm dejavu-gates` | ✅ | ✅ | in-package plugin host (`src/cline-plugin.ts`); SDK/CLI/Kanban only — the VS Code and JetBrains extensions have no plugin system; no exit codes → text detection |
| Zed, Aider | — | ❌ | ❌ | no hook API to intercept tool calls — not portable |
| Windsurf, Amp | — | (planned) | ❌ | block-only / fire-and-forget surfaces; deferred until context injection exists |

**Unified store — gates travel across harnesses.** Every host reads/writes the same store (`<repo>/.opencode/dejavu/` + `~/.config/opencode/dejavu/`, `DEJAVU_HOME` overrides). Call signatures are harness-neutral (tool names and arg fields are normalized before signing), so a gate learned in Claude Code fires in OpenCode, Cursor, or anywhere else — and vice versa.

## How it works

```
tool call fails  →  signature normalized (paths/numbers/hashes stripped)
                 →  pattern-key counted, sessions tracked
                 →  3 failures across 2 distinct sessions  →  gate promoted
 next attempt     →  [dejavu] REMINDER (call aborted, agent sees the correction)
 retry fails again →  same-session repeat offense → hard BLOCK on further attempts
 diagnostic cmd   →  gate stays remind-only: the call RUNS and the reminder rides
                     on the failing output as a [dejavu] NOTE (once per session)
```

Design decisions (post-mortem of existing approaches):

- **Remind first, block on repeat.** Pure blocking starts an arms race — the agent routes around gates (`npm` blocked → uses `pnpm`). A reminder with the correction teaches; the block is reserved for ignored reminders.
- **Gate messages are teachers.** Every message carries `CORRECTION:` (what to do instead) and `EVIDENCE:` (N failures across M sessions), not just a prohibition.
- **Mechanical pattern-keys only.** No LLM-based error classification in the hot path — the unreliable component doesn't do reliability work.
- **Two scopes.** Repo-specific gotchas live in `<repo>/.opencode/dejavu/` (committable); patterns seen in 2+ project dirs are agent-level habits and move to `~/.config/opencode/dejavu/`. No single store can see all projects, so a global pattern index (`index.json`) counts distinct project dirs per key and drives the escalation.
- **Gates rot — so they expire.** 60 days without recurrence and a gate is dropped. A gate blocked 10+ times without the error going away gets `review: true` for manual inspection.
- **The metric is recurrence-after-gate.** Tracked per gate as `recurredAfterGate` — if gates don't reduce recurrence, the whole approach is wrong and you'll see it in the data.
- **Enforcement has negative feedback.** The metric acts: a gate that keeps failing after promotion (3+ recurrences across 2+ sessions that reoffended after a reminder) or keeps getting explicitly bypassed (blocking: 3+ `dejavu:proceed` overrides across 2+ distinct sessions; reminding: 5 distinct bypassing sessions, no raw-count bar — bypassing a gate that never interrupts is weaker friction; a single stubborn/injected session cannot disarm a gate) is friction, not teaching — it demotes itself to `watching` and never re-promotes mechanically (`feedbackDemoted`). A human can re-enforce by setting `status` back and clearing `feedbackDemoted` in `gates.json`; the gate then gets a fresh grace window.
- **No identity, no teeth.** A signature whose substance was entirely parameterized away (`cmd <path> <str>`, `node <str>`) matches a whole command family and can never enforce — it may only watch. Over-generic shapes degrade to evidence instead of punishing unrelated calls.
- **Fail-open, always.** The hook CLI never wedges a host: malformed payloads, a broken store, or an internal dejavu bug produce `{}` + exit 0. stdout carries only the decision JSON; everything else goes to stderr.

## Install

Prerequisite for every path: [Bun](https://bun.sh) on PATH (hook handlers run raw TypeScript; no build step).

### One command, any harness (recommended)

```bash
npx -y dejavu-gates install            # auto-detects installed harnesses, installs project-scope
npx -y dejavu-gates install --user     # user-scope (~/.claude, ~/.codex, ...)
npx -y dejavu-gates install --harness claude,cursor --yes
npx -y dejavu-gates uninstall          # removes only dejavu-managed entries, keeps your other hooks
npx -y dejavu-gates hooks --check      # drift report: ok / stale (moved clone) / missing / broken
```

The installer merges idempotently into each harness's config (foreign hooks and fields survive), backs the file up to `<config>.dejavu-bak` before mutating, refuses to touch unparseable configs, and writes hook commands that call the installed package's CLI directly (never `npx` in the hot path — hooks fire on every tool call). Or install the package once (`npm i -g dejavu-gates` or `npm i -D dejavu-gates`) and use the `dejavu` / `dejavu-gates` command instead of `npx -y`.

### Native plugin channels (no npx, auto-updating)

| Harness | Command |
|---|---|
| Claude Code | `claude plugin marketplace add WhiteBite/dejavu-gates` then `claude plugin install dejavu-gates@dejavu-marketplace` |
| Codex CLI | `codex plugin add WhiteBite/dejavu-gates` (hooks are enabled by default; approve the first-run trust prompt if it appears) |
| Copilot CLI | `copilot plugin install WhiteBite/dejavu-gates` |
| Cursor | IDE: `/add-plugin` → browse marketplace → dejavu-gates (or copy the repo to `~/.cursor/plugins/local/dejavu-gates`) |
| Gemini CLI | `gemini extensions install https://github.com/WhiteBite/dejavu-gates` |
| Crush | no plugin system — use the installer above or edit `crush.json` by hand |
| Devin CLI | no plugin marketplace — the installer writes `.devin/hooks.v1.json`; Devin also auto-imports Claude-format hooks from `.claude/settings.json` |
| Kiro | no plugin marketplace — the installer writes `.kiro/hooks/dejavu-gates.json` (project scope; Kiro documents no user-level hooks path) |
| Cline | `cline plugin install --npm dejavu-gates` (or drop `src/cline-plugin.ts` into `.cline/plugins/`); SDK/CLI/Kanban hosts only |

The companion reaction protocol (`skills/dejavu/`) ships inside the plugin bundle and is auto-discovered by the Claude Code, Cursor, and Gemini CLI plugin formats.

### GitHub Packages (authenticated mirror)

Every release is also published to GitHub Packages as `@whitebite/dejavu-gates`. GitHub Packages requires a token even for public packages, so npmjs.com above stays the recommended channel:

```ini
# .npmrc
@whitebite:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=<PAT with read:packages>
```

```bash
npm i -D @whitebite/dejavu-gates
```

### OpenCode

**npm (recommended)** — OpenCode installs it automatically at startup. OpenCode V1 uses the `"plugin"` key; V2 renamed it to `"plugins"`:

```jsonc
// ~/.config/opencode/opencode.json (global) or opencode.json (project)
// OpenCode V1 (@opencode-ai/plugin)
{ "plugin": ["dejavu-gates"] }
```

```jsonc
// OpenCode V2 (@opencode/cli) — or run `opencode plugin add dejavu-gates`
{ "plugins": ["dejavu-gates"] }
```

**From source:**

```bash
git clone https://github.com/WhiteBite/dejavu-gates ~/.config/opencode/vendor/dejavu
cd ~/.config/opencode/vendor/dejavu && bun install
```

```ts
// ~/.config/opencode/plugins/dejavu.ts
export { Dejavu } from "../vendor/dejavu/index.ts"
```

Companion skill (agent behavior protocol): copy `skills/dejavu/` to `~/.config/opencode/skills/dejavu/`.
Status command: copy `commands/dejavu.md` to `~/.config/opencode/command/dejavu.md` (Claude Code, Cursor, and Gemini CLI pick the same command up from the plugin bundle automatically: `commands/dejavu.md` for the first two, `commands/dejavu.toml` for Gemini).

Restart OpenCode. Gates appear automatically as failures recur — nothing to configure.

### Manual / from a clone (all harnesses)

```bash
git clone https://github.com/WhiteBite/dejavu-gates && cd dejavu-gates && bun install
bun scripts/install-hooks.ts --harness claude            # project scope (cwd)
bun scripts/install-hooks.ts --harness claude --user     # user scope (~/.claude/...)
bun scripts/install-hooks.ts --harness codex --dry-run   # preview without writing
```

The generator merges hook entries into the harness's config (`.claude/settings.json`, `.codex/hooks.json`, `.gemini/settings.json`, `.cursor/hooks.json`, `.github/hooks/dejavu.json`, `.crush/crush.json`, `.devin/hooks.v1.json`, `.kiro/hooks/dejavu-gates.json`) pointing at `bun "<clone>/src/cli.ts" <pre|post> --harness <name>`. It is idempotent, preserves other hooks/fields, and refuses to touch an unparseable config.

Harness specifics:

- **Codex**: hooks are a stable feature enabled by default; Pre/PostToolUse fire for every function tool with canonical hook names (`Bash` for shell, `apply_patch` for edits with `Write`/`Edit` matcher aliases, `spawn_agent`, MCP tools under flat names). dejavu's matcher covers `Bash` and `apply_patch`; a first-run trust prompt may still apply to project hooks.
- **Crush**: PreToolUse only (no AfterTool upstream) — dejavu runs degraded: blocking works, reminders can't annotate; the shared store still teaches Crush from gates learned elsewhere.
- **Devin CLI**: hooks live in `.devin/hooks.v1.json` where the file root IS the event map — the installer merges dejavu entries into it and strips them on uninstall, foreign events survive. Devin also auto-imports Claude-format hooks from `.claude/settings.json` (`read_config_from.claude`, on by default), so a Claude install already gates Devin sessions. No user-level hooks file is documented — project scope only.
- **Kiro**: hooks are standalone files under `.kiro/hooks/`; dejavu owns `dejavu-gates.json` there. Kiro blocks on any non-zero hook exit and injects a successful hook's stdout into agent context, so the reminding NOTE rides raw on stdout and an allow writes nothing. Kiro documents no user-level hooks path — project scope only.
- **Claude Code**: `PostToolUseFailure` is wired to the same post handler; payloads carry no exit codes, so failure detection runs on output text (the engine's text channel). The `SessionStart` hook injects a digest of the project's top enforced gates (blocking first, then reminding) as `additionalContext`, so the agent knows the gated calls before losing a first one to a reminder.

Manual invocation (any harness with command hooks):

```bash
echo '{"hook_event_name":"PreToolUse","session_id":"s","tool_name":"Bash","tool_input":{"command":"deploy.sh"},"cwd":"/repo"}' \
  | bun src/cli.ts pre --harness claude --store /repo
# exit 0 + {} = allow; exit 2 + stderr = blocked with a [dejavu] message
```

## Robustness & safety

- **Blocking policy** — only `bash` commands that are NOT diagnostics may ever become blocking gates. Diagnostics and iteration commands (tsc/eslint/mypy/pytest/phpunit/rspec/rubocop/gradle-test/`mvn test`/`dotnet test`/flutter/curl/grep, `dart run`, `go run|build|test|vet`, `cargo run|build|test|clippy`, `swift build|test`...) promote to `reminding` — they annotate the failing output with a `[dejavu] NOTE` (once per session) and never block or interrupt the run, so iterating on tests/builds is never punished. File probes (read/edit/write/glob/grep) stay `watching`: measured, visible in reports, never interrupting. Event-channel `tool-error` signatures (argless calls whose error text is the only identity) promote to `reminding` once their literal head carries enough identity — never `blocking`. `canBlock()`/`canRemind()` in `src/patterns.ts` are the single source of truth. Signatures without residual identity (see above) enforce at no tier.
- **One-liner identity** — for `python -c` / `node -e` / `bun -e` / `php -r` / `ruby -e` / `perl -e` / `julia -e` / `lua -e` / `Rscript -e` and PowerShell `-Command` the code payload IS the call, so it is fingerprinted (`<code:hash>`) instead of flattened to `<str>`: different scripts never share a gate, the same script failing repeatedly still converges. `-r` fingerprints only for php (node/ruby/perl `-r` is a preload flag). PowerShell shapes are covered — quoted exe paths (`& "C:\...\python.exe" -c ...`), here-string payloads, env-prefixed invocations (`PYTHONPATH=x python -c ...`). Legacy bare `-c <str>` shapes never enforce at any tier (residual-identity guard).
- **Wrapper unwrapping** — `cmd /c|/k "..."` normalizes to the INNER command: the gate key, identity and diagnostic tier all see the real call instead of a `cmd <path> <str>` shape matching every cmd invocation.
- **Clean persistence** — terminal control characters (PowerShell VT colors, NULs) are stripped before anything touches disk; signatures, snippets and corrections never carry ANSI escapes. Harness payloads are external untrusted input and cross the same `sanitizeForStore()` boundary before anything is persisted.
- **Secret scrubbing** — every signature and snippet passes `scrubSecrets()` (OpenAI/Anthropic/AWS/GitHub/Slack/Stripe/JWT/bearer/DB-conn-string/PEM patterns + `root@host`) before touching disk. Historical data is cleaned by `migrate()` at init or via `bun scripts/migrate.ts <dirs...>` (also scrubs logs).
- **Intended non-zero exits** — exit 1 from diagnostics is NOT a failure (that is their normal "found nothing / found issues" outcome). Exit ≥ 2 always counts.
- **Aborted ≠ failed** — cancelled/aborted tool executions ("Tool execution aborted") are infrastructure noise and are never counted as failures.
- **Long-running guard** — a FOREGROUND dev-server/watcher start (`npm run dev`, `next dev`, `vite`, `flask run`, `uvicorn`, `python -m http.server`, `mvn spring-boot:run`, `gradle bootRun`, …) would block the bash call until its timeout and strand an orphan process. dejavu interrupts it in the before-hook with a "run detached" reminder (tmux / `nohup … &` / `Start-Process` / a startup script that spawns detached). Detached forms (trailing `&`, `nohup`, `tmux`, `Start-Process`) and one-shots/builds (`vite build`, `npm run build`) pass silently; `# dejavu:proceed` allows a deliberate foreground run. The starter list is deliberately conservative (ambiguous `node <file>`, `go run`, `dotnet run` are not flagged).
- **Suppressed-spawn guard** — compensating measure for [anomalyco/opencode#29831](https://github.com/anomalyco/opencode) (remove when the upstream fix ships): a call that spawns a DETACHED daemon while piping/redirecting stdout (`… start | Out-Null`, `… start > $null`) hangs forever — opencode ends a bash call only on stdio EOF, and the living daemon keeps the pipe open. A static bounded list (`DETACHED_SPAWNERS`) is interrupted in the before-hook with the correction "run the spawn bare (1-3 lines of output) and poll status in a separate call". Bare spawns, non-spawn verbs, and stderr-only redirects (`2>`, `2>&1`) pass; `# dejavu:proceed` bypasses (logged as a warning).
- **Inherited-spawn guard** — the second leak path of the same EOF semantics, empirically verified: `Start-Process -RedirectStandard*`/`-Wait` turns ON handle inheritance, so the spawned process receives the call's stdio pipes and holds them until it exits — a daemon that outlives the call (`-WindowStyle Hidden|Minimized`, or a known server starter as the spawned command) hangs the call forever, and redirecting all three streams does NOT help (a bare `Start-Process` leaks nothing). The before-hook interrupts that shape and teaches bare spawns (daemon writes its own logs) or a two-stage spawn (outer bare `Start-Process` of a pwsh one-liner that redirects inside); `# dejavu:proceed` bypasses (logged).
- **Orphan-job guard** — `Start-Job` without an in-call wait runs inside the call's PowerShell and is killed silently when the call ends: "background" work that never survives, with no error anywhere. The before-hook interrupts it and teaches the detached bare-Start-Process pattern (or `Wait-Job`/`Receive-Job -Wait` for in-call results); `# dejavu:proceed` bypasses (logged).
- **Snowball guard** — an agent re-issuing its own previous bash command verbatim as a strict prefix with a new section appended (command accretion) re-executes every already-answered query and floods the context with duplicate output (the incident: a research subagent issued 30+ growing calls, 46 minutes, no deliverable). The before-hook denies the third consecutive growth call and teaches: issue only the NEW query as a fresh command — the cd/setup prefix belongs in the bash tool's workdir parameter, independent questions are parallel tool calls. Identical re-sends stay the repeat channel's business; `# dejavu:proceed` bypasses (logged).
- **File content is not command output** — in OpenCode, text failure signatures are scanned for `bash` only; `read`/`edit`/`write` failures come exclusively from the event channel (a file containing "TypeError" is not a failure). External harnesses deliver file-tool failures through their post hooks, where the tool's own error text (not file content) is the payload.
- **Concurrency** — gates.json mutations run under an exclusive lockfile; log appends and rotation take their own lock; writes are tmp+rename with EPERM/EACCES/EBUSY retry (Windows AV/indexer). NT long paths get the `\\?\` prefix. Parallel tool calls in the SAME process serialize on an in-process queue before ever touching the file lock. Across processes (several OpenCode windows, or parallel hook-CLI invocations from one harness), if a lock cannot be acquired within 3s the critical section degrades to unlocked (the tool pipeline must never hang) and emits a `degraded` log event. A transiently-unreadable store (AV lock, `EISDIR`) throws instead of parsing as empty, so a failed read can never let the next save clobber real gates.
- **Multi-process safe** — the remind→block escalation chain is persisted on the gate itself (`remindedSessions`/`failedSessions`), not in process memory: several windows, several harnesses, and short-lived hook-CLI processes on one store all see the same chain. Enforcement always reads fresh gate state under the store lock.
- **Near-duplicate consolidation** — new failures merge into existing patterns via normalized Levenshtein ≤ 0.3 with an absolute floor of 3 edits (replaces token Jaccard, which collapsed all `<str>` placeholders; the floor stops `git push` vs `git pull`-style merges).
- **Bounded memory** — per-session maps are capped (50 entries per gate) and freed on session end; handled part IDs evict FIFO; TTL expiry and log rotation re-run every 6 h in long-lived processes (the CLI runs its idempotent init passes per invocation and flushes deferred log events before exit).
- **Migration** — gates outside the blocking policy are re-tiered automatically (diagnostics land in `reminding`, everything else in `watching`); already-proven recurring diagnostics start reminding immediately; project copies of already-global gates are merged into the global gate (evidence is consolidated, never deleted).
- **Self-healing** — every init reconciles the stores: an unparseable `gates.json` is quarantined (bytes preserved as `gates.json.corrupt-<ts>`), gate records are strictly parsed and mechanically repaired (inverted dates swapped, duplicate keys merged, secrets/control-chars re-sanitized, stale blocking demoted), unparseable log lines are excised to `log.jsonl.corrupt`, and the cross-project index is reconciled. Every repair is logged as a `repaired`/`quarantined` event.
- **Gates heal, not just accumulate** — dejavu sees successes too: a SUCCESS matching an enforced gate grows `succeededAfterGate`, and after 3 in a row the gate retires to `watching` (logged `healed`), so a command you fixed stops triggering reminders. A failure resets the streak. The negative twin: a gate the agent keeps fighting (recurrences or explicit overrides) demotes itself (logged `demoted`) — enforcement listens to behavior in both directions. Third path: a gate reminded 5+ times with zero reoffense has TAUGHT its lesson — it retires softly (logged `retired-taught`), re-promotion on new failures stays possible. Fourth path: reminders reaching 10 with 1–2 reoffenses (too ignored for taught, not ignored enough for anti-nag) retire as chronic (logged `retired-chronic`). A gate promoted and retired three times each never re-promotes mechanically — the promote→retire oscillation is terminal (logged `demoted`). Heal-aware: a blocking gate with a live heal streak does not interrupt the first run — it lets a likely-fixed command run and blocks only a repeat failure.
- **Auto-corrections, no manual work** — a promoted gate always ships with a mechanical, overridable default correction chosen by command family (stale `--check` artifacts, failing tests, type errors, network, installs, go/cargo/maven/dotnet/rspec/phpunit/make builds) or from the captured error line, so a gate never sits "NOT TEACHING" awaiting a human. `migrate()` backfills existing gates.
- **Repeat channel (OpenCode only)** — DashScope/Qwen hard-rejects a request whose history carries the same tool call (name + args byte-identical) in consecutive rounds (HTTP 400), and one rejection poisons the session forever. The transform hook scans every outgoing payload statelessly: occurrences past the first of an identical-consecutive series get a `_dejavu_repeat` marker (payload-only, never persisted), a series reaching the tail gets a `[dejavu] REPETITION` note on its last tool result, and a third identical call is hard-blocked in the before-hook. Windowed near-repeats earn a `[dejavu] SHAPE LOOP` note only when the normalized call shape repeats (bash trailing comments and rotating scratch-buffer temp paths collapse; numeric args, moving offsets and distinct temp files stay distinct — they are data) AND the last two results are meaningfully identical; the note is advisory and never escalates to an injection or a stop. Bypass: `_dejavu_proceed: true` in args (logged as override). No gates, no persistence, no promotion — pure payload hygiene.
- **Loop break (OpenCode only)** — a model that keeps re-issuing the call past the REPEAT STOP message gets an automated user-role message appended to the outgoing payload (payload-only, marked `synthetic`). Blocked tool errors are an in-loop stimulus that weak models read as "retry"; a user-role turn is the one stimulus that reliably forces a text reply and ends the loop. The injection fires only while the same series owns the tail — a real user message or a text reply ends it — and logs `loop-break` once per series.

## Observability (debugging aids)

- Every `log.jsonl` gets an `init` event with `PLUGIN_VERSION`; `detected` events carry `channel` (`exit`/`text`/`event`) and the raw exit code; `reminded`/`blocked` carry `via` (`exact`/`fuzzy`/`segment`). Stale plugin sessions are therefore visible in the data. A long-lived host that finds a store last written by a newer plugin self-surfaces the drift at boot — a warn line plus a `version-drift` log event — instead of waiting for a doctor run.
- `bun scripts/doctor.ts [--repair] [projectDirs...]` — one-command report over every invariant the data model implies: gate shape, duplicate keys, temporal order, nested-token corruption, blocking without evidence, policy violations, index↔gates consistency, stale project copies, missed escalation, log integrity, secrets, version drift. `--repair` heals first (idempotent), then reports. `dejavu report [dirs...]` (the npm bin) runs the same report for any harness, no OpenCode needed.
- `bun scripts/analyze.ts [projectDirs...]` — store summary: statuses, tools, top patterns.
- `dejavu lesson list` / `dejavu lesson set <key> "<one-line fix>"` — review gates whose `correction` is still the machine default and write a human correction onto an existing gate (cannot create gates; promotion stays mechanical). A `lesson set` also clears the gate's `review` flag — the rewrite is the review doctor asked for. `lesson list --all` includes watching gates; `lesson set --author owner|agent` records who wrote the correction; `lesson retire-when <key> <spec>` declares an external invalidation (`dep:<name>@>=<min>`, `path-present/absent:<p>`, `tag:<name>`) that `doctor` evaluates.
- `/dejavu` command (OpenCode, installed globally) runs doctor first, then reports.
- Hook CLI diagnostics: set `DEJAVU_DEBUG=1` to see engine log lines on stderr (stdout always stays pure JSON).

## Detection coverage

| Channel | Catches |
|---|---|
| exit code + output text (OpenCode `tool.execute.after`) | bash failures (non-zero exit, TS errors, test failures, stack traces) |
| output text only (external harness post hooks — no exit codes exist there) | failure-shaped output: `error TS…`, `FAIL`, `panic:`, `[ERROR]`, PHPUnit/`FAILURES!`, `Fatal error:`, TAP `not ok`, … |
| `message.part.updated` event scan (OpenCode) | tool-level failures (read of missing file, rejected edits) that never reach the after-hook; error text is Sentry-style parameterized |
| chain-segment matching | gates fire even when the gated command hides inside `x && gated-cmd` chains, `cmd /c "..."` wrappers, or `$(...)` / backtick substitutions |
| `experimental.chat.messages.transform` (OpenCode) | repeat channel: consecutive identical tool calls sanitized in the outgoing payload (DashScope 400 prevention) + NOTE at 2nd round, hard block at 3rd |
| companion skill | agent behavior protocol (how to react, when to annotate) |
| `/dejavu` command | status report: active gates, recurrence metric, review flags |

Language ecosystems covered by failure detection: JS/TS, Python, Go, Rust, Java/Kotlin/Scala (Maven/Gradle/sbt), .NET, Ruby, PHP (PHPUnit), Dart/Flutter, C/C++, Elixir; shells: bash, PowerShell, cmd. Not covered (by design): semantically-equivalent-but-syntactically-different failures beyond fuzzy (Levenshtein ≤ 0.3, ≥ 3 edits) matching.

## Data files

| File | Contents |
|---|---|
| `~/.config/opencode/dejavu/gates.json` | global gates (agent habits) |
| `~/.config/opencode/dejavu/index.json` | cross-project pattern index: which project dirs each failure key was seen in (escalation evidence) |
| `<repo>/.opencode/dejavu/gates.json` | project gates (repo gotchas) |
| `*/dejavu/log.jsonl` | every event: detected, promoted, reminded, retry-allowed, blocked, override, expired, recurred-after-gate, demoted, healed, retired-healed, retired-taught, repaired, quarantined, degraded, init |
| `*/dejavu/*.corrupt*` | quarantined corruption (unparseable gates.json, excised log lines) — bytes preserved for forensics; safe to delet...

© WhiteBite · MIT · hashgraph-online/awesome-codex-plugins

Similar plugins

All plugins for Agent setup: memory, context, orchestration →

From the same set391

The whole set →
devin The plugin puts Devin inside Claude and Claude: code reviews that only read files, adversarial passes, delegated tasks and cloud handoff to app.devin.ai. CX Codex ★ 1,596repo stars designer-skill designer-skill is a plugin for Claude Code and Codex that routes UI design requests, retrieves guides, and checks code against 44 static rules without an API key. CX Codex ★ 1,596repo stars design-helper The design-helper plugin puts CSS, layout, and motion options side by side in a browser, then applies your choice to the project. Use it before committing to a UI change. CX Codex ★ 1,596repo stars delx-recovery delx-recovery — a plugin that reopens an agent's earlier sessions, records where the work stands and turns failures into a recovery plan. Session memory sits on a hosted MCP server. CX Codex ★ 1,596repo stars deepseek-minimal-anchor The deepseek-minimal-anchor plugin tunes DeepSeek sessions in Codex: Pro keeps a one-line anchor, while Flash follows a task-aware decide-and-verify contract. CX Codex ★ 1,596repo stars debt-ops The debt-ops plugin for Claude Code and Codex records deferred agent decisions in a repo registry; its review skill ranks debt by file churn. CX Codex ★ 1,596repo stars core-learning core-learning structures study sessions around Socratic questioning, Feynman teach-back, and spaced recall to deliver working projects. CX Codex ★ 1,596repo stars context-guard context-guard is a Claude Code and Codex plugin that preserves requirements and verification evidence in long Codex tasks. It restores open items after context compaction and checks evidence before marking work complete. CX Codex ★ 1,596repo stars

Project sponsors

Companies that keep this analytics open