Paperclip : L'outil gratuit qui transforme l'IA en équipe de développement logiciel

```html

La plupart des développeurs qui exécutent plusieurs agents IA se heurtent au même mur autour du cinquième agent. Vous avez Claude Code dans un terminal qui réécrit un service backend, Codex dans un autre qui génère des tests, Cursor qui édite un composant, et trois autres onglets que vous avez oublié de vérifier. Personne ne sait ce que fait l'autre. Les coûts s'envolent. Deux agents dupliquent le même travail. L'un tourne pendant six heures et ne produit rien d'utile parce que personne ne lui a donné d'objectif clair.

Paperclip résout ce problème. C'est une plateforme d'orchestration open-source qui transforme vos agents IA dispersés en une entreprise structurée, avec des organigrammes, des rôles assignés, la gestion des tâches, des limites budgétaires et des journaux d'audit. Elle a atteint plus de 35 000 étoiles GitHub en moins de trois semaines, ce qui montre combien de développeurs partageaient la même frustration.

button

Cet article vous guide à travers sa configuration, la structuration de votre première entreprise d'agents, et son exécution afin que le travail soit réellement fait sans que vous ayez à surveiller chaque terminal.

Ce qu'est Paperclip (et ce qu'il n'est pas)

Avant d'installer quoi que ce soit, comprenez ce que vous obtenez.

Paperclip est une couche d'orchestration. Il coordonne les agents, suit leur travail, contrôle leurs budgets et leur donne le contexte des objectifs de l'entreprise. Il ne construit pas d'agents, ne remplace pas votre fournisseur d'IA et n'ajoute pas d'interface de chat.

Le modèle mental utilisé par l'équipe Paperclip : « Si Claude Code est un employé, Paperclip est l'entreprise. »

Cela signifie que :

Les agents ont des rôles, pas seulement des invites
Les tâches ont des propriétaires, pas seulement des terminaux ouverts
Les budgets ont des limites strictes, pas seulement des estimations
Tout est enregistré dans un journal d'audit

Paperclip fonctionne avec Claude Code, OpenAI Codex, Cursor, Gemini CLI, et tout agent pouvant recevoir un webhook ou un signal de battement de cœur. Vous apportez les agents. Paperclip gère l'entreprise.

Il n'est explicitement pas :

Une interface utilisateur de chatbot
Un constructeur de flux de travail par glisser-déposer comme n8n ou Zapier
Un framework pour écrire des agents
Utile pour les cas d'utilisation d'un seul agent

Si vous exécutez un seul agent IA occasionnellement, Paperclip est excessif. Si vous exécutez trois agents ou plus sur des tâches continues, c'est la pièce manquante.

Installation de Paperclip

Vous avez besoin de Node.js 20+, pnpm 9.15+, et c'est tout. Paperclip est livré avec une base de données PostgreSQL intégrée, vous n'avez donc pas besoin de configurer un stockage externe.

Le moyen le plus rapide de démarrer :

npx paperclipai onboard --yes

Cela télécharge l'interface de ligne de commande, exécute l'intégration avec des paramètres par défaut sensibles, et démarre le serveur sur le port 3100. Ouvrez http://127.0.0.1:3100 et vous verrez le tableau de bord.

Si vous souhaitez contribuer ou examiner le code :

git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev

Si vous préférez Docker :

docker compose -f docker-compose.quickstart.yml up --build

Ce qui est créé sur le disque :

Paperclip stocke tout sous ~/.paperclip/instances/default/ :

~/.paperclip/instances/default/
  config.json          — paramètres du serveur et du stockage
  db/                  — fichiers de données PostgreSQL intégrés
  secrets/master.key   — clé de chiffrement (auto-générée)
  logs/                — journaux du serveur
  data/storage/        — pièces jointes
  workspaces/<agent>/  — répertoires de travail par agent
```

Le mode local utilise l'authentification local_trusted par défaut, ce qui ignore la connexion et utilise un utilisateur "Board" synthétique. Vous pouvez commencer à utiliser le tableau de bord immédiatement, aucune création de compte n'est nécessaire.

Une fois que vous êtes connecté, exécutez le contrôle de santé :

paperclipai doctor

Si quelque chose est mal configuré, --repair corrige la plupart des problèmes automatiquement :

paperclipai doctor --repair

`Configuration de votre première entreprise`

Dans Paperclip, une « entreprise » est le conteneur de haut niveau pour vos agents, tâches, objectifs et budgets. Pensez-y comme à un projet, sauf que chaque membre du projet est un agent IA avec un rôle et une ligne hiérarchique.

Depuis le tableau de bord, créez une nouvelle entreprise et donnez-lui une déclaration de mission. Ce n'est pas décoratif. Chaque tâche qu'un agent reçoit est liée à la mission de l'entreprise, de sorte que les agents ont le contexte de *pourquoi* ils font le travail, et pas seulement de *ce qu'il faut faire*. Cela compte pour la prise de décision dans les exécutions agentiques plus longues.

Un exemple simple de mission : « Construire et maintenir une API REST pour la gestion des commandes clients. Prioriser la justesse plutôt que la vitesse. Documenter chaque point d'accès public. »

Cette seule déclaration donne à vos agents un filtre pour chaque décision qu'ils prennent.

`Ajouter vos premiers agents`

Chaque agent dans Paperclip dispose d'un adaptateur qui définit l'outil d'IA qu'il utilise et la façon dont il communique.

Les adaptateurs pris en charge nativement :

Agent	Type d'adaptateur	Paquet
Claude Code	`claude_local`	`@paperclipai/adapter-claude-local`
OpenAI Codex	`codex_local`	`@paperclipai/adapter-codex-local`
Gemini CLI	`gemini_local`	`@paperclipai/adapter-gemini-local`
Cursor	`cursor`	`@paperclipai/adapter-cursor-local`
Webhooks HTTP	Adaptateur HTTP	point de terminaison personnalisé

Pour ajouter un agent Claude Code via la CLI :

paperclipai agent local-cli "Backend Engineer" --company-id <your-company-id>

Ceci initialise l'agent, installe ses compétences dans ~/.claude/skills, et génère les identifiants d'API. L'agent existe maintenant dans l'organigramme de votre entreprise et peut recevoir des affectations de tâches.

Configuration d'un agent Claude (définie dans l'interface utilisateur ou dans la configuration par agent) :

Champ	Ce qu'il fait
`model`	Quel modèle Claude utiliser (ex: `claude-sonnet-4-6`)
`cwd`	Répertoire de travail de l'agent (créé automatiquement s'il manque)
`promptTemplate`	Invite système avec substitution de `{{variable}}`
`maxTurnsPerRun`	Nombre maximum de tours agentiques par battement de cœur (par défaut : 300)
`timeoutSec`	Limite d'exécution stricte (0 = pas de délai)

La répartition des modèles par rôle mérite d'être étudiée avant de commencer. Exécuter Opus sur chaque agent devient rapidement coûteux. Une répartition pratique :

PDG / agents d'orchestration : Sonnet (raisonnement stratégique, le coût en vaut la peine)
Agents managers : Haiku (routage et délégation, rapide et peu coûteux)
Agents créatifs / codeurs : Sonnet (la qualité de la production compte ici)
Agents génériques : Haiku (génération de code boilerplate, échafaudage de tests, migrations)

Cette allocation peut réduire vos dépenses mensuelles d'agents de 40 à 60 % par rapport à l'exécution de Sonnet partout, sans perte significative de qualité sur les tâches de routine.

`Structurer votre organisation d'agents`

Voici une structure de travail pour un petit projet logiciel :

PDG (Sonnet)
 ├── CTO (Haiku)
 │    ├── Ingénieur Backend (Sonnet)
 │    ├── Ingénieur Frontend (Sonnet)
 │    └── Ingénieur QA (Haiku)
 └── Rédacteur Technique (Haiku)

L'agent PDG détient la mission et la divise en objectifs. Le CTO achemine les objectifs vers les agents d'ingénierie. Les ingénieurs font le travail. Le QA valide. Le rédacteur documente.

Chaque agent a un intervalle de battement de cœur, la fréquence à laquelle il se réveille, vérifie ses tâches assignées, effectue son travail et se met en veille. Les agents ne fonctionnent pas en continu. Ils se réveillent, s'exécutent et dorment. C'est ce qui empêche les coûts de s'envoler.

Intervalles recommandés :

Agents de codage : 600 secondes (10 minutes)
Agents à la demande : 86 400 secondes (une fois par jour) avec réveil à la demande activé
Intervalle de sécurité minimum : 30 secondes (inférieur à cela risque de surcoûts et de spam)

`Comment fonctionne le battement de cœur`

Comprendre le modèle de battement de cœur est essentiel pour obtenir un travail fiable de vos agents.

Chaque fois qu'un agent se réveille, il suit un protocole en neuf étapes :

Confirmer l'identité via GET /api/agents/me
Gérer les rappels d'approbation en attente
Récupérer les tâches assignées de GET /api/companies/{companyId}/issues
Prioriser : tâches en cours d'abord, puis à faire ; ignorer les tâches bloquées à moins qu'elles ne puissent être débloquées
Extraire la tâche via POST /api/issues/{issueId}/checkout (si un autre agent l'a déjà prise, la réponse est 409 et cet agent passe à autre chose)
Lire le contexte complet de la tâche et le fil de commentaires
Faire le travail
Mettre à jour la tâche avec des commentaires et des changements de statut
Déléguer des sous-tâches avec des ID de parent et d'objectif si nécessaire

Le mécanisme de "checkout" à l'étape 5 est ce qui empêche le travail en double. Deux agents ne peuvent pas prendre la même tâche. Si l'un y travaille, l'autre l'ignore automatiquement.

Paperclip injecte du contexte dans chaque exécution d'agent via des variables d'environnement :

PAPERCLIP_TASK_ID          # quelle tâche a déclenché cette exécution
PAPERCLIP_WAKE_REASON      # pourquoi l'agent s'est réveillé (minuterie, mention, assignation)
PAPERCLIP_AGENT_ID         # l'identité de l'agent
PAPERCLIP_API_URL          # URL pour rappeler l'API de Paperclip

Les agents peuvent les utiliser pour publier des mises à jour, créer des sous-tâches, demander des approbations et déléguer — le tout au sein d'un seul battement de cœur.

`Assigner des tâches et suivre le travail`

Les tâches dans Paperclip fonctionnent comme des problèmes GitHub croisés avec un outil de gestion de projet. Créez-en une depuis l'interface utilisateur ou la CLI :

paperclipai issue create \
  --company-id <id> \
  --title "Add pagination to the orders endpoint" \
  --assignee-agent-id <backend-engineer-id>

Les tâches peuvent avoir :

Des tâches parentes pour diviser un gros travail en sous-tâches
Des liens d'objectifs pour que les agents sachent à quel objectif de l'entreprise cela sert
Des commentaires pour le contexte, les demandes d'approbation et les mises à jour de statut
Des @-mentions pour réveiller un agent spécifique à la demande (pas besoin d'attendre le prochain battement de cœur)

Vous pouvez voir toutes les tâches ouvertes depuis la CLI :

paperclipai issue list

Ou dans le tableau de bord, où les tâches affichent leur propriétaire actuel, leur statut et la dernière exécution qui les a touchées.

`Contrôle budgétaire qui fonctionne vraiment`

C'est l'une des fonctionnalités les plus utiles de Paperclip, et la plus négligée par les nouveaux utilisateurs des configurations multi-agents.

Chaque agent dispose d'un budget de jetons mensuel. Lorsqu'il atteint 80 %, l'agent se consacre automatiquement aux tâches critiques uniquement. Lorsqu'il atteint 100 %, il se met complètement en pause.

Définissez un budget dans la configuration de l'agent. Le point de départ suggéré par la communauté est de 20 à 50 dollars par mois et par niveau d'agent. Vous pouvez suivre le taux d'utilisation par agent, le coût par battement de cœur et les dépenses mensuelles cumulées, le tout depuis le tableau de bord.

Le tableau de bord des coûts montre quels agents sont efficaces et lesquels gaspillent des jetons sur un travail non ciblé. Si le coût par battement de cœur d'un agent augmente, c'est généralement un signe que les invites sont trop vagues ou que l'étendue de la tâche est trop large. Vous le corrigez en affinant l'affectation, et non en augmentant le budget.

Sans contrôles budgétaires, un agent mal configuré fonctionnant à un intervalle de 30 secondes avec "Réflexion étendue" activée peut brûler des centaines de dollars avant que vous ne le remarquiez. Paperclip l'empêche automatiquement.

`Compétences d'exécution : enseigner de nouveaux flux de travail aux agents sans réentraînement`

L'une des fonctionnalités les plus puissantes de Paperclip est l'injection de compétences. Lorsqu'un agent s'exécute, l'adaptateur de Paperclip crée des liens symboliques vers les fichiers SKILL.md dans le répertoire de configuration de l'agent et les transmet via --add-dir. L'agent lit le fichier de compétence dans le cadre de son contexte et suit le flux de travail.

Cela signifie que vous pouvez enseigner à un agent un nouveau processus, comme la rédaction de messages de commit, la gestion des migrations de base de données ou le formatage de la documentation d'API, en écrivant un fichier markdown. Pas de réécriture d'invite. Pas de redéploiement.

Vous écrivez la compétence :

# COMPÉTENCE : Migrations de bases de données

Lors de la création d'une migration :
1. Ne jamais modifier les fichiers de migration existants
2. Utiliser des noms descriptifs : AAAAJJMM_description.sql
3. Inclure le SQL pour la montée et la descente
4. Tester localement avant de commettre
5. Ajouter un commentaire expliquant la raison métier du changement

Enregistrez-le dans le répertoire des compétences, assignez-le à votre agent backend, et chaque battement de cœur futur suivra ce processus.

`Si vous testez des API construites par vos agents`

Lorsque vos agents construisent des API, vous avez besoin d'un moyen de tester rapidement ce qu'ils produisent. Apidog s'intègre naturellement ici. Il gère la conception d'API, les serveurs de maquette et les tests automatisés en un seul endroit, de sorte que lorsque votre agent backend livre un point de terminaison, vous pouvez le valider immédiatement sans basculer entre Swagger, Postman et un outil de maquette séparé.

Vous pouvez générer automatiquement des suites de tests à partir de votre spécification OpenAPI, les exécuter sur la sortie de l'agent et renvoyer les résultats sous forme de commentaire de tâche. L'agent les récupère au prochain battement de cœur et corrige les échecs. La boucle complète, du code au test en passant par la correction, s'exécute sans intervention humaine.

Apidog prend en charge REST, GraphQL et gRPC, et il est gratuit pour commencer.

`Gestion de plusieurs instances`

Paperclip prend en charge plusieurs instances isolées sur une seule machine via la variable d'environnement PAPERCLIP_INSTANCE_ID ou le drapeau --instance. Chaque instance possède sa propre configuration, base de données, ports et espaces de travail.

Pour le développement local, la commande worktree crée une instance de développement entièrement isolée par branche git :

paperclipai worktree:make feature/orders-pagination

Cela vous donne des ports, une configuration et une base de données séparés, spécifiques à cette branche. Vous pouvez exécuter une entreprise de test sur le code de fonctionnalité sans toucher à votre configuration d'agent de production. Lorsque vous avez terminé, supprimez-la et elle disparaît.

`Configurations multi-agents qui fonctionnent`

Quelques modèles qui fonctionnent bien une fois que vous avez les bases :

Cascade d'objectifs : Écrivez un objectif de haut niveau au niveau de l'entreprise, puis laissez votre agent PDG le décomposer en objectifs de projet, et chaque agent manager décomposer ceux-ci en tâches. Les agents travaillent mieux lorsqu'ils comprennent la chaîne de buts plutôt que de recevoir des instructions isolées.

Gates d'approbation : Pour toute action d'agent qui touche la production, les environnements de staging ou la facturation, configurez une gate d'approbation. L'agent se met en pause, vous envoie une notification et attend un pouce levé avant de continuer. Cela ajoute une étape manuelle mais permet de détecter les problèmes avant qu'ils ne deviennent coûteux.

Réveils à la demande via @-mention : Au lieu d'un intervalle de battement de cœur rapide (et le coût en jetons qui l'accompagne), configurez les agents à un intervalle lent et utilisez les @-mentions dans les commentaires de tâche pour les réveiller immédiatement si nécessaire. Vous obtenez des temps de réponse rapides sur les tâches importantes sans payer pour un sondage constant.

Espace de travail séparé par agent : Chaque agent a son propre répertoire de travail sous workspaces/<agent-id>/. Gardez-les propres. Les agents qui partagent un espace de travail se marchent sur les pieds. L'isolation est intégrée ; ne la combattez pas.

`Le démarrage prend environ 15 minutes`

La première fois, l'intégration prend moins de 15 minutes. Une seule commande installe et démarre le serveur. L'ajout de votre premier agent et la création d'une tâche prennent cinq minutes de plus dans le tableau de bord.

Le plus difficile est de bien structurer votre entreprise : rédiger une mission claire, choisir le bon modèle pour chaque rôle et fixer des limites budgétaires raisonnables. Consacrez 30 minutes à cela avant de commencer à assigner du travail, et vos agents produiront de bien meilleurs résultats que si vous connectez tout rapidement et espérez le meilleur.

Si vous utilisez déjà plus de deux agents IA sur un projet en cours, cela vaut la peine d'y consacrer un après-midi de configuration. La différence entre un onglet de terminal par agent et une entreprise structurée avec des contrôles budgétaires, la propriété des tâches et des journaux d'audit est la différence entre un projet secondaire et quelque chose qui peut réellement fonctionner sans supervision.

```