Goldfish

7 seconds is just about right.

Agentic coding leaves resource debt: duplicate MCP servers, orphaned browsers, swollen transcripts, stale worktrees, and diffs nobody meant to keep.

Goldfish checks after the tool call, off the critical path. When the evidence matters, it hands a short brief back to the agent. Two consecutive critical checks pause mutating work until the agent verifies ownership, cleans up the smallest safe target, and rechecks.

It never kills a process or deletes a file on its own.

Install

Goldfish hooks require python3 3.10+ on PATH. Verify it before installing:

python3 --version

Claude Code:

/plugin marketplace add hanzw/goldfish
/plugin install goldfish@goldfish

Codex:

codex plugin marketplace add hanzw/goldfish
codex plugin add goldfish@goldfish

Current Codex releases expose the Skill from a plugin but do not run plugin-bundled hooks. For automatic sampling and gating, install the same script as a small CLI, then let the existing owner of the Codex hook file register goldfish hook for PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, SubagentStart, and SubagentStop:

uv tool install .          # or: pipx install .
goldfish doctor

If a versioned harness already owns that file, add Goldfish through its installer. Do not create a second config writer.

Skill-only install for other Agent Skills clients:

npx skills add hanzw/goldfish --skill goldfish

This installs manual triage only. Automatic sampling and gating require the client's native pre/post hooks.

From a repository clone, run it directly on macOS or Linux:

python3 skills/goldfish/scripts/goldfish.py doctor
python3 skills/goldfish/scripts/goldfish.py check

check returns 0 for ok/warn and 2 for critical; exit 2 is an alert, not a crash.

What it watches

• Runtime: system pressure, agent process-tree RSS, duplicate helpers, agent-related orphans.
• Context: transcript size as a cheap signal for context debt.
• Workspace: dirty-file count, diff growth, and prunable worktree records.
• Control: a fresh, project-scoped state file with hysteresis, expiry, snooze, and acknowledgement.
• Lifecycle: tool and subagent starts that never receive their matching completion event.

Goldfish does not guess that code is dead from size alone. Workspace growth tells the agent when to run that repository's own linter, dependency graph, or dead-code tool.

The seven-second probe budget is not an intentional delay. Goldfish self-detaches after post events instead of relying on client-side async support; the pre-hook reads cached state and normally finishes in milliseconds. A stalled kernel or filesystem call can still overrun the CLI budget.

How the gate works

1. A post hook writes a compact evidence snapshot.
2. A prompt hook gives that evidence to the current agent.
3. After two consecutive critical snapshots, mutating tools pause. Read-only diagnosis still works.
4. The agent preserves dirty work, verifies exact targets, applies a reversible fix, then runs check and ack.

Use snooze 10 for an explicit escape hatch, capped at 60 minutes. Set GOLDFISH_MODE=observe for alerts without gating or GOLDFISH_MODE=off to disable it. A project .goldfish.json may only lower numeric thresholds within safe bounds; trusted GOLDFISH_* environment values may raise them. No custom shell probes are executed.

Stalled tools and subagents

Goldfish hashes a native tool/subagent ID at start and removes it only on the matching success, failure, or stop event. No completion event for two minutes is a warning; ten minutes is critical and pauses new mutations at the next hook boundary. Override those trusted-runtime defaults with GOLDFISH_WARN_STALLED_SECONDS and GOLDFISH_CRITICAL_STALLED_SECONDS.

This is lifecycle evidence, not proof that a process is deadlocked. If the current host is blocked, interrupt it normally; the next prompt or session reports the unfinished operation. Goldfish does not kill it. Runtimes that expose a child PID or process group should still enforce their own timeout and terminate-then-kill policy.

Compatibility

Client	Skill	Background sample	Prompt brief	Mutation gate
Claude Code 2.1+	yes	yes	yes	yes
Codex 0.146+ plugin only	yes	direct hook required	direct hook required	direct hook required
Agent Skills clients	yes	adapter required	manual	adapter required
Any shell agent	manual	cron/native hook	manual	wrapper policy

Validated locally against Claude Code 2.1.233 and Codex 0.147.0. Hook APIs change; doctor plus the client debug log is the source of truth.

For other frameworks, pipe one normalized event object to hook:

{"event":"tool.execute.after","cwd":"/repo","tool_name":"shell","tool_input":{"command":"git status"},"transcript_path":"/optional/transcript.jsonl"}

Use tool.execute.before before tools and before_prompt before a new prompt. Unknown tools fail closed only while a critical gate is active. Post events always return after launching the bounded background sample.

Hook input is capped at 256 KiB and probe output at 2 MiB per stream. Oversized tool responses are not retained; lifecycle metadata is recovered when present and truncation is reported.

Uninstall and recovery

# Claude Code
/plugin uninstall goldfish@goldfish

codex plugin remove goldfish@goldfish
npx skills remove goldfish

Uninstalling leaves the mode-0600 state snapshot in ${XDG_STATE_HOME:-~/.local/state}/goldfish for diagnosis or reinstall continuity. If a gate is active, use the absolute Python command printed in the alert to run report, snooze 10, or ack; pyenv/asdf shims are not required for that escape path.

ack also clears lifecycle records whose host crashed before sending a completion event, then performs a fresh resource scan. It still refuses to clear the gate while current resource evidence remains critical.

Safety and privacy

Goldfish records fixed helper signatures, counts, RSS, and bounded PID/elapsed-time pairs so the agent can detect PID reuse before cleanup. It does not persist raw command lines, prompts, tool input, environment variables, or secrets. State is written atomically with mode 0600 under ${XDG_STATE_HOME:-~/.local/state}/goldfish.

The gate deliberately refuses broad cleanup. Unknown ownership stays unknown.

Why this shape

The recurring failures are broader than one client: leaked process trees, workspace residue, context growth, and cleanup without enough evidence. Container limits and upstream lifecycle fixes help specific runtimes; Goldfish adds the missing cross-agent feedback loop.

See the linked reports for concrete examples: Codex MCP stacks reaching 37 GB, a 13.6 GB Playwright regression, Claude temporary-file accumulation, and stale worktree cleanup problems.

MIT.