---
name: paperclip-quickstart
description: >
  Guide d'installation et bonnes pratiques Paperclip pour tout nouvel opérateur.
  Use when setting up Paperclip for the first time, configuring agents, structuring
  an org chart, or troubleshooting a fresh install. Generic — works for any use case.
---

# Paperclip — Guide Quickstart & Bonnes Pratiques

Paperclip est un control plane open-source pour orchestrer des équipes d'agents IA.
Il gère l'org chart, les budgets, la gouvernance et la coordination — tu fournis les agents.

## Installation (2 minutes)

```bash
# Prérequis : Node.js 20+, pnpm 9.15+
git clone https://github.com/paperclipai/paperclip.git ~/paperclip
cd ~/paperclip
pnpm install

# Créer le script de démarrage (évite les conflits avec Claude Code)
cat > ~/paperclip/start.sh << 'STARTEOF'
#!/bin/zsh
unset CLAUDECODE
cd "$(dirname "$0")"
pnpm dev
STARTEOF
chmod +x ~/paperclip/start.sh
```

**Important :** toujours lancer via `~/paperclip/start.sh`, jamais depuis un terminal Claude Code.
UI disponible sur `http://127.0.0.1:3100`.

## Ordre de setup recommandé

```
1. Créer la company (nom + mission)
2. Créer un company goal (mesurable, time-boxé)
3. Créer le CEO agent → board approuve la stratégie
4. Builder l'org : CEO > managers > ICs
5. Configurer budgets par agent
6. Activer heartbeats
7. Créer les premières tâches
```

## Configurer un agent — template

```json
{
  "adapterType": "claude_local",
  "adapterConfig": {
    "model": "claude-haiku-4-5-20251001",
    "cwd": "/ton/dossier/workspace",
    "instructionsFilePath": "/ton/dossier/agents/nom-agent/AGENTS.md",
    "args": ["--add-dir", "/ton/dossier/skills"],
    "timeoutSec": 900,
    "graceSec": 15,
    "maxTurnsPerRun": 20,
    "dangerouslySkipPermissions": true
  }
}
```

### Quel modèle choisir ?

| Rôle | Modèle recommandé | Pourquoi |
|------|------------------|---------|
| CEO / orchestration | Sonnet | Raisonnement stratégique |
| Manager (délégation) | Haiku | Lecture + routing, pas besoin de Sonnet |
| IC créatif (contenu, copy) | Sonnet | Qualité output |
| IC formulaïque (outreach, ops) | Haiku | 3x moins cher, suffisant |

## Heartbeat — configuration

```json
{
  "runtimeConfig": {
    "heartbeat": {
      "enabled": true,
      "intervalSec": 600,
      "wakeOnDemand": true,
      "cooldownSec": 10,
      "maxConcurrentRuns": 1
    }
  }
}
```

- **Agents créatifs / coding** : 600s (10 min)
- **Agents on-demand** : 86400s (1/jour) + `wakeOnDemand: true`
- Ne jamais descendre sous 30s — risque de spam et surcoût

## Budgets — règles d'or

| Seuil | Comportement auto |
|-------|------------------|
| 80% | Agent focus tâches critiques seulement |
| 100% | Agent auto-pausé |

Réglages de départ :
- CEO : 5 000 cents ($50/mois)
- Managers : 3 000 cents
- ICs : 2 000 cents
- Company total : 15 000-20 000 cents

**Ne jamais laisser à 0** (= illimité = risque runaway).

## Écrire un bon AGENTS.md

Structure minimale efficace :

```markdown
You are [Nom], [Rôle] at [Company].

## Reporting
Tu reportes à [Manager]. [Board] est le board.

## Responsabilités
1. [Action principale]
2. [Action principale]

## KPIs
| KPI | Cible |
|-----|-------|
| [Métrique] | [Valeur] |

## Règles
- Toujours utiliser le skill `paperclip` pour la coordination.
- Ne jamais annuler une tâche cross-team — réassigner au manager.
- Escalader à [Manager] si bloqué.
```

**À ne pas mettre dans AGENTS.md :**
- Le protocole heartbeat Paperclip (déjà dans le skill `paperclip`)
- Le contexte produit (le mettre dans un skill dédié)
- Les instructions d'API (le skill `paperclip` les couvre)

## MCPs pour les agents

Créer un `.mcp.json` dans le dossier workspace des agents :

```json
{
  "mcpServers": {
    "mon-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@mon/mcp-server"],
      "env": {}
    }
  }
}
```

Les agents Claude Code détectent automatiquement ce fichier au démarrage.

## Debugging — checklist

1. **Erreur "nested sessions"** → lancer Paperclip avec `unset CLAUDECODE`
2. **Workspace fallback** → configurer `cwd` dans l'adapterConfig
3. **Agent ne fait rien** → vérifier `instructionsFilePath` + heartbeat `enabled: true`
4. **Timeout immédiat** → `timeoutSec` à 0, le passer à 900
5. **Port 3100 occupé** → `lsof -ti:3100 | xargs kill -9`
6. **Config invalide** → `pnpm paperclipai doctor --repair`

## Commandes CLI essentielles

```bash
pnpm paperclipai doctor          # santé de l'instance
pnpm paperclipai doctor --repair # réparation auto
pnpm paperclipai agent list      # lister les agents
pnpm paperclipai issue list      # lister les tâches
pnpm paperclipai heartbeat run --agent-id <id>  # déclencher manuellement
```

## Installer ce skill

```bash
mkdir -p ~/.claude/skills/paperclip-quickstart
curl -o ~/.claude/skills/paperclip-quickstart/SKILL.md \
  https://gist.githubusercontent.com/Bennn1O/1a720a142a0ca3be089577fbdc94d899/raw/SKILL.md
```