Installation

Ce guide amène un dépôt de zéro à un workflow repo-harness opérationnel : installer le runtime, adopter le dépôt, câbler les hooks de votre agent, et confirmer que les garde-fous se déclenchent.

Prérequis

Un dépôt git

repo-harness est repo-local. Exécutez-le depuis un arbre de travail git — faites git init d’abord si le dossier n’en est pas encore un.

Un agent

Claude Code ou la CLI Codex comme exécuteur. ChatGPT Pro est optionnel, pour la planification.

Bun

La CLI s’exécute sur Bun — l’installateur l’intègre s’il est manquant. Aucune configuration Node requise.

1. Installer la CLI

Obtenez le binaire repo-harness sur votre machine avec le point d’entrée qui vous convient :

curl

# macOS / Linux — installs Bun if missing, then the CLI
curl -fsSL https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.sh | sh

bun

bun add -g repo-harness

npm

npm install -g repo-harness

Deux « installations » différentes

L’étape ci-dessus installe le paquet CLI. L’étape suivante, repo-harness init, est une action distincte qui configure le runtime sur cette machine. Même mot, missions différentes — c’est pourquoi la commande de bootstrap est init, et non install.

2. Bootstrap du runtime

1. Exécutez init une fois par machine. C’est idempotent — cela câble les adaptateurs de hook hôte, les skills Waza et l’index CodeGraph pour chaque projet que vous utiliserez :

   repo-harness init
   # ✓ host adapters · skills · CodeGraph configured

2. Vérifiez l’état de préparation à tout moment (lecture seule) :

   repo-harness status   # CLI version, host install state, route coverage
   repo-harness doctor   # PATH, version, hosts, trust state

Déjà bootstrappé ?

repo-harness init peut être réexécuté sans risque — utilisez-le pour réparer une machine à moitié configurée. Pour récupérer un runtime plus récent ultérieurement, utilisez repo-harness update.

3. Adopter votre dépôt

1. Depuis la racine de votre dépôt, prévisualisez ce qui va changer. Rien n’est écrit :

   repo-harness adopt --dry-run   # Migration Report

2. Appliquez le contrat repo-local :

   repo-harness adopt

adopt inspecte le dépôt, installe les fichiers de workflow, câble les hooks, construit l’index CodeGraph et exécute le contrôle de workflow. L’arborescence qu’il met en place :

• AGENTS.md contrat de routage Codex
• CLAUDE.md contrat de routage Claude Code
• Répertoire.ai/

  • Répertoireharness/ contrat, politique, contrôles, handoff

    • …
  • Répertoirecontext/ context-map + capabilities

    • …
  • Répertoirehooks/ runtime de hook repo-local

    • …
• Répertoiredocs/

  • spec.md vérité produit
• Répertoireplans/ catalogue de plans horodaté

  • …
• Répertoiretasks/

  • Répertoirecontracts/ autorité de portée d’édition

    • …
  • Répertoirereviews/ portes d’achèvement

    • …
• Répertoirescripts/ utilitaires de workflow

  • …

Pas un dépôt git ?

adopt refuse de s’exécuter hors d’un arbre de travail git. Faites git init d’abord, ou passez une cible explicite avec repo-harness adopt --repo <path> pour un scaffold hors git.

4. Câbler votre agent

init installe des adaptateurs hôtes qui dispatchent les événements de l’éditeur vers repo-harness. Pointez votre agent vers eux, puis redémarrez la session pour que les hooks se chargent.

Claude Code

L’adaptateur réside dans vos paramètres utilisateur — ~/.claude/settings.json — et route chaque événement SessionStart, PreToolUse, PostToolUse, UserPromptSubmit et Stop dans le harness. Redémarrez Claude Code pour le prendre en compte.

Codex

Codex lit ~/.codex/hooks.json. Après que init l’a écrit, faites confiance à la config de hook dans les Paramètres Codex — Codex n’exécutera pas de hooks non approuvés. Puis démarrez une nouvelle session.

5. Vérifier que c’est actif

1. Routage des prompts — soumettez n’importe quel prompt. Le hook UserPromptSubmit classe l’intention et fait remonter l’état du plan dans sa sortie consultative.

2. Le garde-fou d’édition — demandez à l’agent de modifier un fichier avant qu’un plan ne soit approuvé. Le garde-fou PreToolUse.edit échoue de façon fermée et bloque l’écriture jusqu’à ce que vous saisissiez un plan.

3. Le contrôle de workflow — exécutez la porte directement :

   bash scripts/check-task-workflow.sh --strict

Un contrôle au vert signifie que la surface du contrat est cohérente et que les garde-fous sont armés.

6. Planifier avec ChatGPT Pro (optionnel)

Vous voulez que ChatGPT Pro lise vos plans sans toucher au code source ? Exposez uniquement les fichiers de workflow via un sidecar MCP local :

repo-harness mcp setup chatgpt --repo .
repo-harness mcp serve --transport http \
  --host 127.0.0.1 --port 8765 --profile planner

Tous les détails — y compris la limite de sécurité en lecture seule — se trouvent sur la page Planificateur ChatGPT Pro.

Étapes suivantes

Le workflow Plan → Sprint → Goal, et la Carte de revue humaine.

Hooks Les huit routes gérées qui protègent et tracent votre travail.

Référence CLI Chaque commande dont vous aurez besoin.