jrobic-cc-harness-setup-example

cc-harness-setup-example

Onboard a developer onto a recommended Claude Code configuration in one command.

This repository is a minimal, generic, production-ready example of a Claude Code harness: a deny list, a team context import, and the tooling to install and maintain them — all shipped as a Claude Code marketplace plugin.

---

What this is

A harness covers three distinct layers. They are kept separate because they have different trust properties:

Layer	What	Trust
Enforcement	permissions.deny rules in settings.json	Hard — the agent cannot read around these
Tooling	Commands, skills, hooks, MCP servers (shipped as a plugin)	Portable, pluginnable
Context	CLAUDE.md import — advisory guidance for the agent	Soft — can be overridden

Key invariant: deny ≠ context. A hard prohibition belongs in the deny list, never in CLAUDE.md. The deny list is the enforcement layer; CLAUDE.md is guidance the agent can be talked out of.

The engine (harness-setup.ts) performs the two writes that the plugin format cannot express by itself — the deny merge and the context import — with your explicit confirmation, and backs up every file it touches.

---

Install

Public GitHub marketplace (recommended)

Register this repo as a marketplace, then install the plugin:

claude plugin marketplace add jrobic/cc-harness-setup-example
claude plugin install jrobic-cc-harness-setup-example

Clone & go

This repository ships a .claude/settings.json that declares itself as a known marketplace. Trust the folder and Claude Code will prompt you to register and install automatically.

git clone https://github.com/jrobic/cc-harness-setup-example
cd cc-harness-setup-example
claude  # trust the folder → follow the marketplace prompt

Private git host (generic HTTPS)

For a privately hosted fork, use the full HTTPS URL. Your existing git credential helper (e.g. the macOS keychain, a token stored via git credential, or SSH key forwarding) handles authentication — no special setup needed:

claude plugin marketplace add https://git.example.com/your-org/cc-harness-setup-example.git
claude plugin install jrobic-cc-harness-setup-example

If your private server requires a token, configure it once via git's credential helper rather than embedding it in the URL:

git config --global credential.helper store   # or 'osxkeychain', 'manager', etc.

---

Run the harness setup

Once the plugin is installed, run:

/harness-setup

The command will:

1. Run check — audit your ~/.claude/settings.json and ~/.claude/CLAUDE.md.
2. Present any missing deny rules and the absent context import (if any).
3. Ask for your explicit confirmation before writing anything.
4. Run apply — merge the deny rules, copy the context file, and ensure exactly one managed import block in CLAUDE.md.
5. Report what changed and confirm that .bak-<timestamp> backups were created.

Nothing is written without your agreement. Every modified file gets a backup.

---

Tooling layer: MCP servers + CLIs

The plugin's .mcp.json declares two MCP servers, and the tooling layer mixes mechanisms by what fits the target:

• example → a live MCP, no credentials. The official MCP reference server (@modelcontextprotocol/server-everything), stdio over npx, no auth. It connects out of the box, so /mcp visibly shows a working MCP with example tools — a placeholder to demonstrate the layer; swap it for your real servers.
• datadog → a realistic example (needs setup). The official Datadog MCP server (HTTP, OAuth at runtime — no key committed). The endpoint is org/site-specific, left as ${DATADOG_MCP_URL}; unset, it silently fails and does not appear in /mcp (expected — it's a needs-setup placeholder). Easiest path: /plugin install datadog@claude-plugins-official then /ddsetup.
• GitLab & AWS → CLI + skill (planned). glab and the aws CLI already cover the ground, so these will be wrapped as skills over the CLI rather than MCP servers (not built in this phase).

See docs/how-it-works.md §5 for the rationale (when to use an MCP server vs a CLI-backed skill) and setup details.

---

Soft vs hardened mode

The engine ships in two modes, controlled by a build knob: