{
  "markdown": "> For the Japanese version, see [README.ja.md](README.ja.md).\n> Part of the [neko-HQ](https://github.com/aliksir/neko-hq) ecosystem.\n\n# neko-harness-doctor\n\n> A free, open-source CLI tool that automatically diagnoses your Claude Code harness using 25 anti-pattern indicators.\n\n![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)\n![Node.js 18+](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)\n![Dependencies: 0](https://img.shields.io/badge/dependencies-0-blue.svg)\n\n## What is this?\n\nAutomatically diagnoses your Claude Code environment (`CLAUDE.md` / `settings.json` / `.mcp.json` / `hooks/` / `skills/` / `memory/` / `MCP` / `workflow`) against **25 anti-pattern indicators**, outputting an **S-to-E grade** and **prioritized Quick Wins (improvement suggestions)**.\n\n## Why do you need this?\n\nMuch of the inconsistency in Claude Code output quality across sessions comes from **structural flaws in harness design**:\n\n- `CLAUDE.md` has grown too large, degrading KV-Cache efficiency\n- Important rules are buried in the middle and Claude misses them (Lost in the Middle)\n- `bypassPermissions` is enabled, silently allowing dangerous operations\n- Skill descriptions are too short for Claude to select correctly\n- MCP server versions are not pinned\n\nChecking all of these manually is a huge effort, but this single tool covers everything in 5-15 seconds.\n\n## Features\n\n- **25 Anti-Pattern Indicators**: Cross-cutting diagnosis across 7 categories (CLAUDE.md structure / settings / hooks / skills / memory / MCP / workflow)\n- **S-to-E Grade Evaluation**: Hybrid grading (PASS rate + Critical instant-demotion, up to 3 tiers)\n- **Quick Wins**: Prioritized improvement suggestions (top 5 by default)\n- **Interactive Fix Flow**: `--fix-mode propose` outputs fix proposals as JSON. Claude Code presents them for user approval and applies via the Edit tool -- a fully transparent workflow\n- **Read-only**: The CLI itself **never modifies** the target. Fixes are always applied after user approval\n- **Deterministic**: No LLM calls -- uses grep / AST / JSON parsing for **deterministic** results\n- **i18n**: Japanese by default, switch to English with `--lang en`\n- **Zero Dependencies**: Only requires Node.js 18+, ready to run after `npm install`\n\n## Installation\n\n### npm (recommended -- standalone CLI)\n\n```bash\nnpm install -g @aliksir/neko-harness-doctor\n```\n\n### As a Claude Code Plugin\n\nThis repository also works as a Claude Code plugin. When enabled as a plugin:\n\n- `bin/neko-harness-doctor` is automatically added to the Bash tool's PATH (callable as a bare command)\n- The bundled skill responds to the `/neko-harness-doctor` slash command and natural language triggers like \"diagnose my harness\"\n- Claude can automatically run diagnosis, present Quick Wins, and execute the interactive fix flow\n\n**Marketplace (pending approval)**:\n\n```bash\n# Available after approval\nclaude plugin install neko-harness-doctor\n```\n\n**Local testing (pre-approval / building from source)**:\n\n```bash\ngit clone https://github.com/aliksir/neko-harness-doctor.git\nclaude --plugin-dir ./neko-harness-doctor\n# /neko-harness-doctor becomes available in the session\n```\n\nPlugin structure:\n\n```\nneko-harness-doctor/\n├── .claude-plugin/plugin.json      # Manifest\n├── bin/neko-harness-doctor         # Added to PATH when plugin is active\n├── skills/neko-harness-doctor/\n│   └── SKILL.md                    # Claude auto-trigger + /name shortcut\n└── src/                            # 25 indicator logic\n```\n\n### GitHub clone (run the raw script)\n\n```bash\ngit clone https://github.com/aliksir/neko-harness-doctor.git\ncd neko-harness-doctor\nnode bin/neko-harness-doctor --help\n```\n\n## Quick Start\n\n```bash\n# Diagnose ~/.claude/\nneko-harness-doctor\n\n# Diagnose a specific directory\nneko-harness-doctor --target ~/.claude --workspace ~/work/myproject\n\n# Filter by category\nneko-harness-doctor --category claude-md\n\n# JSON output\nneko-harness-doctor --format json\n\n# Switch to English\nneko-harness-doctor --lang en\n\n# Fix proposal mode (when called from Claude Code)\nneko-harness-doctor --fix-mode propose --format json\n```\n\n## Example Output\n\n```markdown\n# neko-harness-doctor Diagnosis Report\n\n- **Target**: ~/.claude\n- **Overall Grade**: C (base B, demoted 1 tier due to 1 Critical violation)\n- **PASS Rate**: 17/25 (68.0%)\n- **Critical Violations**: 1\n- **Timestamp**: 2026-04-11T21:48:00.000Z\n\n## Scores by Category\n\n| Category | PASS/Total | Critical | Major | Minor |\n|---|---|---|---|---|\n| CLAUDE.md Structure | 2/5 | 1 | 1 | 1 |\n| settings.json | 4/4 | 0 | 0 | 0 |\n| Hooks | 1/3 | 0 | 2 | 0 |\n| Skills | 1/4 | 0 | 2 | 1 |\n| Memory | 3/3 | 0 | 0 | 0 |\n| MCP | 3/3 | 0 | 0 | 0 |\n| Workflow | 3/3 | 0 | 0 | 0 |\n\n## Detected Issues\n\n### [CRITICAL] IND-03: critical-rules-not-in-first-third\n- **Location**: ~/.claude/CLAUDE.md\n- **Violation**: Earliest critical-rule heading at position=80.2% (outside first third)\n- **Reference**: Liu et al. 2023 \"Lost in the Middle\" (arXiv:2307.03172)\n- **Remediation**: Move critical rules to the first third (position 0 to 0.3) to avoid Lost-in-the-Middle\n- **Auto-fixable**: Manual only\n\n## Quick Wins (Prioritized)\n\n1. **[CRITICAL]** IND-03 critical-rules-not-in-first-third — Move critical rules to the first third\n2. **[MAJOR]** IND-05 volatile-elements-not-at-tail — Consolidate volatile elements at the tail\n3. **[MAJOR]** IND-10 hook-missing-error-handling — Add try/catch to all hook scripts\n...\n```\n\n## Interactive Fix Flow (Claude Code Integration)\n\nUsing `--fix-mode propose` outputs fix proposals as JSON. Claude Code reads these, asks the user for approval, then applies fixes using the `Edit` tool:\n\n```json\n[\n  {\n    \"indicator\": \"IND-06\",\n    \"autoFixable\": true,\n    \"fixStrategy\": \"remove-bypass-permissions\",\n    \"severity\": \"critical\",\n    \"target\": \"/path/to/settings.json\",\n    \"description\": \"\\\"bypassPermissions\\\": true is set\",\n    \"evidence\": \"Principle of least privilege\",\n    \"diff\": {\n      \"before\": \"{ \\\"bypassPermissions\\\": true, ... }\",\n      \"after\": \"{ ... }\"\n    }\n  },\n  {\n    \"indicator\": \"IND-03\",\n    \"autoFixable\": false,\n    \"severity\": \"critical\",\n    \"target\": \"/path/to/CLAUDE.md\",\n    \"description\": \"...\",\n    \"manualSteps\": [\n      \"Move critical rules to the first third (position 0 to 0.3)\",\n      \"Review CLAUDE.md and refactor per the remediation guidance.\"\n    ]\n  }\n]\n```\n\n**Principle**: The CLI only proposes. Actual fixes are applied by Claude Code using the `Edit` tool after user approval, making everything fully transparent with diff preview.\n\n## All 25 Indicators\n\n| Category | Count | Key Areas |\n|---|---|---|\n| CLAUDE.md Structure | 5 | Line count bloat / Prefix instability / Lost in the Middle / Duplicate sections / Volatile elements at tail |\n| settings.json | 4 | bypassPermissions / Auto-accept all / Excessive permissions / No hooks configured |\n| Hooks | 3 | Missing error handling / Side-effect risk / PostToolUse overuse |\n| Skills | 4 | Insufficient description / Ambiguous trigger / No risk setting / Namespace collision |\n| Memory | 3 | MEMORY.md bloat / Scattered lessons / Broken pointers |\n| MCP | 3 | Unpinned versions / Insufficient descriptions / Unverified supply chain |\n| Workflow | 3 | Missing gate definitions / Poor plan management / Missing review-protocol |\n\nSee [docs/indicators.md](./docs/indicators.md) for details.\n\n## Grading Specification\n\nThe base grade is determined by PASS rate, with 1-tier demotion per Critical violation (max 3 tiers).\n\n| Grade | PASS Rate |\n|---|---|\n| S | >= 90% |\n| A | >= 75% |\n| B | >= 60% |\n| C | >= 45% |\n| D | >= 30% |\n| E | < 30% |\n\nSee [docs/grading.md](./docs/grading.md) for details.\n\n## Configuration\n\nExtend the MCP publisher allowlist and other settings via `~/.neko-harness-doctor/config.json`:\n\n```json\n{\n  \"mcp\": {\n    \"publisherAllowlist\": [\n      \"@anthropic-ai\",\n      \"@my-org\",\n      \"@trusted-vendor\"\n    ]\n  }\n}\n```\n\nSee [docs/configuration.md](./docs/configuration.md) for details.\n\n## Options\n\n```\n--target <path>       Target directory to diagnose (default: ~/.claude/)\n--workspace <path>    Working directory to look for plans/checklist/rules\n--format <fmt>        Output format: json|markdown (default: markdown)\n--category <name>     Diagnose a specific category only\n--severity <level>    Minimum severity: critical|major|minor (default: minor)\n--top <n>             Number of top Quick Wins to display (default: 5)\n--fix-mode <mode>     Fix proposal mode: off|propose (default: off)\n--lang <lang>         Output language: ja|en (default: ja)\n--quiet               Show violations only\n--help                Show help\n\nEnvironment variables:\n  NEKO_HARNESS_WORKSPACE  Fallback for --workspace\n\nExit codes:\n  0 - Diagnosis completed\n  1 - Target not found\n  2 - Internal error\n```\n\n## Comparison with Similar Tools\n\n| Tool | Scope | Relationship to neko-harness-doctor |\n|---|---|---|\n| `skill-security-check` | Security audit for individual Skills | Complementary (this tool only does cross-cutting Skill structure audits) |\n| `cc-skill-security-review` | Security review of code changes | Complementary (this tool audits deployed configuration) |\n| `analyze-permissions` | settings.json permission analysis | Complementary (this tool diagnoses across 8 broader areas) |\n\n## FAQ\n\n**Q: Does it call an LLM?**\nA: No. All checks are deterministic using grep / AST / JSON parsing. Same input always produces the same output. Ideal for CI integration.\n\n**Q: Does it modify my files?**\nA: **The CLI itself never modifies anything.** Fixes go as far as outputting proposal JSON via `--fix-mode propose`. Actual changes are applied by Claude Code using the `Edit` tool (after user approval).\n\n**Q: Any dependencies?**\nA: Zero runtime dependencies. Runs on Node.js 18+ stdlib only.\n\n**Q: Can I add or customize indicators?**\nA: As of v0.2.0, only the built-in 25 indicators are available. User-defined indicators are planned for the future. Thresholds like the publisher allowlist can be extended via `~/.neko-harness-doctor/config.json`.\n\n## License\n\n[MIT](./LICENSE)\n\n## Acknowledgments\n\n- **Liu et al. 2023** \"Lost in the Middle\" (arXiv:2307.03172) -- basis for IND-03\n- **Anthropic Prompt Caching Guide** -- basis for IND-01/02/05\n- **OpenSSF Secure Supply Chain Best Practices** -- basis for IND-20/22\n- **IEEE peer review standard / Four Eyes Principle** -- basis for IND-25\n\n## Roadmap\n\n- [x] **v0.1.0** -- Initial 25 indicators, i18n, fix-mode=propose\n- [x] **v0.2.0** -- Shell hook support (IND-10), `hd-ignore` inline exclusion, external skill exclusion (`--skip-external`), CRLF parse bug fix, CI/test suite\n- [ ] **v0.3.0** -- ESLint integration, user-defined indicators, live MCP tool description measurement (dynamic fetch at startup)\n- [ ] **v0.4.0** -- IND-22 postinstall live measurement integration\n- [ ] **v1.0.0** -- Stable release\n",
  "bytes": 10835,
  "sha": "a278aa3bd034bbc4994726a220510971180c9f6d2a89f5bf7931936e8eee70d7",
  "repo_slug": "aliksir/neko-harness-doctor",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_aliksir_neko_harness_doctor_neko_harness_28972051/readme"
}