bruno
d9ffc34156
Axe 8 (sécurité) : - am audit : checksums SHA-256 des configs (embarquée, utilisateur, locale) stockés dans state.json, croisement avec events.jsonl pour dater les changements, détection des modifications manuelles hors de am (statut MANUAL), rapport lisible + --json stable (contrat) - backup automatique avant chaque am update (agent ou --all) : état + config utilisateur + répertoires d'installation + shims dans <state>/backups/<ts>/ avec manifest.json - am update --rollback [point] : restaure le dernier backup (ou un id précis, préfixe accepté), arrête les agents concernés d'abord, événement EventKind::Rollback journalisé - am update --rollback list : liste les points de restauration - rétention settings.backups_keep (défaut 5) appliquée après chaque backup - événements EventKind::Backup / EventKind::Rollback pour l'audit REPL : commande audit + update --rollback (parse, complétion), help specs, tip cheat sheet, man pages régénérées (50 pages). Version 0.4.6, ROADMAP cases cochées, 272 tests verts.
407 lines
18 KiB
Markdown
407 lines
18 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 fuzzy : tolère les fautes de frappe, classe par pertinence, propose « vouliez-vous dire » |
|
||
| am suggest <requête> | recommande un agent pour une demande en langage naturel (tags + usage réel) |
|
||
| am info <agent> | fiche détaillée (installation, dépendances, site…) |
|
||
| am status [agent] | état, version, PID, logs |
|
||
| am models | inventaire des modèles locaux (ollama, llama.cpp, LM Studio) |
|
||
| am models --prune | purge des modèles inutilisés (--dry-run : simulation) |
|
||
| am catalog update / add <url> | catalogue distant : rafraîchit l'officiel ou ajoute un catalogue d'équipe |
|
||
| am audit | qui a modifié quoi, quand (checksums config + journal) |
|
||
| am update --rollback | annule la dernière mise à jour (backup automatique avant chaque update) |
|
||
|
||
**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 config set settings.default_shell pwsh | modifie la configuration sans éditeur |
|
||
| am alias add cc claude-code | raccourci pour un agent (list / remove aussi) |
|
||
| am init | génère un agent-manager.yaml selon la pile du projet (Node/Rust/Python…) |
|
||
| 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) — sans argument, lance l'agent par défaut du projet |
|
||
| am start <agent> --background --env KEY=VALEUR | détaché, PID et log gérés ; --env NOM=@secret injecte un secret du trousseau |
|
||
| 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 |
|
||
|
||
### 📊 Observer & retrouver
|
||
|
||
| Commande | Rôle |
|
||
|----------|------|
|
||
| am stats [agent] --period 7d/30d/90d | statistiques d'utilisation : lancements, durées, échecs, barres ASCII |
|
||
| am top --period | les 10 agents les plus utilisés |
|
||
| am report --last-week / --last-month | digest markdown (lancements, échecs, changements, sessions) |
|
||
| am log [agent] --kind --since --follow | journal des événements : tout ce que am a fait, en direct avec --follow |
|
||
| am timeline --project --since | vue chronologique unifiée (journal + commandes du REPL) |
|
||
| am projects [nom] | quel agent travaille sur quel projet (agent dominant, sessions, durées) |
|
||
| am sessions [agent] --status --show --resume | registre des sessions + reprise d'une session arrêtée |
|
||
| am history --search --failed --rerun N | historique des commandes (am + shell), filtrable et réexécutable |
|
||
| am logs <agent> --follow | tail du log d'un agent, en direct |
|
||
| am dashboard | tableau de bord TUI temps réel : vue d'ensemble, activité, stats, sessions, projets (Tab/←/→ : onglets, j/k : défilement, q : quitter) |
|
||
|
||
### 🎯 Personnaliser
|
||
|
||
| Commande | Rôle |
|
||
|----------|------|
|
||
| am favorite <agent> / am unfavorite | étoile ★ dans am list, am status et am info (persistante) |
|
||
| am note <agent> <texte…> | note libre affichée dans am info (am note <agent> : affiche) |
|
||
| am tag <agent> <mot>… / am untag <agent> <mot> | tags personnels, filtrables avec am search --tag |
|
||
| am tags [agent] | liste les tags personnels et les agents qui les portent |
|
||
| am profile list / show | profils d'environnement (env + args + agent par défaut) |
|
||
| am start <agent> --profile dev | lance un agent avec un profil ; am start --profile dev utilise l'agent du profil |
|
||
| am man [commande] --output man/ | génère les pages de manuel (am.1 + une page par commande) |
|
||
|
||
### 🧰 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 watch <agent> --restart --notify | supervise un agent et le relance en cas de crash |
|
||
| am secret set NOM --agent A --value … / list / unset | secrets dans le trousseau du système (jamais en clair) |
|
||
| am config show / edit / add / set | gère votre configuration (hooks on_start/on_stop/… dans settings.hooks) |
|
||
| am open <agent> | ouvre le répertoire d'installation dans l'explorateur |
|
||
| am completion <shell> [--installed] | script de complétion (bash, zsh, fish, powershell, elvish) ; --installed complète dynamiquement les agents installés, alias et groupes |
|
||
| 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 start cc --profile dev # profil d'environnement : env + args injectés
|
||
|
||
am dashboard # TUI temps réel : toute l'activité d'un coup d'œil
|
||
am favorite cc && am tag cc python # personnalisez votre parc
|
||
am search --tag python # retrouvez les agents que vous avez tagués
|
||
|
||
am # shell interactif (bannière style Hermes) :
|
||
❯ inst<Tab> # complétion Tab : commandes, agents installés, groupes, options
|
||
❯ install jcode
|
||
❯ dashboard # le dashboard se lance aussi depuis le REPL
|
||
❯ 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 — menu interactif façon Nushell
|
||
❯ 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>
|
||
|
||
La complétion Tab est un **menu interactif façon Nushell** : une
|
||
correspondance unique est insérée directement ; plusieurs correspondances
|
||
ouvrent un menu sous la ligne avec le **premier choix en surbrillance**, et
|
||
chaque Tab déplace la surbrillance vers le choix suivant (Shift+Tab vers
|
||
l'arrière). **Entrée** valide le choix, **Échap** ferme le menu, les flèches
|
||
↑/↓ naviguent et continuer à taper filtre la liste en direct. Le menu
|
||
affiche une **description** à côté de chaque candidat (commandes et agents)
|
||
et suit la palette du thème actif.
|
||
|
||
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).
|
||
|
||
**Où vivent les statistiques, les sessions et l'historique ?** Dans le
|
||
répertoire d'état, au format JSON lisible et 100 % local : events-YYYYMM.jsonl
|
||
(journal de chaque action), sessions.json (registre des sessions),
|
||
history/ (historique structuré du shell), projects.json (agrégats par
|
||
projet). Interrogeables avec am stats, am top, am log, am timeline,
|
||
am projects, am sessions et am history.
|
||
|
||
**Où vivent les secrets ?** Dans le trousseau de votre système (Windows
|
||
Credential Manager, macOS Keychain, Linux Secret Service) — jamais dans la
|
||
configuration ni dans les logs. Injection avec --env NOM=@secret.
|
||
|
||
**Puis-je automatiser des actions ?** Oui : hooks on_install/on_start/on_stop/
|
||
on_update dans settings.hooks (globaux) ou dans le profil d'un projet, et
|
||
am watch pour superviser un agent avec redémarrage automatique.
|
||
|
||
**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).
|