Skip to content
Back to search

groundhog

MarketplaceWorks with Claude CodeGitHub

groundhog plugin marketplace

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/shiroe-95--groundhog/badge.svg)](/listings/shiroe-95--groundhog)

HTML

<a href="/listings/shiroe-95--groundhog"><img src="/api/listings/shiroe-95--groundhog/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Inside Claude Code:

/plugin marketplace add Shiroe-95/groundhog
/plugin install groundhog@groundhog

Or from a terminal:

claude plugin marketplace add Shiroe-95/groundhog
claude plugin install groundhog@groundhog

You need Node.js 20.1 or newer on your `PATH`. Claude Code users almost always have it already.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 15 lines
  1. {
  2. "name": "groundhog",
  3. "owner": {
  4. "name": "Wilson Vargas Martinez",
  5. "url": "https://www.linkedin.com/in/wilsonvm09"
  6. },
  7. "description": "groundhog plugin marketplace",
  8. "plugins": [
  9. {
  10. "name": "groundhog",
  11. "source": "./",
  12. "description": "Notices when the agent keeps hitting the same error through different commands, or keeps undoing its own edits."
  13. }
  14. ]
  15. }
README.md · README · 436 lines
  1. <div align="center">
  2. **English** · [Español](README.es.md)
  3. <img src="assets/banner.svg" alt="Three different commands hit the same error wall" width="100%">
  4. # groundhog
  5. **Your coding agent keeps waking up in the same error. groundhog notices.**
  6. A Claude Code plugin that spots when the agent hits the same wall through *different* commands, or keeps rewriting its own edits, and tells it to stop and think before the next try.
  7. [![CI](https://github.com/Shiroe-95/groundhog/actions/workflows/ci.yml/badge.svg)](https://github.com/Shiroe-95/groundhog/actions/workflows/ci.yml)
  8. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  9. ![Node >= 20.1](https://img.shields.io/badge/node-%3E%3D20.1-339933)
  10. ![Dependencies: 0](https://img.shields.io/badge/dependencies-0-brightgreen)
  11. ![Network calls: 0](https://img.shields.io/badge/network%20calls-0-brightgreen)
  12. [In 30 seconds](#in-30-seconds) · [The problem](#the-problem) · [What you get](#what-you-get) · [How it compares](#how-it-compares) · [How it works](#how-it-works) · [Install](#install) · [Evidence](#evidence) · [Research](#research-behind-it) · [Privacy](#privacy-and-security)
  13. </div>
  14. ---
  15. ## In 30 seconds
  16. New to all this? Start here.
  17. - **Claude Code** is an AI assistant that works inside your project. It reads files, edits code and runs commands (tests, builds, scripts) on its own. People call this kind of assistant a *coding agent*.
  18. - **The problem:** sometimes the agent gets stuck. A command fails, it tries a slightly different command, it fails with the very same error, and it keeps going like that. Each try costs time and money, and fills its memory with the same error again and again. The agent does not always realize it is going in circles.
  19. - **What groundhog does:** it watches for that pattern. When the same error comes back, it adds a short note for the agent: *"this is the same problem as before, here is what you already tried, stop and test a real idea."* If it happens a third time, the note says: *"stop guessing: find the cause, hand it to a fresh helper, or ask the user."*
  20. - **What you do:** install it once. There is nothing to run and nothing to configure. It stays quiet until the agent repeats a failure.
  21. - **What it never does:** it does not block the agent, change your code, or send anything over the internet. It only adds a few lines of advice at the right moment.
  22. Think of a colleague looking over the agent's shoulder who says *"you already tried that, it's the same error"* before the sixth attempt instead of after it.
  23. The name comes from the film *Groundhog Day*, where the main character wakes up to the same day over and over until he changes his approach. A stuck agent lives the same error over and over. groundhog points that out.
  24. **Who it is for:** anyone who lets Claude Code run commands on its own: developers, teams that use it in long sessions, and people who are not experts and cannot always tell when the agent is spinning its wheels.
  25. ## The problem
  26. You have seen it. The agent runs the tests, gets an error, tweaks the command, gets the same error, tries a different flag, then a different file, then a different tool. Six attempts later nothing has moved, and the context window is full of near-identical failures.
  27. **Without groundhog:**
  28. ```
  29. > npm test Error: Cannot find module '/app/src/db.js'
  30. > npx jest Error: Cannot find module '/app/src/db.js'
  31. > node test/run.js Error: Cannot find module '/app/src/db.js'
  32. > npm test -- --runInBand Error: Cannot find module '/app/src/db.js'
  33. > ... (the agent keeps guessing; you keep paying)
  34. ```
  35. **With groundhog**, on the second failure the agent is told that this is the same wall, shown what it already tried, and asked for a testable hypothesis. On the third it is told to stop guessing and either find the root cause, hand off to a fresh subagent with a short brief, or ask you.
  36. Most loop guards look for **identical** calls: same tool, same arguments, over and over. That catches the dumbest loop, but it is not the common one. The agent rarely repeats itself exactly. It changes the input every time, and the error stays the same.
  37. Measured with `/groundhog-report` on a sample of 620 real Claude Code sessions:
  38. | What | Count |
  39. | --- | --- |
  40. | Sessions scanned | 620 |
  41. | Sessions that hit at least one wall | 114 (18%) |
  42. | Walls (same tool, same error, 3+ times in one session) | 140 |
  43. | Failed calls spent inside those walls | 632 |
  44. | Walls where the agent **changed the input at least once** | 108 (77%) |
  45. | Walls made only of identical retries | 32 (23%) |
  46. | Edits that undid an earlier edit (A to B, back to A) | 14 |
  47. In three out of four walls the agent changed the command along the way, so a detector that waits for N identical calls in a row sees a shorter loop, or none at all. groundhog counts the error instead, so the changes do not hide the wall.
  48. You can get the same table for your own sessions with `/groundhog-report`.
  49. ## What you get
  50. | Benefit | What it means for you | Where the number comes from |
  51. | --- | --- | --- |
  52. | **Fewer wasted retries** | The agent is told it is looping on the 2nd failure, not the 6th. In the sample, 16% of all failed calls came after that point. That is the ceiling on what the note can save. | [Evidence](#evidence) |
  53. | **A cleaner context window** | Every repeated failure pastes the same error into the conversation again. Stopping the loop earlier leaves more room for the work that matters. | [Evidence](#evidence) |
  54. | **You hear about blockers sooner** | On the 3rd hit the agent is asked to find the root cause, hand off with a short brief, or ask you, instead of guessing quietly while you wait. | [What the agent sees](#what-the-agent-sees) |
  55. | **No more edit ping-pong** | It notices when an edit undoes an earlier one, or when the agent keeps rewriting the same lines after each failure. | [How it works](#how-it-works) |
  56. | **Nothing to pay when things go well** | No note unless something actually repeats: about one per 100 tool calls. It never blocks a tool, makes no network calls and has no dependencies. | [Evidence](#evidence), [Privacy](#privacy-and-security) |
  57. | **Works with what you already use** | Covers MCP tools too, defers to your own debugging skill if you have one, and runs next to other hooks. | [Plays well with your setup](#plays-well-with-your-setup) |
  58. | **A mirror of your own sessions** | `/groundhog-report` tells you how often your agent gets stuck and where, before you install anything. | [Usage](#usage) |
  59. ## How it compares
  60. There are four common ways to deal with a stuck agent today. Each one solves part of the problem:
  61. | Approach | Catches a loop where the command keeps changing | Catches edit ping-pong | Never blocks a tool | Speaks up on its own, at the right moment |
  62. | --- | --- | --- | --- | --- |
  63. | Do nothing, let the agent retry | No | No | Yes | No |
  64. | Identical-call loop detectors (LoopGuard, loop-circuit-breaker, agent-loop-detector) | Only once the call repeats exactly | No: an edit and its undo are different calls | Depends on the tool | Yes |
  65. | Block the tool after N failures | Only if it counts failures, not calls | No | No | Yes, by stopping the agent |
  66. | Debugging rules in `CLAUDE.md` or a debugging skill | Only if the agent notices it is looping | No | Yes | No: the agent has to remember them |
  67. | **groundhog** | **Yes: it counts the error, not the command** | **Yes: reverts and rework** | **Yes** | **Yes: on the 2nd and 3rd hit** |
  68. Why that matters: in the sample, 77% of walls had the command changed at least once, so the first and third rows see a shorter loop or none at all. groundhog does not replace the others. It works next to an identical-call detector, and when you have a debugging skill it tells the agent to use it at the moment it is needed. More detail in [Why not just...](#why-not-just).
  69. ## How it works
  70. groundhog is two small hooks and two skills. No network, no dependencies, no background process.
  71. ```
  72. tool fails ──> PostToolUseFailure hook (any tool, MCP tools included)
  73. │
  74. ├─ normalize the error into a signature
  75. │ paths -> <path> hashes -> <hex> numbers -> <n>
  76. │
  77. ├─ same tool + same (or nearly the same) signature? count it
  78. ├─ more tests passing than last time? progress: reset the count
  79. │
  80. ├─ 2nd hit: hypothesis, prediction, check
  81. └─ 3rd hit: stop. root cause, fresh subagent, or ask the user
  82. Edit succeeds ──> PostToolUse hook
  83. ├─ this edit reverses an earlier one? say so
  84. └─ rewriting its own lines again after a failure? say so
  85. ```
  86. **The signature is the key idea.** `Cannot find module '/home/a/src/db.js'` and `Cannot find module 'C:\work\src\db.js'` are the same wall. Line numbers, temp paths, commit hashes and ports change on every attempt. The cause does not. groundhog strips the noise and keeps the shape of the error. Two long errors from the same tool that differ in a single word (a workspace name, say) are also treated as one wall.
  87. When the count crosses a threshold, the hook adds a short note next to the tool result. The agent sees it on its next turn. groundhog never blocks a call and never rewrites output. It only adds evidence.
  88. ### Inside the failure hook, step by step
  89. Claude Code runs the hook after every tool call that fails. It reads the failure, updates a small counter for the session and, if needed, prints a note. The whole run takes milliseconds, and if anything goes wrong inside the hook it exits quietly, so it can never break your session. Failures caused by you pressing Esc are ignored.
  90. 1. **Pick the line that matters.** Colors and `exit code N` lines are dropped. groundhog takes the first line that looks like an error (it contains words such as *error*, *fail*, *not found*, *denied*, *cannot*, *invalid* or *exception*), or the first line if none does.
  91. 2. **Mask secrets first.** URLs, email addresses, `password=...`, `token=...` and API-key-shaped strings are replaced before anything else happens, so they are never stored or shown.
  92. 3. **Remove what changes between attempts.** Paths become `<path>`, host names `<host>`, hashes and ids `<hex>`, and every number `<n>`. The result is cut to 120 characters. That is the *signature*.
  93. 4. **Find the wall.** The wall is "this tool + this signature". If there is no exact match, groundhog looks for a near match from the same tool: both signatures have at least 4 words and share 80% or more of them. That catches two long errors that differ only in a name, while short and different errors stay apart.
  94. 5. **Check for progress.** If the output is a test summary and more tests pass than the last time this wall was seen, the agent is getting somewhere, so the count starts over.
  95. 6. **Count and remember.** The wall's count goes up by one. groundhog keeps a short summary of the last 5 attempts (the command, file or first text argument, with secrets masked) and a fingerprint of the last 2 inputs, which tells it whether the agent changed anything or retried the exact same call.
  96. 7. **Decide whether to speak.**
  97. | Hit | What happens |
  98. | --- | --- |
  99. | 1st | Nothing. One failure is normal work. |
  100. | 2nd (`GROUNDHOG_WARN_AT`) | The "hypothesis" note: what was tried, whether the input changed, and three steps: one hypothesis, the cheapest check with a predicted output, the quoted line that settles it. |
  101. | 3rd and later (`GROUNDHOG_STOP_AT`) | The "stop" note: stop retrying and pick root cause, a fresh subagent with a short brief, or ask the user. |
  102. If the tool that failed is `Edit`, the note adds a hint to re-read the file first, since that failure almost always means the file no longer matches what the agent remembers. Both thresholds can be changed in [Configuration](#configuration).
  103. ### Inside the edit hook
  104. After every `Edit` that succeeds, a second hook looks at what was replaced. It stores only fingerprints (hashes) of the old and new text, never the file contents.
  105. - **Revert:** the agent changed A into B earlier, and now changes B back into A in the same file. groundhog says so on the first revert, because the agent is oscillating between two versions.
  106. - **Rework:** the agent rewrites lines it wrote itself earlier in the session, and some tool failed since its last edit to that file. That is the edit, fail, re-edit loop. Rewriting your own code is normal, so the note only appears every 3rd time.
  107. ### What it keeps, and for how long
  108. One small JSON file per session, in the folder Claude Code gives the plugin (or a private temp folder). It holds counts, short attempt summaries with secrets masked, and hashes. Files older than 7 days are deleted, and a damaged file is simply replaced by a fresh one. Details in [Privacy and security](#privacy-and-security).
  109. The two skills are `unstick`, the full recovery protocol the stop note points to, and `/groundhog-report`, which runs the same detector over your saved sessions.
  110. ### What the agent sees
  111. This is the real output of the hook, copied from a run.
  112. On the second hit:
  113. ```
  114. groundhog: this is the 2nd time this session that Bash failed with the same error signature:
  115. "Error: Cannot find module '<path>'"
  116. Recent attempts:
  117. 1. npm test
  118. 2. npx jest
  119. The input changed but the error did not, so the cause is probably not what the last attempt changed. Before the next retry:
  120. 1. Write one sentence with a new hypothesis that explains every failure above.
  121. 2. Pick the cheapest check that could prove it wrong, and predict what it will print.
  122. 3. Run it and quote the line of output that confirms or kills the hypothesis.
  123. If you have your own debugging skill or process, use it for these steps.
  124. ```
  125. On the third:
  126. ```
  127. groundhog: this is the 3rd time this session that Bash failed with the same error signature:
  128. "Error: Cannot find module '<path>'"
  129. Recent attempts:
  130. 1. npm test
  131. 2. npx jest
  132. 3. node test/run.js
  133. Stop retrying variations: this is a wall, not bad luck. Pick one:
  134. a) Read the full error and the exact code or config it points at, then state the root cause.
  135. b) Hand the problem to a fresh-context subagent.
  136. c) Ask the user.
  137. For b) and c), send a brief, not logs: the goal, the facts you verified (with the command that verified each), the hypotheses you ruled out, and the signature above.
  138. If you have your own debugging skill or process, use it now; otherwise the groundhog:unstick skill has the full protocol.
  139. ```
  140. When an edit reverses an earlier edit to the same file (wrapped here for reading; the real note is one line):
  141. ```
  142. groundhog: this edit undoes an earlier edit to config.ts in this session
  143. (back-and-forth #1). You are oscillating between two versions. Before touching
  144. this file again, decide which version is correct and cite the evidence (test output,
  145. docs, the caller that needs it).
  146. ```
  147. When the agent keeps going edit, fail, re-edit on the same lines (also wrapped):
  148. ```
  149. groundhog: you have rewritten lines you wrote earlier in parser.js 3 times this session.
  150. Editing the same spot again and again usually means each change is a guess. Before the
  151. next edit to this file, run the check that shows whether the last change worked, and
  152. say what it printed.
  153. ```
  154. ### A full example, step by step
  155. Here is one session from start to finish, so you can see when groundhog speaks and when it stays quiet. The commands and errors are an example; the notes use the real wording shown above.
  156. 1. **You ask:** "Add a login endpoint and make the tests pass."
  157. 2. **The agent edits a few files and runs `npm test`.** It fails: `Error: Cannot find module '/app/src/db.js'`.
  158. groundhog stores the error's signature (`Cannot find module '<path>'`) and **says nothing**. One failure is normal.
  159. 3. **The agent tries `npx jest`.** Same error.
  160. groundhog sees the same signature from the same tool a second time and **adds the 2nd-hit note**: same wall, here are your two attempts, write a hypothesis, predict what a cheap check will print, run it and quote the result.
  161. 4. **The agent stops guessing and states a hypothesis:** "The tests import `src/db.js`, but the file was moved." It predicts that `ls src` will not list `db.js`, runs it, and quotes the output: `database/ routes/ server.js`. Hypothesis confirmed.
  162. 5. **The agent fixes the import to `src/database/db.js` and runs `npm test`.** Tests pass. The loop ended on attempt 2.
  163. If the agent had ignored the note and tried `node test/run.js`, the third failure would bring the **stop note**: find the root cause by reading the error and the code it points at, hand the problem to a fresh subagent with a short brief, or ask you. Either way, you hear about it on attempt 3, not after attempt 10.
  164. Without groundhog, the same session often looks like the "Without groundhog" block at the top: four, six, ten variations of the same command, each one pasting the same error into the conversation.
  165. ## Install
  166. Inside Claude Code:
  167. ```
  168. /plugin marketplace add Shiroe-95/groundhog
  169. /plugin install groundhog@groundhog
  170. ```
  171. Or from a terminal:
  172. ```bash
  173. claude plugin marketplace add Shiroe-95/groundhog
  174. claude plugin install groundhog@groundhog
  175. ```
  176. You need Node.js 20.1 or newer on your `PATH`. Claude Code users almost always have it already.
  177. ## Usage
  178. Once installed, there is nothing to run. The hooks work on their own.
  179. | Command | What it does |
  180. | --- | --- |
  181. | `/groundhog-report` | Scans your local session history and shows your top walls, how many had changing inputs, and how many edits were reverted. |
  182. | `groundhog:unstick` skill | The playbook the agent follows when a note appears. The agent loads it on its own. You can also call it by name. |
  183. You can run the report outside Claude Code too:
  184. ```bash
  185. node scripts/report.js # English
  186. node scripts/report.js --lang es # Spanish
  187. node scripts/report.js --json # raw numbers
  188. node scripts/report.js --dir /path/to/transcripts
  189. ```
  190. ## Plays well with your setup
  191. groundhog is meant to sit under whatever you already use, not replace it.
  192. - **Your skills come first.** Every note says: *"If you have your own debugging skill or process, use it."* If you have a debugging skill, a test-first workflow or a house playbook, the agent is pointed back to it. `groundhog:unstick` is only the fallback.
  193. - **MCP tools are covered.** The failure hook matches every tool, so a database, browser or API server that keeps failing the same way is counted like `Bash` (there is a test for `mcp__db__query`).
  194. - **It never blocks.** It does not deny calls, rewrite output or stop the session. It only adds a few lines of context, so it cannot break another plugin's hooks or your own.
  195. - **It coexists with other hooks.** Claude Code runs all matching hooks. groundhog's run in milliseconds, write only to their own data folder and stay silent on anything they don't understand.
  196. - **One switch to turn it off:** `GROUNDHOG_DISABLE=1`.
  197. ## Configuration
  198. All settings are environment variables. Set them in your shell or in the `env` block of your Claude Code settings.
  199. | Variable | Default | Meaning |
  200. | --- | --- | --- |
  201. | `GROUNDHOG_WARN_AT` | `2` | Hit number that triggers the first note (2 to 20). |
  202. | `GROUNDHOG_STOP_AT` | `3` | Hit number that triggers the "stop" note (never lower than `WARN_AT`). |
  203. | `GROUNDHOG_DISABLE` | unset | Set to `1` to turn groundhog off without uninstalling it. |
  204. ## Evidence
  205. Claims are cheap, so here is what you can check yourself.
  206. **It works as described.** 56 automated tests with Node's built-in runner, on Linux, macOS and Windows with Node 20, 22 and 24 in CI. They cover the 2nd and 3rd hit, near-duplicate errors that should merge and short errors that must not, progress resets, reverts, rework, MCP tools, malformed and oversized input, path traversal in session ids, corrupt state files and secret masking. The messages above are pasted from a real run, not written by hand.
  207. ```bash
  208. node --test
  209. claude plugin validate . --strict
  210. ```
  211. **What it would have caught.** `bench/replay.js` replays your saved sessions through the same detector and counts what happened *after* groundhog would have spoken. On the same 620 sessions:
  212. | What | Value |
  213. | --- | --- |
  214. | Tool calls replayed | 78,443 |
  215. | Failed tool calls | 2,203 (2.8%) |
  216. | Notes groundhog would have added | 863 (1.1 per 100 tool calls) |
  217. | Sessions that would get at least one note | 266 (43%) |
  218. | Failed calls that came **after** the first note on their wall | 352 (16% of all failures) |
  219. | Failed calls that came **after** the "stop" note | 212 (9.6% of all failures) |
  220. | Error output in those 352 calls | about 28k tokens |
  221. Read this as an upper bound, not an A/B test. It shows how much failed work happened after the point where groundhog speaks, which is the most a note could save. It does not prove the agent would have listened. The note rate is the cost side: about one short note per hundred tool calls. That still means four sessions in ten would see at least one, so the notes are kept short and only appear when something actually repeats.
  222. Run it on your own history (it prints aggregates only, never commands or file names):
  223. ```bash
  224. node bench/replay.js # ~/.claude/projects
  225. node bench/replay.js --json
  226. node bench/replay.js --dir /path/to/transcripts
  227. ```
  228. ## Research behind it
  229. Every design choice maps to published work. groundhog does not reproduce these papers' experiments; it applies their findings to one narrow problem.
  230. | Design choice | What the research says | Source |
  231. | --- | --- | --- |
  232. | Speak early: 2nd hit, stop at 3rd | Debugging effectiveness decays fast with each repeated attempt; a strategic fresh start helps | Adnan & Kuhn 2025, [The Debugging Decay Index](https://arxiv.org/abs/2506.18403) |
  233. | Hand off to a fresh context, not keep going | Models that take a wrong turn in a long conversation rarely recover; a clean start with the facts consolidated does better | Laban et al. 2025, [LLMs Get Lost In Multi-Turn Conversation](https://arxiv.org/abs/2505.06120) |
  234. | | Models condition on their own earlier mistakes and make more of them over long tasks | Sinha et al. 2025, [The Illusion of Diminishing Returns](https://arxiv.org/abs/2509.09677) |
  235. | "Send a brief, not logs" | Dropping old tool output works as well as summarizing it, and costs less | Lindenbauer et al. 2025, [The Complexity Trap](https://arxiv.org/abs/2508.21433) |
  236. | Short note placed right next to the failure | Information buried in the middle of a long context is often ignored | Liu et al. 2023, [Lost in the Middle](https://arxiv.org/abs/2307.03172) |
  237. | Hypothesis must be tested by running something | Self-correction without external feedback does not help, and can hurt | Huang et al. 2023, [LLMs Cannot Self-Correct Reasoning Yet](https://arxiv.org/abs/2310.01798) |
  238. | | Self-correction works when reliable external feedback is available | Kamoi et al. 2024, [When Can LLMs Actually Correct Their Own Mistakes?](https://arxiv.org/abs/2406.01297) |
  239. | | Self-repair gains are modest once its cost is counted; better feedback is what helps | Olausson et al. 2023, [Is Self-Repair a Silver Bullet for Code Generation?](https://arxiv.org/abs/2306.09896) |
  240. | Hypothesis, prediction, check, quote the result | A scientific-debugging loop (hypothesize, predict, experiment, conclude) matches repair baselines while producing explanations that helped developers judge patches | Kang et al. 2023, [Explainable Automated Debugging via LLM-driven Scientific Debugging](https://arxiv.org/abs/2304.02195) |
  241. | | Explaining code against real execution results helps models fix their own bugs | Chen et al. 2023, [Teaching LLMs to Self-Debug](https://arxiv.org/abs/2304.05128) |
  242. | | Short verbal reflection on a failure improves the next attempt | Shinn et al. 2023, [Reflexion](https://arxiv.org/abs/2303.11366) |
  243. | Near-duplicate errors count as one wall | In a study of one agent app, combining structural and semantic similarity found more cycles than either alone | George et al. 2025, [Unsupervised Cycle Detection in Agentic Applications](https://arxiv.org/abs/2511.10650) |
  244. | Edit-tool hint and rework detector | The agent-computer interface shapes coding agents; failed edits tend to cascade into more failed edits | Yang et al. 2024, [SWE-agent](https://arxiv.org/abs/2405.15793) |
  245. | Treat repetition as a failure mode at all | Step repetition and not knowing when to stop are recurring failure modes in agent systems | Cemri et al. 2025, [Why Do Multi-Agent LLM Systems Fail?](https://arxiv.org/abs/2503.13657) |
  246. ## Privacy and security
  247. groundhog was built to be safe to install on a work machine.
  248. **What it runs:** two Node.js scripts, only when a tool fails or an `Edit` succeeds. Each one reads the hook payload from stdin, updates a small JSON file and exits. Nothing stays running.
  249. **What it stores:** one JSON file per session in the plugin data folder Claude Code provides (or a per-user folder in your OS temp folder), readable only by you, deleted after 7 days. It holds:
  250. - for each wall: the normalized error signature (paths, numbers, URLs, emails and tokens masked; it can still contain words like a table or module name), a counter, the best "N passed" seen, hashes of the last two inputs, and the last 5 commands, cut to 100 characters, with URLs, emails, tokens and `key=value` secrets masked;
  251. - for up to 100 edited files: a hash of the path, truncated SHA-256 hashes of edit text and of edited lines (never the text itself), and revert and rework counters;
  252. - a running count of failures in the session.
  253. **What it sends:** nothing. There are no network calls. Check with `grep -r "http" scripts/`.
  254. And:
  255. - **No dependencies.** Only the Node.js standard library. There is no supply chain to compromise.
  256. - **Scrubbed output.** Signatures replace paths, URLs, emails, tokens, hashes and numbers with placeholders. The report goes further: it never prints commands, and it masks quoted names, CamelCase identifiers and MCP server names. Masking is pattern-based, so take a quick look before you post a report publicly.
  257. - **Fails closed to silence.** Malformed input, a corrupt state file or an oversized payload makes the hook exit quietly. It never breaks your session.
  258. - **Read-only report and bench.** They only read transcripts. They write nothing.
  259. Found a security issue? See [SECURITY.md](SECURITY.md).
  260. ## Why not just...
  261. **...use an identical-call loop detector?** Tools like LoopGuard, loop-circuit-breaker and agent-loop-detector are good at what they do. But they fingerprint the *call*, and in the measured sample most walls change the call every time. groundhog fingerprints the *error*. The two approaches work fine together.
  262. **...block the tool after N failures?** Blocking gets in the way when the retry is deliberate, like polling a server that is still starting. A note leaves the decision to the agent and keeps you in control.
  263. **...use a Stop hook?** Stop hooks from plugins have rough edges ([anthropics/claude-code#10412](https://github.com/anthropics/claude-code/issues/10412)). Commenting on the failure right where it happens is simpler and works today.
  264. Related discussions: [#4317](https://github.com/anthropics/claude-code/issues/4317) (loop detection), [#12768](https://github.com/anthropics/claude-code/issues/12768) (thrashing detection), [#47033](https://github.com/anthropics/claude-code/issues/47033) (session-level failure tracking), [#42796](https://github.com/anthropics/claude-code/issues/42796) (loop rate).
  265. ## Limitations
  266. - The signature is a heuristic. Two different bugs can share an error line ("Segmentation fault"), and one bug can print two different lines. The near-duplicate merge joins errors from the same tool whose sets of distinct words overlap 80% or more. In practice one differing word is only absorbed when the error has 9 or more distinct words, so short errors stay apart, but two long errors that differ only in a type name can be joined. The thresholds are low on purpose so a false alarm costs one sentence.
  267. - The progress reset only understands test runners that print "N passed".
  268. - Only `Edit` calls are checked for reverts and rework. Changes made with `Write` or a shell command are not seen.
  269. - Counters are per session. A wall that spans several sessions is visible in the report, not live.
  270. - The report and bench read the transcript format Claude Code uses today. If that format changes, they may undercount until updated. The hooks do not depend on it.
  271. ## Words used in this README
  272. | Word | Meaning |
  273. | --- | --- |
  274. | **Agent** | The AI (here, Claude Code) that edits code and runs commands for you. |
  275. | **Tool call** | One action by the agent: running a command (`Bash`), editing a file (`Edit`), querying an MCP server, and so on. |
  276. | **Session** | One conversation with Claude Code, from start to finish. groundhog counts per session. |
  277. | **Hook** | A small script Claude Code runs automatically after certain events. groundhog uses two: one after a tool fails, one after an edit. |
  278. | **Wall** | The same tool failing with the same error in one session, even if the command changed each time. |
  279. | **Signature** | The error with the parts that change on every try (paths, line numbers, hashes, ports) replaced by placeholders, so two tries of the same problem look identical. |
  280. | **Note** | The few lines groundhog adds next to the failed result. Only the agent reads them; they change what it does next. |
  281. | **Revert** | An edit that puts a file back the way it was before an earlier edit (A to B, then back to A). |
  282. | **Rework** | Rewriting the same lines again and again, with a failure in between each time. |
  283. | **Subagent** | A fresh helper agent with a clean memory. Handing it a short brief is often better than continuing in a long, cluttered conversation. |
  284. | **MCP tool** | A tool from an external server (database, browser, API) plugged into Claude Code. groundhog watches those too. |
  285. | **Context window** | The agent's working memory for the session. Repeated errors fill it with noise. |
  286. ## FAQ
  287. **Does it fix the bug for me?** No. It notices that the agent is stuck and tells it how to get unstuck: test a hypothesis, find the root cause, hand off, or ask you. The agent still does the fixing.
  288. **Does it change my code or my commands?** No. It never edits files, never blocks a command and never rewrites output. It only adds a short note.
  289. **How will I know it is working?** Most of the time you will not notice it, which is the point. When it fires, you will see the agent stop to state a hypothesis and run a check, or come to you with a short summary of what it tried. To see how often your sessions get stuck, run `/groundhog-report`.
  290. **What if the agent ignores the note?** It can. groundhog advises, it does not force. If the same wall comes back a third time, the note gets firmer and offers three exits. The [Evidence](#evidence) section explains why the savings are reported as a ceiling.
  291. **How do I turn it off or remove it?** Set `GROUNDHOG_DISABLE=1` to pause it, or run `claude plugin uninstall groundhog@groundhog` to remove it.
  292. **Does it cost tokens?** A few hundred per note. In the replay above that was about one note per hundred tool calls.
  293. **Will it nag me during normal work?** Only when the same tool fails with the same error twice in one session, an edit undoes an earlier one, or an edit loop shows up after a failure. Sessions without any of these never hear from it.
  294. **Does it work with subagents?** Yes. The hooks fire for subagent tool calls too, and they are counted under the session that reports them.
  295. **Windows?** Yes. CI runs on Linux, macOS and Windows.
  296. ## Development
  297. ```bash
  298. git clone https://github.com/Shiroe-95/groundhog
  299. cd groundhog
  300. node --test
  301. claude plugin validate . --strict
  302. ```
  303. To try your local copy in Claude Code: `claude --plugin-dir .`
  304. See [CONTRIBUTING.md](CONTRIBUTING.md) for the details.
  305. ## Author
  306. Built by **Wilson Vargas Martinez**, engineer. [LinkedIn](https://www.linkedin.com/in/wilsonvm09) · [GitHub](https://github.com/Shiroe-95)
  307. ## License
  308. [MIT](LICENSE). Use it, fork it, ship it.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.