342 lines
14 KiB
Markdown
342 lines
14 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) — gère aussi les agents externes (npm/pip/uv/cargo/bun, sinon suppression des fichiers) |
|
||
| 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 self-uninstall | désinstalle am et tout ce qu'il a créé (confirmation) |
|
||
| am | shell interactif : bannière, passerelle système, 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 (bannière style Hermes) :
|
||
❯ inst<Tab> # complétion Tab : commandes, agents, groupes, options
|
||
❯ install jcode
|
||
❯ exit # historique persistant (flèches haut/bas)
|
||
|
||
### 🐚 Passerelle système
|
||
|
||
Le prompt interactif est aussi une **passerelle vers votre shell
|
||
système** : toute saisie qui n'est pas une commande am est exécutée par le
|
||
shell actif. Le **shell par défaut de l'utilisateur est détecté au
|
||
démarrage et mis en évidence** dans la bannière (config
|
||
`settings.default_shell`, puis `SHELL`/`COMSPEC`, puis détection sur le
|
||
PATH — pwsh, powershell, cmd, bash, zsh, fish, sh, nu, elvish).
|
||
|
||
❯ ls # liste façon Nushell : tableau encadré (type, taille, date)
|
||
❯ dir # sur Windows, même affichage que ls
|
||
❯ ls src # un chemin précis — Tab complète fichiers et dossiers
|
||
❯ ps # liste des processus (pid, ppid, cpu, mem, threads)
|
||
❯ ls | where size > 1mb # filtre la dernière table (>, <, >=, <=, ==, !=, =~)
|
||
❯ ps | where name =~ am # =~ cherche dans le texte
|
||
❯ ls | get name # sélectionne une colonne
|
||
❯ cd <Tab> # complétion des dossiers uniquement, un niveau par Tab
|
||
❯ shell # affiche le shell courant + les shells disponibles
|
||
❯ shell bash # change le shell de la session
|
||
❯ !ls · !list # force l'exécution système (même nom qu'une commande am)
|
||
❯ cd ~/projets # change le répertoire de la session (persistant)
|
||
❯ /help # commandes slash : /help · /version · /exit · /shell <nom>
|
||
|
||
Le menu Tab affiche une **description** à côté de chaque candidat
|
||
(commandes et agents), comme Nushell, et **cycle** entre les propositions à
|
||
chaque Tab.
|
||
|
||
Pour rendre le choix permanent : `settings.default_shell: pwsh` dans
|
||
`config.yaml` (voir `am config path`).
|
||
|
||
---
|
||
|
||
## 🧹 Désinstallation propre
|
||
|
||
Une seule commande, sur tous les OS — elle arrête d'abord les agents en
|
||
arrière-plan, puis supprime les données, l'état (logs, historique), la
|
||
configuration, et enfin l'exécutable lui-même :
|
||
|
||
am self-uninstall # avec confirmation
|
||
am self-uninstall --yes # automatique, en une ligne
|
||
|
||
Sans le binaire (ou en dernier recours), supprimez les répertoires
|
||
qu'agent-manager possède :
|
||
|
||
# Linux
|
||
rm -rf ~/.local/share/agent-manager ~/.local/state/agent-manager ~/.config/agent-manager
|
||
|
||
# macOS
|
||
rm -rf "$HOME/Library/Application Support/agent-manager" "$HOME/.config/agent-manager"
|
||
|
||
# Windows — PowerShell
|
||
Remove-Item -Recurse -Force $env:LOCALAPPDATA\agent-manager, $env:APPDATA\agent-manager -ErrorAction SilentlyContinue
|
||
|
||
# Windows — cmd.exe (à ne PAS coller dans PowerShell : rmdir y est un
|
||
# alias de Remove-Item et le & final lance un job en arrière-plan)
|
||
rmdir /s /q "%LOCALAPPDATA%\agent-manager" & rmdir /s /q "%APPDATA%\agent-manager"
|
||
|
||
(Si vous utilisiez `AGENT_MANAGER_DATA`/`AGENT_MANAGER_STATE`/`AGENT_MANAGER_CONFIG_DIR`,
|
||
supprimez aussi ces emplacements.)
|
||
|
||
---
|
||
|
||
## ⚙️ 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).
|