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

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

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

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:

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