claudecode-harness

Production-grade Claude Code configuration — hooks, rules, agents, and MCP templates. One command to go from vanilla Claude Code to a fully loaded development environment.

Why

Claude Code out of the box is powerful, but raw. No quality gates on commits, no auto-formatting on edits, no security monitoring, no session memory between conversations, no specialized agents for code review or TDD. You set all of that up yourself — or you install this.

claudecode-harness packages a battle-tested, production configuration into a single install. It was extracted from a setup running 38 hooks, 36 agents, 77 rules across 13 languages, and 27 MCP server templates — used daily for real development work.

Before & After

| | Vanilla Claude Code | With claudecode-harness | |---|---|---| | Commit quality | Whatever you push | Pre-commit hooks block secrets, check formatting, enforce conventional commits | | Code review | Manual | Automatic — dedicated agents for security, code quality, and language-specific review | | Testing | Hope for the best | TDD agent enforces write-tests-first, 80% coverage minimum | | Session memory | Starts fresh every time | Neuromcp persistence — picks up where you left off | | MCP servers | Configure each one manually | 27 pre-configured templates, credentials via env vars | | Security | Trust the vibes | Pre-tool security monitoring, secret detection, config protection | | Multi-language | One language at a time | Rules for TypeScript, Python, Go, Rust, Java, Kotlin, Swift, PHP, Perl, C++, C# |

Quick Start

$ npx claudecode-harness

claudecode-harness v1.0.1

Preflight checks:
  ✓ Claude CLI found: 2.1.92
  ✓ Node.js 22.22.0 (>= 18.0.0 required)
  ✓ Docker is available
  ✓ Python found: Python 3.12.7

Which layers do you want to install?
  [x] core       Settings template, CLAUDE.md
  [x] hooks      34 hook scripts + shared libraries
  [x] rules      Coding standards (common + language-specific)
  [x] agents     36 specialized agent definitions
  [ ] mcp        27 MCP server templates + .env.example

Installing...
  ✓ hooks (34 files)
  ✓ rules (common, typescript, python)
  ✓ agents (36 files)
  ✓ hooks merged into settings.json
  ✓ CLAUDE.md (standard)
  ✓ 10 essential plugins installed

✓ Installation complete!

Next steps:
  1. Restart Claude Code
  2. Run: claudecode-harness doctor

What's Included

Hooks (38 scripts)

Hooks run automatically before and after tool use. They're the backbone of the quality system.

| Hook | What it does | |------|-------------| | Pre-commit quality | Blocks commits with secrets, debug statements, or missing tests | | Config protection | Prevents accidental modification of linter/formatter configs | | Security monitoring | Scans bash commands and file writes for dangerous patterns | | Session persistence | Saves work context to neuromcp database on session end | | Context injection | Restores previous session context on startup | | Cost tracking | Tracks API usage per session | | Desktop notifications | macOS notifications when long tasks complete | | Quality gates | Post-edit lint, format, and type checking | | MCP health checks | Probes MCP servers and caches status | | Telegram cleanup | Kills zombie Telegram plugin processes to prevent duplicate replies | | Session checkpoints | Saves periodic work-state snapshots for crash recovery | | Neuromcp auto-capture | Automatically captures context to neuromcp memory during work | | Task completion sound | Plays audio notification when long tasks finish | | ...and 25 more | Tmux reminders, git push checks, governance capture, error learning |

Rules (75 files, 13 languages)

Markdown-based coding standards that Claude reads and follows. Common rules apply everywhere, language-specific rules add framework patterns.

Common rules: coding style, testing (80% minimum coverage), security, git workflow, code review, design patterns, agent orchestration, hooks usage, performance optimization, development workflow.

Language rules available for: TypeScript, Python, Go, Rust, Java, Kotlin, Swift, PHP, Perl, C++, C#. Each includes: coding style, testing patterns, security practices, hook configuration, and design patterns.

Chinese translations included for all common rules.

Agents (36 specialists)

Pre-configured agent definitions that Claude dispatches for specific tasks.

| Category | Agents | |----------|--------| | Code review | code-reviewer, typescript-reviewer, python-reviewer, go-reviewer, rust-reviewer, kotlin-reviewer, java-reviewer, cpp-reviewer, flutter-reviewer | | Build fixing | build-error-resolver, go-build-resolver, java-build-resolver, kotlin-build-resolver, rust-build-resolver, cpp-build-resolver, pytorch-build-resolver | | Planning | planner, architect, tdd-guide | | Security | security-reviewer, healthcare-reviewer | | Operations | e2e-runner, doc-updater, refactor-cleaner, performance-optimizer | | Multi-agent | gan-planner, gan-generator, gan-evaluator, loop-operator | | Open source | opensource-forker, opensource-packager, opensource-sanitizer |

MCP Server Templates (27 servers)

Pre-configured templates for popular MCP servers. Credentials use environment variables — never hardcoded.

Included: GitHub, Exa, Playwright, Firecrawl, Supabase, Vercel, Railway, Cloudflare (4 servers), ClickHouse, Context7, fal.ai, Ollama, Browserbase, and more.

Each comes with a .env.example documenting the required credentials and where to get them.

Installation Options

Interactive (recommended)

npx claudecode-harness

Walks you through layer selection, language detection, and CLAUDE.md profile choice.

Selective layers

npx claudecode-harness --layers hooks,rules

Only install what you need. Available layers: core, hooks, rules, agents, mcp.

Full autonomous mode

npx claudecode-harness --profile jarvis

Installs everything with the "Jarvis" CLAUDE.md — full autonomous operation, broad permissions, multi-agent orchestration.

Standalone (without npx)

curl -fsSL https://raw.githubusercontent.com/AdelElo13/claude-harness/main/setup.sh | bash

CLI Commands

| Command | Description | |---------|-------------| | claudecode-harness | Interactive install (default) | | claudecode-harness doctor | Health check — verifies scripts, plugins, env vars | | claudecode-harness update | Update installed layers to latest version | | claudecode-harness uninstall | Remove installed layers (selective with --layers) | | claudecode-harness list | Show what's installed, versions, file counts | | claudecode-harness backup | Snapshot current ~/.claude configuration |

Flags

| Flag | Description | |------|-------------| | --layers=<list> | Comma-separated: core,hooks,rules,agents,mcp | | --profile=<name> | CLAUDE.md profile: minimal, standard, jarvis | | --claude-dir=<path> | Target directory (default: ~/.claude) | | --yes | Skip confirmation prompts |

CLAUDE.md Profiles

| Profile | Best for | What it sets up | |---------|----------|----------------| | minimal | Trying it out | Basic tool list, simple routing table | | standard | Daily development | Tool routing, hook overview, agent roster, MCP docs | | jarvis | Power users | Full autonomous persona, broad permissions, session continuity, multi-agent orchestration, Telegram remote control |

Plugin Tiers

Essential (auto-installed)

These 10 plugins are expected by the hooks, agents, and rules. Installed automatically.

superpowers context7 commit-commands code-review code-simplifier feature-dev pr-review-toolkit claude-md-management hookify plugin-dev

Recommended (install manually)

| Category | Plugins | Install | |----------|---------|---------| | Frontend | frontend-design, playground | claude plugin install frontend-design@claude-plugins-official | | Security | security-guidance | claude plugin install security-guidance@claude-plugins-official | | Languages | typescript-lsp, pyright-lsp, swift-lsp | claude plugin install typescript-lsp@claude-plugins-official | | Communication | telegram | claude plugin install telegram@claude-plugins-official | | Development | agent-sdk-dev, skill-creator, ralph-loop | claude plugin install agent-sdk-dev@claude-plugins-official | | Output styles | explanatory-output-style, learning-output-style | claude plugin install explanatory-output-style@claude-plugins-official |

How It Works

Install: merge, never overwrite

Your existing settings.json is backed up before any changes. Hooks are merged into your config — existing hooks are preserved, new ones are appended. Permissions are never touched.

Tracking: .harness-meta.json

The installer writes ~/.claude/.harness-meta.json tracking exactly what was installed — every file, every layer, every language. This enables clean updates, selective uninstall, and doctor validation.

Credentials: environment variables only

MCP server templates use empty credential fields that inherit from your shell environment. Add your API keys to ~/.zshenv (macOS) or ~/.bashrc (Linux). The .env.example file documents every variable.

Requirements

| Requirement | Required | Notes | |-------------|----------|-------| | Node.js >= 18 | Yes | Hooks are Node scripts | | Claude Code | Yes | The thing we're configuring | | Docker | No | Used by GitHub MCP server | | Python 3 | No | Used by security monitor hook |

Platform Support

| Platform | Status | |----------|--------| | macOS | Full support | | Linux | Full support | | WSL2 | Supported | | Windows (native) | Not supported |

FAQ

Will it overwrite my existing config? No. Your settings.json is backed up first. Hooks are merged (append-only), permissions are never touched. If a CLAUDE.md already exists, the template is saved as CLAUDE.md.harness so you can compare.

Can I uninstall cleanly? Yes. claudecode-harness uninstall removes all installed files and hooks. Your backup is preserved. Use --layers hooks for selective removal.

Where are credentials stored? Never in config files. All MCP servers read from environment variables. See .env.example after installing the MCP layer.

Can I install only specific layers? Yes. --layers=hooks,rules installs just those. The core layer is always included as a base.

How do I add a language later? Re-run npx claudecode-harness --layers=rules and select additional languages.

Does it work with existing Claude Code plugins? Yes. It installs alongside your existing setup. No conflicts.

How is this different from karpathy-skills?

karpathy-skills gives you 4 behavioral rules in a CLAUDE.md — think before coding, simplicity first, surgical changes, goal-driven execution.

claudecode-harness gives you 38 automated hooks that enforce those rules, plus 36 specialized agents and 77 language-specific standards.

| | karpathy-skills | claudecode-harness | |---|---|---| | Approach | Guidelines (read and follow) | Automation (enforced on every action) | | "Think before coding" | A rule you hope Claude follows | Planner agent + Plan Mode that structures every task | | "Simplicity first" | Advice | Post-edit lint hooks + code-reviewer agent that flags overcomplication | | "Surgical changes" | Advice | Config protection hooks + diff-scoped review agents | | "Goal-driven execution" | A suggested pattern | TDD agent enforces write-tests-first + 80% coverage minimum | | Scope | 1 CLAUDE.md file | 38 hooks, 36 agents, 77 rules, 27 MCP templates |

Rules are nice. Enforcement is better.

Contributing

See CONTRIBUTING.md for how to add hooks, rules, agents, or MCP templates.

License

MIT — see LICENSE.