Aller au contenu
Documentation

Personnaliser l’agent IA

Tout ce qui figure sur cette page est un fichier local. Les fichiers situés sous .champrep/ dans un dépôt sont partagés avec votre équipe via Git ; les fichiers situés sous $CONFIG/ai/ s’appliquent uniquement à vous, dans tous les projets. Lorsqu’un projet et une définition utilisateur portent le même nom, c’est celle du projet qui prévaut.

Contenu du projet dans .champrep/ reste inactif tant que vous n’avez pas approuvé le dépôt. Voir Confiance du dépôt.

CHAMPREP.md contient des instructions permanentes destinées à l’agent : comment construire et tester le projet, les conventions à respecter et les éléments à éviter. L’agent lit ces instructions au début de chaque session :

  • $CONFIG/ai/CHAMPREP.md, vos instructions personnelles pour chaque projet ;
  • CHAMPREP.md à la racine du projet et dans chaque répertoire depuis la racine jusqu’à l’emplacement où vous avez lancé l’agent.

Si un répertoire ne contient aucun CHAMPREP.md, un AGENTS.md est utilisé à la place.

ActionComment
En créer un/init parcourt le référentiel et écrit CHAMPREP.md, en conservant le contenu utile d’un fichier existant AGENTS.md.
Ajouter une noteLancez une invite avec #, par exemple # run make lint before committing.
Afficher ou modifier/memory, ou /memory edit [user|project|FILE] pour l’ouvrir dans votre éditeur.

La mémoire de votre CHAMPREP AIcompte, gérée dans vos paramètresCHAMPREP AI sur le Web, s’applique également dans le terminal. /memory l’affiche en lecture seule.

Une commande personnalisée est un modèle de prompt Markdown que vous exécutez sous la forme /<name>.

EmplacementPortée
.champrep/commands/NAME.mdCe projet
$CONFIG/ai/commands/NAME.mdVous

Un fichier situé dans un sous-dossier, tel que commands/git/commit.md, devient /git:commit. Créez-en un avec /commands new NAME et répertoriez-les à l’aide de /commands.

---
description: Explain a failing test and propose a fix
argument-hint: <test name>
allowed-tools: [local_read_file, local_grep, local_bash]
---
Find the test named $1, run it, and explain why it fails.
Relevant notes: @docs/testing.md
Recent changes:
!`git log --oneline -5`
  • $ARGUMENTS correspond à tout ce qui suit le nom de la commande ; $1, $2, … sont des arguments uniques. Si le modèle n’utilise ni l’un ni l’autre, les arguments sont ajoutés à la fin.
  • @path inclut un fichier d’espace de travail. Les fichiers contenant des secrets ne sont jamais inclus.
  • !`command` exécute une commande lorsque vous invoquez le modèle. Il vous est demandé de l’approuver une fois par modèle, puis à chaque modification de celui-ci.
  • allowed-tools limite les outils disponibles pour ce tour, et model remplace le modèle.

Une compétence est un dossier contenant des instructions, ainsi que des fichiers d’accompagnement facultatifs, que l’ agent ne charge que lorsqu’il en a besoin. Jusqu’à ce moment-là, le modèle ne voit que le nom et la description de la compétence ; ainsi, de nombreuses compétences ne nécessitent que très peu de contexte.

EmplacementPortée
.champrep/skills/NAME/SKILL.mdCe projet
$CONFIG/ai/skills/NAME/SKILL.mdVous
---
description: Release checklist for this service
when_to_use: When the user asks to cut, tag, or publish a release
---
1. Confirm the changelog has an entry for the new version.
2. ...

/skills répertorie les compétences, y compris celles de votre CHAMPREP AIcompte. Exécutez-en une directement avec /<skill-name>.

Un agent personnalisé est un sous-agent doté de ses propres instructions, outils et modèle.

EmplacementPortée
.champrep/agents/NAME.mdCe projet
$CONFIG/ai/agents/NAME.mdVous
---
name: test-writer
description: Writes and fixes unit tests. Use after a code change.
tools: [local_read_file, local_grep, local_glob, local_edit_file, local_bash]
permission_mode: accept-edits
isolation: worktree
---
You write focused unit tests that follow this project's existing style.
  • description indique à l’agent principal quand lui déléguer une tâche.
  • tools limite les outils ; omettez-le pour hériter des outils de la session.
  • permission_mode ne peut que rendre l’agent plus restrictif que votre session.
  • isolation: worktree l’exécute dans son propre répertoire de travail Git.

Gérer les agents avec /agents create|edit|delete NAME. Démarrez une session en tant qu’ agent avec champrep ai --agent NAME, ou envoyez-lui une invite avec @NAME prompt. Voir Sous-agents.

Les hooks sont des commandes shell que le exécuteCLI à différents moments d’une session, par exemple pour mettre en forme des fichiers après une modification ou pour bloquer certaines commandes.

ÉvénementS’exécute
SessionStartLorsqu’une session démarre.
UserPromptSubmitAvant l’envoi d’une invite. Peut la bloquer ou ajouter du contexte.
PreToolUseAvant l’exécution d’un outil local. Peut le bloquer.
PostToolUseAprès l’exécution d’un outil local. Permet d’ajouter des commentaires au résultat.
PermissionRequestLorsqu’une invite d’autorisation s’affiche.
NotificationQuand l’agent vous envoie une notification.
SubagentStopLorsqu’un sous-agent a terminé.
PreCompactAvant que la conversation ne soit condensée.
StopÀ la fin d’un tour.
SessionEndÀ la fin de la session.

Configurez les hooks dans n’importe quel fichier de paramètres :

{
"hooks": {
"PostToolUse": [
{ "matcher": "local_edit_file|local_write_file", "command": "npm run format --silent", "timeout": 30 }
],
"PreToolUse": [
{ "matcher": "local_bash", "command": "./scripts/check-command.sh" }
]
}
}
  • matcher est une expression régulière sur le nom de l’outil ; omettez-la pour qu’elle s’applique à tous les outils.
  • Le hook reçoit une description JSON de l’événement via l’entrée standard.
  • Code de sortie 2, ou sortie JSON avec "decision": "block" et un reason, bloque l’action lorsque l’événement le permet. additionalContext au format JSON La sortie ajoute du texte pour le modèle.
  • Le délai d’expiration par défaut est de 60 secondes, et le maximum est de 10 minutes.
  • Les hooks s’exécutent avec votre environnement, à l’exception des identifiantsCHAMPREP.

Gérer les hooks avec /hooks, /hooks add EVENT [--matcher M] [--timeout S] [--scope user|project] -- COMMAND, /hooks disable ID, et /hooks enable ID.

CommandeOptions
/colorUne couleur d’accentuation pour les sessions de ce projet, afin de distinguer les sessions parallèles : blue, cyan, green, yellow, orange, red, pink, magenta, purple, gray, ou reset.
/themeauto, dark, light, high-contrast, ou colorblind. NO_COLOR et --no-color désactive les couleurs.
/statuslineSélectionnez des segments parmi profile, model, context, branch, mode, cost, et tasks; utilisez /statusline command CMD pour afficher la première ligne de la sortie de votre propre commande ; /statusline reset rétablit les valeurs par défaut.
/output-styledefault, concise, explanatory, ou learning.
/vimÉdition de type Vim dans l’invite.
/keybindingsAfficher les raccourcis ; /keybindings edit ouvre $CONFIG/ai/keybindings.json.
/configTout ce qui précède sur un seul écran.

Les conversations de l’agent sont hébergées sur votre CHAMPREP AIcompte. Seul l’état spécifique à la machine est stocké localement. Affichez tous les emplacements sur votre machine à l’aide de :

Fenêtre de terminal
champrep ai paths
QuoiOù
CLI profils et environnements$CONFIG/config.toml
Vos paramètres d’agent : règles, mode, thème, ligne d’état, hooks$CONFIG/ai/settings.json
Remplacement des raccourcis clavier$CONFIG/ai/keybindings.json
Vos instructions personnelles$CONFIG/ai/CHAMPREP.md
Vos agents, commandes et compétences$CONFIG/ai/agents/, commands/, skills/
Vos serveurs MCP locaux$CONFIG/ai/mcp.json
Projets de confiance$CONFIG/ai/trusted-projects.json
Conversations récentes par répertoire et listes de tâches$STATE/ai/sessions.json
Historique des invites (expurgé et tronqué)$STATE/ai/history.jsonl
Journaux de débogage (expurgés, conservés pendant 7 jours)$STATE/ai/logs/
Points de contrôle des fichiers$CACHE/ai/checkpoints/
Paramètres du projet (pouvant faire l’objet d’un commit).champrep/settings.json, mcp.json, agents/, commands/, skills/
Vos remplacements de projet (fichiers ignorés par git).champrep/settings.local.json
Instructions relatives au projetCHAMPREP.md
Arbres de travail.champrep/worktrees/

Les identifiants ne sont jamais stockés dans ces fichiers. Ils restent dans le trésor du système d’exploitation.

RootmacOS et LinuxWindows
$CONFIG$XDG_CONFIG_HOME/champrep, sinon ~/.config/champrep%APPDATA%\champrep
$STATE$XDG_STATE_HOME/champrep, sinon ~/.local/state/champrep%LOCALAPPDATA%\champrep\state
$CACHE$XDG_CACHE_HOME/champrep, sinon ~/.cache/champrep%LOCALAPPDATA%\champrep\cache

Définir CHAMPREP_CONFIG_DIR pour conserver les trois dans un même répertoire, dans config/, state/, et cache/ sous-dossiers. Ceci est utile pour les installations portables et les exécutions CI isolées.