Table of Contents

• Why agent-fix
• Features
• Quick Start
• Usage
  • CLI commands
  • Compatibility matrix
  • Issue catalog
  • Use it from your programs
  • MCP server (19 tools for any agent)
• 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
• 🤖 Every agent, registry-driven — an agent registry in catalog.json covers Claude Code, Codex, OpenCode, Hermes, Kimi Code, Pi, ZCode, Cursor, Gemini CLI, Aider, Qwen Code, Amp, Droid + any npm CLI; fix doctor checks every agent installed on your machine, not just the big four. 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, 19 tools) organized as a clear tree (registry → review gate → six domain groups + the DeepSeek Harness office), so Claude Code, OpenCode, Cursor, ZCode, Codex can call fix_doctor, net_diagnose, provider_setup, dsh_fix, … as native tools; 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 — deepseek-harness-broken diagnoses a broken dsh launcher (binary missing / Node too old / incomplete plugin bundles); dsh_diagnose + dsh_fix repair & verify it over MCP or CLI
• 🔐 Secret-safe by default — API keys / tokens are redacted from every output (config_audit, log_triage, 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 agent registry and which agents are installed	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 (19 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. It is organized as a tree — a registry declares the tools, a review gate validates every call, and six domain groups plus the DeepSeek Harness office execute:

Group	Tools
Agents	fix_agents, version_check, watchdog_status
Configs	config_audit, backup_configs, restore_configs
Providers	provider_setup, deepseek_setup
Network	net_diagnose (endpoint latency + proxy)
Diagnosis	fix_doctor, fix_check, fix_info, log_triage
Repair	fix_apply, self_heal, heal_hooks
Harness (DeepSeek)	dsh_diagnose, dsh_fix

Plus court_status — the toolbox map, callable as a tool. python mcp/smoke_test.py regresses every tool over the wire. Every tool redacts API keys / tokens in its output — see mcp/README.md security notes.

(The modules keep the Tang-court pinyin names — a small nod to the ancient 三省六部 system: court/shangshu/libu_personnel.py = agents, hubu.py = configs, libu_rites.py = providers, bingbu.py = network, xingbu.py = diagnosis, gongbu.py = repair, taipu.py = the DeepSeek Harness office. See mcp/README.md for the architecture.)

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

Then just talk to your agent: "run fix_doctor and tell me what's broken", "net_diagnose — is DeepSeek reachable?", "backup_configs before I upgrade", "deepseek_setup with key sk-…". Full docs: mcp/README.md.

How it works

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

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

1. Append an issue block to catalog.json (id, checks, fixes, verify, doc).
2. Add a matching fixes/<id>.md doc.
3. Validate: fix check <id>; test the repair with fix apply <id> --yes.
4. 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).

Related

• 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