QuietHarness – A lightweight safety‑layer for AI‑coding agents

What it is – QuietHarness is a small, portable set of configuration files and helper scripts that add a “safety harness” around AI‑driven coding assistants such as Claude Code, Codex, or Cursor. The harness does not change the model, call any external services, or require API keys. Instead it installs a shared Core (≈1.6 KB) that enforces a handful of reliability rules:

1. Don’t overwrite unrelated files – the agent must first check the current state of the repository.
2. Run tests before declaring success.
3. Treat risky actions (e.g., credential changes, production deployments) as a confirmation step.
4. Record concrete evidence of what was changed so the result can be verified later.

The same core can be used with any of the three supported agents; the installer writes the appropriate template file for the chosen tool (e.g., AGENTS.md for Claude Code/Codex or quiet‑harness.mdc for Cursor).

---

Who might benefit?

• Developers who already rely on an AI coding assistant and have run into problems such as accidental file overwrites, missing test runs, or un‑reviewed destructive actions.
• Teams that switch between Claude Code, Codex, and Cursor and want a consistent set of safety checks without re‑creating the configuration each time.
• Anyone looking for a dry‑run‑first workflow that can be rolled back (backups are automatically created with timestamps).

---

Quick start (isolated demo)

# clone and enter the repo
git clone https://github.com/runesleo/claude-code-workflow.git
cd claude-code-workflow

# run an inventory check (sanity‑check script)
./scripts/inventory.sh

# create a temporary sandbox for the demo
DEMO=$(mktemp -d /tmp/quiet‑harness‑demo.XXXXXX)
./examples/first-success/setup.sh "$DEMO"

Choose one of the three agents and run the installer in dry‑run mode, then apply:

# Claude Code example
./scripts/install.sh --dry-run --claude-project "$DEMO"
./scripts/install.sh --apply   --claude-project "$DEMO"

The installer writes the harness files into the sandbox (AGENTS.md, CLAUDE.md, or the Cursor rule file) and reports what it would back‑up.

---

How it works under the hood

Layer	What it contains	Size
Shared Core	templates/shared/AGENTS.md – the universal safety rules	1 604 B
Claude Code adapter	templates/claude/CLAUDE.md – thin wrapper that points to the core	168 B
Cursor rule	templates/cursor/quiet‑harness.mdc – Markdown‑compatible rule file	546 B

Only one of these files is loaded by the chosen agent; the others stay dormant. The core defines four behavioural categories:

1. Direct request execution – the agent proceeds only after the harness confirms the request.
2. Visibility checks – the agent must explicitly read any file, webpage, or history before claiming it’s been examined.
3. Risk‑based validation – after a file change the harness asks the model to verify the modification against a risk profile.
4. Confirmation for irreversible actions – any operation that could affect credentials, production, or finances requires an explicit user confirmation step.

---

Optional experimental labs

The repository also ships a few labs that showcase how the harness can be extended:

• Attention Inbox – filters out trivial waiting_for_user messages and surfaces only real decision points.
• Chat Export – normalises local chat logs from Claude Code, Codex, Cursor, and Grok Bot into a single Markdown format.
• Session Hooks – tiny hooks that remind you to rename a thread, add a closing checklist line, or de‑duplicate pending decisions.
• OPC Company Layer – an experimental governance layer for multi‑owner/worker hand‑off (not required for the basic harness).

These labs are optional and live under labs/.

---

Installation & rollback

• The installer creates a timestamped backup (.bak‑ai‑workflow‑*) before overwriting any existing file.
• --dry-run shows exactly what would be written; --apply performs the changes.
• A --undo‑style rollback is possible by restoring the backup and removing the newly created file (see MIGRATION‑v3.md#回滚).
• User‑level installs affect ~/AGENTS.md (Claude) or $CODEX_HOME/AGENTS.md (Codex). Project‑level installs write into the target directory you pass with --*‑project.

---

Validation & testing

Running ./scripts/verify.sh checks:

• Shell syntax and isolation of the install process.
• Correct handling of dry‑run, multi‑target pre‑flight, backups, and rollbacks.
• No accidental leakage of private paths or live‑task data.
• Size limits of the templates (total 2 318 B).
• Basic SVG/JSON integrity for the system map and example task files.

---

When to use (and when not to)

Use QuietHarness if you already have an AI coding assistant and need a lightweight, reproducible safety net that you can version‑control alongside your project.

Don’t use it as a full‑blown task‑orchestration platform – it deliberately does not provide a task database, scheduler, or team‑wide coordination features. Those belong to separate systems (the README points to the author’s other repos for such capabilities).

---

License

MIT – see the LICENSE file.

---

TL;DR

QuietHarness is a 2 KB configuration bundle that you can drop into a Claude Code, Codex, or Cursor workspace to make the assistant behave more predictably: it backs up files, forces test runs, requires explicit confirmation for risky actions, and records concrete evidence of what was changed. Install with a single script, try it in an isolated sandbox, and roll back easily if needed.