281 lines
11 KiB
Markdown
281 lines
11 KiB
Markdown
# 🚀 agent-manager — vos agents IA, gérés comme des apps
|
|
|
|
**am** liste, installe, démarre, met à jour et désinstalle vos agents IA de
|
|
coding (Claude Code, Codex, Aider, jcode, Prime Agent… **72 agents connus**)
|
|
en une ligne de commande — avec la gestion des dépendances (Node.js, Python,
|
|
Go, Rust…) prise en charge pour vous.
|
|
|
|
> ✅ Rust · ✅ Windows, Linux, macOS · ✅ aucune dépendance runtime
|
|
|
|
---
|
|
|
|
## ✨ Pourquoi am ?
|
|
|
|
- 🗂️ **Catalogue de 72 agents prêts à l'emploi** — descriptions, méthodes
|
|
d'installation, dépendances et commandes de démarrage déjà configurées.
|
|
- 📦 **9 méthodes d'installation** — npm, pip, uv, cargo, go, bun, script
|
|
d'installation, binaire (GitHub Releases/Gitea) et dépôt git — toujours
|
|
dans un répertoire local, jamais dans le système.
|
|
- 🧩 **Dépendances gérées pour vous** — avant d'installer un agent, am
|
|
vérifie les outils requis et, s'il en manque, **détecte votre OS** et
|
|
propose la commande exacte (scoop/winget, apt/dnf/pacman, brew) — il peut
|
|
même l'exécuter à votre place.
|
|
- 🚦 **Gestion des processus** — démarrage en avant-plan ou détaché
|
|
(--background) avec PID enregistré et logs ; arrêt propre SIGTERM puis
|
|
SIGKILL.
|
|
- ⚡ **Rapide** — sondes de version en parallèle + cache : un am list
|
|
à chaud prend ~25 ms.
|
|
- 🧭 **Shell interactif** avec complétion **Tab** et historique.
|
|
- 🔒 **Sûr** — mode --dry-run universel, checksums sha256, confirmations
|
|
avant les scripts d'installation, journalisation horodatée.
|
|
|
|
---
|
|
|
|
## ⚡ Installation — 30 secondes
|
|
|
|
**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
|
|
(statique sous Linux : compatible toutes les distributions, Debian 12 et
|
|
antérieures comprises) et l'ajoute à votre PATH. Sans binaire pour votre
|
|
plateforme, il compile automatiquement depuis les sources.
|
|
|
|
> 🔄 **Mise à jour** : relancez simplement la même commande.
|
|
|
|
---
|
|
|
|
## 🎬 Vos 3 premières commandes
|
|
|
|
am list # vos agents installés (et ceux détectés sur le PATH)
|
|
|
|
NAME VERSION STATUS SOURCE PATH
|
|
------------------------------------------------
|
|
Claude Code 2.1.112 external external C:\\Users\\bruno\\.local\\bin\\claude.exe
|
|
jcode 0.76.0 external external C:\\Users\\bruno\\AppData\\Local\\jcode\\bin\\jcode.exe
|
|
|
|
am install jcode # installe un agent (dépendances vérifiées d'abord)
|
|
|
|
installing jcode (type=binary repo=1jehuang/jcode)…
|
|
installed jcode (v0.76.0) in ~/.local/share/agent-manager/agents/jcode
|
|
|
|
am start jcode # le lance en avant-plan (--background pour détacher)
|
|
|
|
---
|
|
|
|
## 📚 Aide-mémoire des commandes
|
|
|
|
### 🔍 Découvrir
|
|
|
|
| Commande | Rôle |
|
|
|----------|------|
|
|
| am list | agents installés (gérés + détectés sur le PATH) |
|
|
| am list --all | tout le catalogue, avec l'état de chacun |
|
|
| am search <mot-clé> | recherche par nom, description, catégorie, tag |
|
|
| am info <agent> | fiche détaillée (installation, dépendances, site…) |
|
|
| am status [agent] | état, version, PID, logs |
|
|
|
|
**Statuts** : 🟢 running · 🔵 installed (géré par am) · 🟡 external (trouvé
|
|
sur le PATH) · ⚪ not-installed · 🔴 not-installable (SaaS/desktop)
|
|
|
|
### 📦 Installer et gérer
|
|
|
|
| Commande | Rôle |
|
|
|----------|------|
|
|
| am install <agent> | installe (dépendances vérifiées et proposées) |
|
|
| am install <agent> --method pip | choisit une méthode d'installation |
|
|
| am update <agent> | met à jour vers la dernière version connue |
|
|
| am uninstall <agent> | désinstalle et nettoie (--purge : logs + config) |
|
|
| am export / am import | sauvegarde et restaure config + état |
|
|
|
|
### 🚀 Exécuter
|
|
|
|
| Commande | Rôle |
|
|
|----------|------|
|
|
| am start <agent> | avant-plan (Ctrl-C pour quitter) |
|
|
| am start <agent> --background --env KEY=VALEUR | détaché, PID et log gérés |
|
|
| am stop <agent> | arrêt gracieux puis forcé (--force : immédiat) |
|
|
| am restart <agent> | arrête puis redémarre |
|
|
| am run <agent> [args…] | exécution directe, sans gestion de processus |
|
|
|
|
### 🧰 Système
|
|
|
|
| Commande | Rôle |
|
|
|----------|------|
|
|
| am doctor | vérifie outils, config, chemins — avec commandes d'installation |
|
|
| am doctor --fix | répare ce qui peut l'être, propose d'installer les outils manquants |
|
|
| am config show / edit / add | gère votre configuration |
|
|
| am completion <shell> | script de complétion (bash, zsh, fish, powershell) |
|
|
| am self-update | met à jour am lui-même (si configuré) |
|
|
| am | shell interactif avec Tab et historique |
|
|
|
|
---
|
|
|
|
## 🧩 Dépendances : am s'en occupe
|
|
|
|
Avant chaque installation, am vérifie les **prérequis** déclarés pour
|
|
l'agent (ex. node >= 18 pour Claude Code). S'il manque un outil :
|
|
|
|
1. il **détecte votre système** — Windows (scoop puis winget), Linux
|
|
(apt / dnf / pacman / apk selon la distribution), macOS (brew) ;
|
|
2. il **propose la commande exacte** et peut l'exécuter à votre place
|
|
(confirmation demandée, ou --yes) :
|
|
|
|
$ am install claude-code
|
|
dependency 'node' is missing
|
|
Run the detected installer for Windows? -> scoop install nodejs-lts [y/N]
|
|
|
|
Si vous refusez, l'installation s'arrête avec le mode d'emploi :
|
|
|
|
error: agent 'claude-code' has unmet dependencies:
|
|
- node: not found on PATH (minimum: 18.0.0)
|
|
on Windows: scoop install nodejs-lts | winget install OpenJS.NodeJS.LTS
|
|
|
|
am doctor affiche la même aide pour tous les outils de l'environnement.
|
|
Les dépendances des paquets (les modules npm/pip de l'agent lui-même) sont,
|
|
elles, installées automatiquement par npm/pip/cargo dans un **répertoire
|
|
local isolé** (virtualenv privé, --prefix npm, GOBIN local…) — votre
|
|
système n'est jamais touché.
|
|
|
|
---
|
|
|
|
## 🛠️ Options globales
|
|
|
|
Disponibles avant **ou après** la sous-commande.
|
|
|
|
| Option | Effet |
|
|
|--------|-------|
|
|
| -y, --yes | répond oui à toutes les confirmations |
|
|
| --dry-run | simule sans rien modifier (idéal pour essayer) |
|
|
| --json | sortie JSON stable pour vos scripts |
|
|
| -v, --verbose | affiche chaque commande exécutée |
|
|
| -q, --quiet | uniquement les erreurs |
|
|
| --no-color | désactive les couleurs |
|
|
| -c, --config <fichier> | configuration alternative |
|
|
|
|
---
|
|
|
|
## 👥 Groupes, alias et shell interactif
|
|
|
|
am start cc # alias (cc -> claude-code)
|
|
am start group:dev # démarre tout un groupe en arrière-plan
|
|
am stop group:dev
|
|
|
|
am # shell interactif :
|
|
am> inst<Tab> # complétion Tab : commandes, agents, groupes, options
|
|
am> install jcode
|
|
am> exit # historique persistant (flèches haut/bas)
|
|
|
|
---
|
|
|
|
## ⚙️ Personnalisation
|
|
|
|
### Fichiers de configuration (par priorité)
|
|
|
|
1. --config <fichier>
|
|
2. ./agent-manager.yaml (répertoire courant)
|
|
3. ~/.config/agent-manager/config.yaml
|
|
4. catalogue embarqué (72 agents)
|
|
|
|
Vos définitions **complètent ou surchargent** le catalogue par nom.
|
|
|
|
### Ajouter votre agent
|
|
|
|
# ~/.config/agent-manager/config.yaml (ou am config add mon-fichier.yaml)
|
|
version: "1.0"
|
|
agents:
|
|
- name: mon-agent
|
|
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
|
|
|
|
Autres méthodes : pip/uv (virtualenv privé), cargo, go, bun, binaire depuis
|
|
Gitea/GitHub Releases (repo: owner/repo), URL directe, script d'installation
|
|
(type: curl) et dépôt git avec build (build + binary_path). Les chemins
|
|
acceptent ~ et les variables d'environnement ($HOME, ${VAR}) ; includes
|
|
multi-fichiers pris en charge ; configuration validée au démarrage.
|
|
|
|
---
|
|
|
|
## 🔒 Sécurité
|
|
|
|
- les scripts d'installation sont **téléchargés puis exécutés séparément** —
|
|
jamais de curl pipé vers sh ; --verbose les affiche ;
|
|
- **--dry-run** simule n'importe quelle action sans rien écrire ;
|
|
- checksums **sha256** vérifiés quand ils sont fournis ;
|
|
- URL limitées à https/http/file ; extraction d'archives protégée contre le
|
|
path traversal ;
|
|
- tout vit dans vos répertoires utilisateur ; rien n'est exécuté avec des
|
|
privilèges élevés.
|
|
|
|
---
|
|
|
|
## 🖥️ Complétions shell
|
|
|
|
am completion bash > completions/am.bash
|
|
am completion zsh > completions/_am
|
|
am completion fish > completions/am.fish
|
|
am completion powershell > completions/_am.ps1
|
|
|
|
---
|
|
|
|
## ❓ FAQ
|
|
|
|
**Où sont installés les agents ?**
|
|
~/.local/share/agent-manager/agents (Linux), %LOCALAPPDATA%\\agent-manager\\agents
|
|
(Windows) — l'état et les logs dans ~/.local/state/agent-manager (Linux) ou
|
|
%LOCALAPPDATA%\\agent-manager (Windows).
|
|
|
|
**Comment mettre à jour am ?** Relancez l'installeur one-liner (ou
|
|
am self-update si le dépôt de release est configuré).
|
|
|
|
**Comment désinstaller am ?** Supprimez le binaire et le répertoire
|
|
d'état ; les agents installés restent utilisables en les supprimant avec
|
|
am uninstall avant.
|
|
|
|
**Pourquoi le binaire Linux est statique ?** Pour fonctionner partout,
|
|
Debian 12 (glibc 2.36) comprise, sans dépendance système.
|
|
|
|
**Un agent me demande une clé API.** am ne gère pas les secrets : il lance
|
|
l'agent, qui fera sa propre configuration. Passez des variables avec
|
|
--env KEY=VALEUR si besoin.
|
|
|
|
---
|
|
|
|
## 🧑💻 Pour les développeurs
|
|
|
|
### Compiler et tester
|
|
|
|
git clone https://git.dracodev.net/Projets/agent-manager.git
|
|
cd agent-manager
|
|
cargo build --release # binaire dans target/release/am
|
|
cargo test # 45+ tests (config, processus, dry-run, complétion…)
|
|
|
|
### Architecture
|
|
|
|
src/
|
|
cli.rs # commandes clap
|
|
config.rs # schéma YAML, includes, fusion, validation
|
|
catalog.rs # catalogue : lookup, alias, groupes, recherche
|
|
deps.rs # vérification des dépendances (min_version, OS)
|
|
toolchain.rs # détection OS + commandes d'installation (scoop/apt/…)
|
|
probe.rs # détection d'agents externes (parallèle + cache)
|
|
installers/ # npm, pip, uv, cargo, go, bun, curl, binary, git
|
|
process.rs # spawn détaché, signaux, logs
|
|
state.rs # base locale JSON (installations, PID)
|
|
runner.rs # exécution de commandes (réelle, mock, dry-run)
|
|
|
|
### Publier une release
|
|
|
|
Les binaires des releases sont construits en conteneur : Windows (MSVC)
|
|
nativement, **Linux en statique musl** (jamais de binaire glibc récent —
|
|
voir l'erreur GLIBC). La procédure complète est dans
|
|
[RELEASING.md](RELEASING.md).
|