# agent-manager (am)

Gestionnaire en ligne de commande, écrit en **Rust**, pour les **agents IA de
coding installés localement** : lister, installer, démarrer, arrêter,
redémarrer, mettre à jour et désinstaller — avec gestion automatique des
dépendances (Node.js, Python, Go, Rust, Bun, etc.) et un catalogue YAML de
~70 agents prêts à l'emploi.

---

## Sommaire

1. [Fonctionnalités](#fonctionnalités)
2. [Installation](#installation)
3. [Démarrage rapide](#démarrage-rapide)
4. [Commandes](#commandes)
5. [Options globales](#options-globales)
6. [Fichier de configuration](#fichier-de-configuration)
7. [Ajouter un agent](#ajouter-un-agent)
8. [Alias, groupes et mode interactif](#alias-groupes-et-mode-interactif)
9. [Gestion des processus](#gestion-des-processus)
10. [Sécurité](#sécurité)
11. [Tests](#tests)
12. [Complétions shell](#complétions-shell)
13. [Structure du projet](#structure-du-projet)
14. [Limites et feuille de route](#limites-et-feuille-de-route)

---

## Fonctionnalités

- **Catalogue intégré** : ~70 agents connus (Claude Code, Codex, Gemini CLI,
  OpenCode, Aider, jcode, Prime Agent, l'écosystème OpenClaw, les SaaS, etc.),
  chacun avec sa méthode d'installation et ses dépendances.
- **9 méthodes d'installation** :

  | type | description |
  |------|-------------|
  | npm / bun | paquet global installé dans un préfixe local (jamais en -g système) |
  | pip / uv  | virtualenv privé par agent, sans toucher au site-packages système |
  | cargo | cargo install --root <répertoire-local> |
  | go    | go install avec GOBIN local |
  | curl  | script d'installation téléchargé puis exécuté séparément (jamais de curl pipé vers sh) |
  | binary| binaire précompilé depuis GitHub Releases ou URL directe, checksum vérifié, extraction zip/tar.gz |
  | git   | clone + build (make, cargo build --release, npm install…) puis copie du binaire ou shim |

- **Gestion des processus** : avant-plan (stdio hérités) ou arrière-plan
  (détaché, PID enregistré, sortie vers un log) ; arrêt propre SIGTERM puis
  SIGKILL après un délai configurable.
- **Base d'état locale** (state.json) : nom, version, chemin, binaires, PID,
  dates — plus la **détection d'agents externes** via le PATH. Les sondes de
  version sont exécutées **en parallèle** (timeout 4 s) et **mises en cache**
  (index du PATH et versions) : un am list à chaud prend ~50 ms.
- **Dépendances** : vérification avant installation (node >= 18, etc.) avec
  messages actionnables ; installation automatique possible quand une commande
  d'installation est connue.
- **Sécurité** : mode --dry-run universel, confirmations (--yes pour les
  sauter), validation des URL (http/https/file), vérification sha256,
  journalisation horodatée de toutes les commandes exécutées.
- **Confort développeur** : sortie JSON stable (--json), couleurs
  (--no-color), mode verbeux, complétions bash/zsh/fish/powershell/elvish,
  alias, groupes (am start group:dev), mode interactif, export/import,
  doctor et self-update.

---

## Installation

### En une ligne (recommandé)

**Windows** (PowerShell) :

    powershell -ExecutionPolicy Bypass -Command "irm https://git.dracodev.net/Projets/agent-manager/raw/branch/main/install.ps1 | iex"

**Linux / macOS / WSL** :

    curl -fsSL https://git.dracodev.net/Projets/agent-manager/raw/branch/main/install.sh | sh

Le script télécharge le binaire précompilé de la **dernière release** du dépôt
Gitea, l'installe dans un répertoire utilisateur et l'ajoute au PATH. Si aucun
binaire ne correspond à votre plateforme, il compile automatiquement depuis
les sources (cargo install --git). **Relancez la même commande pour mettre à
jour.** Les scripts sont versionnés dans le dépôt (install.ps1, install.sh) —
vous pouvez les lire avant de les exécuter.

### Depuis les sources

Prérequis : Rust 1.70+ (le programme lui-même n'a **aucune** dépendance
runtime ; les outils comme node/python ne sont nécessaires que pour les agents
qui les utilisent).

    # 1. cloner et compiler (binaire dans target/release/am)
    git clone https://git.dracodev.net/Projets/agent-manager.git
    cd agent-manager
    cargo build --release

    # 2. installer dans ~/.cargo/bin (sur le PATH)
    cargo install --path .

    # 3. vérifier
    am --version
    am doctor

> Le binaire s'appelle **am** (agent-manager est le nom du paquet).

### Ajouter les binaires des agents au PATH

Les agents installés par am vivent dans
~/.local/share/agent-manager/agents/bin (Linux),
%LOCALAPPDATA%\agent-manager\agents\bin (Windows) ou
~/Library/Application Support/agent-manager/agents/bin (macOS).
Ajoutez ce répertoire au PATH pour pouvoir lancer les agents directement :

    # Linux/macOS — dans ~/.bashrc ou ~/.zshrc
    export PATH="$HOME/.local/share/agent-manager/agents/bin:$PATH"

am doctor vous le rappelle si le répertoire n'est pas sur le PATH.

---

## Démarrage rapide

    am list                        # agents installés (gérés + externes)
    am list --all                  # tout le catalogue, avec l'état de chacun
    am search rust                 # recherche par mot-clé
    am info jcode                  # fiche détaillée

    am install claude-code         # npm + vérification de node >= 18
    am install aider --method pip  # choisir la méthode 2 (pip) au lieu de uv
    am install smelt --dry-run     # simuler sans rien changer

    am start claude-code           # avant-plan (Ctrl-C pour quitter)
    am start claude-code --background --env ANTHROPIC_MODEL=opus
    am status claude-code
    am stop claude-code            # SIGTERM puis SIGKILL après 5 s
    am restart codex --background
    am update claude-code
    am uninstall smelt --purge

    am run pi "explique ce fichier"   # exécution directe, sans gestion de process
    am doctor --fix                   # vérifie l'environnement et répare

---

## Commandes

| Commande | Description |
|----------|-------------|
| am list [--all] [--category <cat>] | agents installés (défaut) ; --all pour tout le catalogue |
| am start <agent> [--background] [--args ...] [--env K=V] [--notify] | démarre l'agent (avant-plan par défaut) |
| am stop <agent> [--force] [--timeout <s>] | arrête un agent d'arrière-plan (PID enregistré) |
| am restart <agent> [--background] [--force] | arrête puis redémarre |
| am status [agent] | état d'un agent, ou de tous les agents installés |
| am install <agent> [--method <n|type>] [--force] | installe l'agent et ses dépendances |
| am uninstall <agent> [--purge] | désinstalle et nettoie (--purge : logs + entrée de config) |
| am update <agent> [--all] | met à jour vers la dernière version connue |
| am search <mot-clé> [--category <cat>] | recherche dans le catalogue |
| am info <agent> | description, méthodes d'installation, commande, dépendances, site |
| am config show / path / edit / validate / add <fichier> | gestion de la configuration |
| am doctor [--fix] | outils présents, validité de la config, chemins, permissions |
| am run <agent> [args...] | exécute la commande de l'agent directement |
| am completion <shell> | script de complétion (bash, zsh, fish, powershell, elvish) |
| am self-update [--check] | met à jour agent-manager depuis GitHub Releases |
| am export / am import <fichier> | sauvegarde/restauration de la config + état |
| am (sans arguments) | shell interactif |

**Statuts affichés par list/status** : running (PID actif), installed (géré
par am), external (trouvé sur le PATH, non géré), not-installed,
not-installable (SaaS/desktop).

---

## Options globales

Toutes les options globales fonctionnent avant **ou après** la sous-commande.

| Option | Description |
|--------|-------------|
| -c, --config <fichier> | fichier de configuration alternatif |
| -v, --verbose | affiche chaque commande exécutée et les détails |
| -q, --quiet | uniquement les erreurs |
| -y, --yes | répond oui à toutes les confirmations |
| --dry-run | simule l'action (aucune écriture, aucun téléchargement) |
| --json | sortie JSON stable sur stdout (les messages vont sur stderr) |
| --no-color | désactive les couleurs ANSI |
| -h, --help / -V, --version | aide / version |

---

## Fichier de configuration

### Emplacements (par ordre de priorité)

1. --config <fichier> (ou la variable d'environnement AGENT_MANAGER_CONFIG)
2. ./agent-manager.yaml (répertoire courant)
3. ~/.config/agent-manager/config.yaml
   (Windows : %APPDATA%\agent-manager\config.yaml)
4. catalogue par défaut embarqué dans le binaire

Le fichier trouvé **surcharge/complète** le catalogue embarqué : un agent
défini par l'utilisateur remplace celui du même nom ; les autres s'ajoutent.

### Schéma (extrait)

    version: "1.0"

    settings:
      install_dir: null        # défaut: ~/.local/share/agent-manager/agents
      log_dir: null            # défaut: ~/.local/state/agent-manager/logs
      default_shell: null      # shell pour les scripts d'installation
      auto_install_deps: true  # proposer d'installer les dépendances manquantes
      confirm_before_run: true # confirmer avant d'exécuter un script d'installation
      stop_timeout_secs: 5     # délai SIGTERM -> SIGKILL
      self_update_repo: null   # "owner/repo" pour am self-update

    aliases:
      cc: claude-code          # am start cc == am start claude-code

    groups:
      dev: [claude-code, aider, codex]

    include:                   # modularité : autres fichiers (chemins relatifs)
      - agents-perso.yaml

    agents:
      - name: claude-code
        display_name: "Claude Code"
        description: "..."
        category: coding-agent
        website: https://github.com/anthropics/claude-code
        install:
          type: npm
          package: "@anthropic-ai/claude-code"
          # args: ["--omit=optional"]          # arguments supplémentaires
          # env: { FOO: bar }                  # environnement de l'installeur
          # methods: [...]                     # méthodes alternatives (--method)
          # post_install: ["claude setup"]     # commandes après installation
        dependencies:
          - { name: node, min_version: "18.0.0", install_hint: "https://nodejs.org" }
        run: claude
        args: []                 # arguments par défaut
        env: {}                  # variables d'environnement par défaut
        tags: [anthropic]
        installable: true        # false = listé mais non installable (SaaS/desktop)
        note: null               # explication affichée avec installable: false
        platforms: []            # linux | macos | windows (vide = tous)

Les chemins acceptent ~ et les variables d'environnement ($HOME, ${VAR}).
La configuration est **validée au démarrage** avec des messages précis
(agent 'x': 'run' is required when installable, champs inconnus rejetés,
doublons détectés).

---

## Ajouter un agent

Créez ~/.config/agent-manager/config.yaml (am config edit) ou un fichier
inclus (am config add mes-agents.yaml) puis :

    version: "1.0"
    agents:
      # paquet npm
      - name: mon-agent-npm
        display_name: "Mon Agent"
        install: { type: npm, package: mon-agent }
        dependencies:
          - { name: node, min_version: "18.0.0", install_hint: "https://nodejs.org" }
        run: mon-agent

      # paquet pip (virtualenv privé)
      - name: mon-agent-python
        display_name: "Mon Agent Python"
        install: { type: pip, package: mon-agent-python }
        dependencies:
          - { name: python, min_version: "3.10.0", install_hint: "https://python.org" }
        run: mon-agent

      # binaire GitHub Releases (asset choisi selon plateforme/arch)
      - name: mon-binaire
        display_name: "Mon Binaire"
        install:
          type: binary
          repo: owner/repo
          binary: mon-binaire            # nom de l'exécutable attendu
          checksum: null                 # ou "sha256:..."
        run: mon-binaire

      # binaire via URL directe
      - name: mon-binaire-2
        display_name: "Mon Binaire 2"
        install:
          type: binary
          url: "https://example.com/dl/mon-bin.tar.gz"
        run: mon-bin

      # script d'installation (téléchargé PUIS exécuté, jamais curl|sh)
      - name: mon-script
        display_name: "Mon Script"
        install:
          type: curl
          script: "https://example.com/install.sh"
        run: mon-script
        platforms: [linux, macos]

      # dépôt git + build
      - name: mon-git
        display_name: "Mon Git"
        install:
          type: git
          repo: "https://github.com/owner/repo"
          build: ["cargo", "build", "--release"]   # ou "make build" (chaîne)
          binary_path: target/release/mon-git      # copié dans le bin dir
        run: mon-git

      # application desktop / SaaS : listée mais non installable
      - name: mon-saas
        display_name: "Mon SaaS"
        installable: false
        note: "SaaS — voir https://example.com"

Puis : am config validate, am install mon-agent-npm, etc.

---

## Alias, groupes et mode interactif

    am start cc                     # alias -> claude-code
    am start group:dev              # démarre tout le groupe "dev" en arrière-plan
    am stop group:dev               # arrête tout le groupe
    am                              # shell interactif (rustyline) :
    #   am> inst<Tab>               # complétion Tab : commandes, agents, alias,
    #   am> install jcode           #   group:xxx, options (--background, ...)
    #   am> start jcode --background
    #   am> exit

Le shell interactif offre la **complétion par Tab** (commandes, noms
d'agents, alias, groupes, options) et un **historique persistant**
(flèches haut/bas, fichier history.txt dans le répertoire d'état).

---

## Gestion des processus

- **Avant-plan** (défaut) : la commande hérite de votre terminal ; am attend
  sa fin et propage son code de sortie. Ctrl-C interrompt l'agent.
- **Arrière-plan** (--background) : processus détaché (nouveau groupe de
  processus), PID enregistré dans state.json, stdout/stderr redirigés vers
  ~/.local/state/agent-manager/logs/<agent>.log. Si l'agent crashe au
  démarrage, am affiche la fin du log et échoue.
- **Arrêt** : am stop <agent> envoie SIGTERM (Windows : taskkill), attend
  stop_timeout_secs, puis SIGKILL (taskkill /F /T). --force court-circuite
  la phase gracieuse. Les PID périmés sont nettoyés automatiquement.
- Toutes les commandes exécutées sont journalisées avec horodatage dans
  <log_dir>/agent-manager.log (--verbose les affiche aussi).

---

## Sécurité

- Les scripts d'installation (curl) sont **téléchargés puis exécutés
  séparément** — jamais de curl pipé directement vers sh. --verbose affiche
  leur contenu, confirm_before_run demande confirmation.
- --dry-run simule n'importe quelle action sans rien écrire.
- URL limitées à https, http et file (tests locaux).
- Checksums sha256 vérifiés quand ils sont fournis dans la config.
- Rien n'est exécuté avec des privilèges élevés ; tout vit dans les
  répertoires utilisateur. Les archives sont extraites avec protection
  contre le path traversal (zip-slip).

---

## Tests

    cargo test          # tests unitaires + intégration (config, versions,
                        # dry-run, processus, doctor, installateurs)
    cargo test -- --nocapture

Les tests d'installation utilisent des *mocks* et le mode dry-run : aucun
réseau, aucune installation réelle. Les tests de processus spawnent
sleep/ping et vérifient le cycle démarrage → détection → arrêt.

---

## Complétions shell

    am completion bash       > completions/am.bash        # fournies dans completions/
    am completion zsh        > completions/_am
    am completion fish       > completions/am.fish
    am completion powershell > completions/_am.ps1

    # bash
    source completions/am.bash
    # zsh
    fpath+=(completions) && compinit
    # fish
    cp completions/am.fish ~/.config/fish/completions/am.fish

---

## Structure du projet

    src/
      main.rs          # point d'entrée (binaire am)
      lib.rs           # crate bibliothèque (testable)
      cli.rs           # définition clap des commandes
      app.rs           # contexte applicatif (config, chemins, état, log)
      config.rs        # schéma YAML, chargement, includes, fusion, validation
      catalog.rs       # catalogue fusionné : lookup, alias, groupes, recherche
      state.rs         # base locale JSON (installations, PID)
      runner.rs        # exécution de commandes (réelle / mock / dry-run)
      process.rs       # spawn détaché, détection, SIGTERM/SIGKILL, logs
      download.rs      # téléchargement, checksums, releases GitHub, archives
      deps.rs          # vérification des dépendances (node >= 18, ...)
      doctor.rs        # diagnostic d'environnement + réparations
      output.rs        # logger horodaté, tableaux, JSON, couleurs
      installers/      # npm, bun, pip, uv, cargo, go, curl, binary, git
      commands/        # une implémentation par commande
      repl.rs          # mode interactif
    config.yaml        # catalogue par défaut (~70 agents, embarqué)
    tests/             # tests d'intégration
    completions/       # scripts de complétion générés

---

## Limites et feuille de route

- Les applications desktop (Warp, openyak, Kun, cc-haha) et les SaaS (Devin,
  Amp, Junie, Cortex, Tabnine, Mentat) sont **listés** avec
  installable: false et un lien — ils ne sont pas installables localement.
- La mise à jour compare la version installée à la dernière connue (registry
  npm/PyPI/crates.io, tag GitHub) puis réinstalle.
- Pistes futures : plugins d'installation dynamiques, notifications Windows
  natives, intégration tmux, tests d'intégration avec des registres simulés.