agent-fix

August 30, 2026 · View on GitHub

agent-fix

One command heals broken AI coding agents. Claude Code, Codex, OpenCode, Hermes, Kimi Code, Pi, ZCode, Cursor — when the install or upgrade silently breaks them, fix apply <id> diagnoses, repairs, and verifies in a single command. No dependencies. Cross-platform.

English / 简体中文

🩺 It really looks like this

$ fix doctor
== npm-postinstall-skipped: npm postinstall skipped -> native binary missing
    [FAIL] opencode binary runs
          Error: postinstall script was not run
   -> BROKEN. Fix with: fix apply npm-postinstall-skipped --yes

$ fix apply npm-postinstall-skipped --yes
    [FIX ] Re-run opencode postinstall        → ok (12.4s)
    [FIX ] Re-run claude-code install script  → ok (1.1s)
    [VERIFY OK] opencode --version            → v1.18.10
    [VERIFY OK] claude --version              → 2.1.220 (Claude Code)
=> verified OK

$ fix doctor   # everything healthy? prints nothing
$ echo $?      # → 0

▶ Try it in 30 seconds — no install, no dependencies:

git clone https://github.com/qingzhuo-cn/agent-fix.git && cd agent-fix
./scripts/fix doctor   # or: powershell -File install\install.ps1 to install into your agents

Why agent-fix
Features
Quick Start
Usage
How it works
Extending the catalog
FAQ
Related
License

Why agent-fix

AI coding agents are installed, upgraded, and switched by all kinds of tooling — npm, GUI switchers (CC-Switch), version managers — and when that tooling misbehaves, every agent breaks in familiar ways:

opencode --version → "postinstall script was not run" (the classic ignore-scripts / --ignore-scripts trap, recurring on every upgrade)
claude --version → "native binary not installed"
CC-Switch says "installed · cannot run" while the terminal works fine
EBADENGINE, ETIMEDOUT, 401 Unauthorized, Not logged in …

Fixes for these are scattered across GitHub issues and chat logs. agent-fix collects them into one versioned, machine-readable catalog (catalog.json) plus human-readable docs (fixes/*.md), and ships a zero-dependency CLI (scripts/fix.py) that diagnoses, repairs, and verifies — on Windows, macOS, and Linux.

It was born from a real recurring incident: OpenCode and Claude Code broke five times in five days on one machine, always the same root cause, always a different manual command. This skill makes that repair one command: fix apply npm-postinstall-skipped --yes.

Features

🔧 10 issue classes, 1 command — fix doctor checks everything; fix apply <id> repairs and verifies
🤖 Only the agents you actually have — an agent registry in catalog.json powers detection; fix doctor checks every agent installed on your machine (Claude Code, Codex, OpenCode, Hermes, Kimi Code, Pi, ZCode, and any other we detect). fix agents lists only what you've installed — the tool never names, lists, or exposes install commands for agents that are not present on your machine. New agents = one line of data, no code
🖥️ Cross-platform — Windows (incl. Git Bash & WSL-aware), macOS, Linux
🧩 Skill + CLI + API — loadable as a skill by agents, callable from a terminal, or importable as a Python module
⚡ MCP server — a zero-dependency stdio MCP server (mcp/server.py, 14 generic verb tools + a review gate), so Claude Code, OpenCode, Cursor, ZCode, Codex can call doctor, check, apply, net, provider, … as native tools; the catalog's issue ids are the arguments, so new issues need no new tool code; python mcp/smoke_test.py regresses every tool
📦 Zero dependencies — pure Python 3.8+ stdlib
🔁 Watchdog-ready — fix auto checks and auto-repairs; non-zero exit on failure drops straight into cron/CI
💉 Self-heal on agent start — installers register startup hooks (Claude Code SessionStart, Codex [hooks] session_start, OpenCode plugin, Hermes cron watchdog) so every agent checks & repairs itself the moment it launches; fix selfheal prints nothing when healthy
🧪 Verified fixes — every fix ends with a real verification step, not just --version
🔌 DeepSeek Harness (dsh) repair — the deepseek-harness-broken issue diagnoses a broken dsh launcher (binary missing / Node too old / incomplete plugin bundles); the reinstall is a documented manual step — the tool diagnoses and verifies, it never installs an agent itself
🔐 Secret-safe by default — API keys / tokens are redacted from every output (audit, logs, diagnosis detail, proxy credentials); provider keys stay masked unless you pass show_key=true; config backups are chmod 600

Quick Start

git clone https://github.com/qingzhuo-cn/agent-fix.git
cd agent-fix

# 1) CLI — no install needed
./scripts/fix doctor

# 2) install the skill into your agents (Claude Code / OpenCode / Hermes / Codex hook)
./install/install.sh            # POSIX or Git Bash
powershell -File install\install.ps1   # Windows PowerShell

# 3) try it
fix list

Windows users: full check coverage requires Git Bash (the CLI auto-detects it and falls back to cmd.exe for npm/node/registry checks).

Usage

CLI commands

Command	What it does	Exit code
`fix list`	list every known issue	0
`fix agents`	list the agents installed on this machine	0
`fix check`	run all diagnostics (incl. per-agent binary checks)	0 healthy / 1 broken
`fix check <id>...`	run diagnostics for specific issues	0 / 1
`fix doctor`	alias for `fix check`	0 / 1
`fix apply <id> [--yes]`	apply fixes for one issue, then verify	0 verified
`fix auto`	check all → auto-apply fixes for broken ones (watchdog)	0 all fixed
`fix info <id>`	print the matching doc from `fixes/`	0
`fix --json` / `fix check --json`	machine-readable output for programs	—

Typical session:

$ fix doctor
== npm-postinstall-skipped: npm postinstall skipped -> native binary missing
    [FAIL] opencode binary runs
          Error: postinstall script was not run
   -> BROKEN. Fix with: fix apply npm-postinstall-skipped --yes

$ fix apply npm-postinstall-skipped --yes
    [FIX ] Re-run opencode postinstall        → ok (12.4s)
    [FIX ] Re-run claude-code install script  → ok (1.1s)
    [VERIFY OK] opencode --version            → v1.18.10
    [VERIFY OK] claude --version              → 2.1.220 (Claude Code)
=> verified OK

Compatibility matrix

Agent	Skill format	Install path	Auto-loaded?
Hermes	`SKILL.md`	`~/.local/share/hermes/skills/agent-fix/` (Win: `%LOCALAPPDATA%\hermes\skills\agent-fix\`)	✅
Claude Code	`SKILL.md`	`~/.claude/skills/agent-fix/`	✅
Codex CLI	`SKILL.md` + `AGENTS.md`	`~/.codex/skills/agent-fix/`	✅
OpenCode	`SKILL.md` + `AGENTS.md`	`~/.config/opencode/skills/agent-fix/`	✅
Kimi Code	`SKILL.md` (auto-discovered)	`~/.kimi-code/skills/agent-fix/`	✅
Pi	`SKILL.md`	`~/.pi/agent/skills/agent-fix/`	✅
ZCode & shared	`SKILL.md`	`~/.agents/skills/agent-fix/`	✅
Cursor, others	`AGENTS.md`	repo root	✅
Any npm CLI	`fix` CLI	`~/bin/fix`	n/a

All 13 registry agents (incl. Gemini CLI, Aider, Qwen Code, Amp, Droid) are detected and health-checked by fix doctor even when the skill itself isn't installed — see fixes/agent-matrix.md.

Issue catalog

ID	Problem	Affected agents	Doc
`agent-broken-generic`	ANY detected agent's binary fails (dynamic check, registry-driven)	all	doc
`npm-postinstall-skipped`	npm `ignore-scripts`/`--ignore-scripts` skips postinstall → native binary missing	claude-code, opencode, codex, pi, any npm CLI	doc
`gui-path-blind`	GUI apps (CC-Switch, ZCode Desktop etc.) can't see agent binaries (registry PATH)	all agents, CC-Switch	doc
`node-version-too-old`	Node too old for the agent's engines → startup crash	claude-code, codex, opencode, pi	doc
`npm-registry-mirror`	npm install/upgrade slow or unreachable	all npm agents	doc
`agent-auth-broken`	"Not logged in" / expired OAuth / missing key	claude-code, codex, kimi-code, pi	doc
`provider-config`	no provider configured — set key/base URL/model for ANY provider (DeepSeek/OpenAI/Anthropic/Google/Ollama/...)	all	doc
`net-connectivity`	agent API endpoints unreachable (TCP/DNS/proxy layer under all agents)	all (network layer)	doc
`opencode-mcp-schema`	`opencode.json` MCP entry invalid (`type: stdio` / string `command` / missing `enabled`) → `ConfigInvalidError`	opencode	doc
`deepseek-harness-broken`	DeepSeek Harness (`dsh`) won't boot — binary missing / Node too old / incomplete plugin bundles	dsh	doc

Per-agent deep dives: Kimi Code · Pi · ZCode

Use it from your programs

import sys
sys.path.insert(0, "/path/to/agent-fix-skill/scripts")
from fix import load_catalog, check_issue, apply_issue, auto_fix

catalog = load_catalog()
issue = next(i for i in catalog["issues"] if i["id"] == "npm-postinstall-skipped")

state = check_issue(issue, quiet=True)          # diagnose
print("broken" if state["broken"] else "healthy")

outcome = apply_issue(issue, yes=True, quiet=True)  # repair + verify
print("verified:", outcome["verified"])

Or call it as a subprocess with --json:

import json, subprocess
out = subprocess.run(["fix", "check", "--json"], capture_output=True, text=True)
report = json.loads(out.stdout)

MCP server (14 tools for any agent)

The same toolbox is exposed as an MCP server, so any MCP-capable agent (Claude Code, OpenCode, Cursor, ZCode, Codex) can call it as native tools. Fourteen generic verb tools, one review gate (type coercion, veto, error wrapping), one shared secret mask:

Tool	Purpose
`doctor` / `check` / `apply` / `info`	diagnose everything / one issue / repair one issue (`confirm=true` to execute) / read the doc
`agents` / `versions`	what's installed / installed vs latest (GUI apps never probed)
`net` / `logs`	endpoint connectivity + proxy / recent ERROR lines
`audit` / `backup` / `restore`	config parse errors + leaked keys / snapshot / restore (`confirm=true`)
`provider`	per-agent snippets for ANY provider (keys masked)
`hooks` / `self_heal`	startup-hook management / the self-heal pipeline (`apply=true` to fix)

The catalog's issue ids are the arguments of check/apply/info, so new issues need no new tool code. Mutating tools are dry-run by default. python mcp/smoke_test.py regresses every tool over the wire.

python scripts/fix.py mcp register       # register with every installed agent
claude mcp list | grep agent-fix         # verify: ✔ Connected

Then just talk to your agent: "run doctor and tell me what's broken", "net — is DeepSeek reachable?", "backup before I upgrade", "provider with provider=deepseek and key sk-…". Full docs: mcp/README.md.

How it works

                ┌─────────────────────────────┐
                │       catalog.json          │  single source of truth
                │  agents · checks · fixes    │  (registry + issue definitions)
                └──────────────┬──────────────┘
                               │
        ┌──────────────────────┬───────────────────────┬───────────────────┬──────────────┐
        ▼                      ▼                       ▼                   ▼
  fixes/*.md            agentfix/ + scripts/fix.py   SKILL.md / AGENTS.md    mcp/server.py
  human & agent         CLI + Python API             agent-side loaders      MCP server — 14 tools
  knowledge base        (stdlib only)                (Hermes/Claude/OpenCode) registry → gate → engine

Each issue in catalog.json is data — checks (diagnostics), fixes (repair commands, with optional platform gating), and verify (post-fix confirmation). The CLI is a thin engine over that data, so adding an issue never requires code changes. The same content is mirrored in fixes/*.md for humans and agents that prefer prose.

Extending the catalog

Append an issue block to catalog.json (id, checks, fixes, verify, doc).
Add a matching fixes/<id>.md doc.
Validate: fix check <id>; test the repair with fix apply <id> --yes.
Open a PR.

FAQ

Q: Why does OpenCode keep breaking after every upgrade? A: The npm install/upgrade skipped its postinstall script (see npm-postinstall.md). Fix it once with fix apply npm-postinstall-skipped --yes, then set up the watchdog: 0 9 * * * cd /path/to/agent-fix-skill && ./scripts/fix auto >> fix.log 2>&1.

Q: CC-Switch says "installed · cannot run" but the terminal works. A: GUI apps don't inherit your shell PATH — they read the Windows registry PATH. Run fix apply gui-path-blind --yes, then restart the GUI app. See gui-path.md.

Q: Can I use this with DeepSeek models? A: Yes — deepseek-provider shows exactly how to point Claude Code (ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic), Codex/OpenCode (OPENAI_BASE_URL=https://api.deepseek.com), and Hermes at the DeepSeek API. See deepseek-provider.md.

Q: Does it need admin rights? A: No. Everything is user-level (config files, user PATH, per-user npm global).

Q: Dependencies? A: None. scripts/fix.py is pure Python 3.8+ stdlib. Bash wrapper needs bash (POSIX or Git Bash on Windows).

CC-Switch — the Claude/Codex/OpenCode provider switcher whose detection logic motivated the gui-path-blind doc
nvm-windows / fnm — recommended Node version managers

License

MIT