# 🚀 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 | recherche fuzzy : tolère les fautes de frappe, classe par pertinence, propose « vouliez-vous dire » | | am suggest | recommande un agent pour une demande en langage naturel (tags + usage réel) | | am info | 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 | catalogue distant : rafraîchit l'officiel ou ajoute un catalogue d'équipe | | am audit | qui a modifié quoi, quand (checksums config + journal) | | am sessions --export | export d'une session (métadonnées + commandes + extrait de log) | | am sessions --retention | purge des sessions terminées au-delà de N jours | | am init --template | génère une config pré-remplie (web, python, rust, cli) | | am doctor --watch | vérifications périodiques de l'environnement + alerte en cas de panne | | am monitor [--json] | TUI temps réel des processus gérés (CPU/RSS/uptime) + alertes de seuils | | am stats --costs | coût estimé par agent (tokens in/out, $) — modèles de prix configurables | | am sync [--message ] | sauvegarde git de l'état (state.json, journal, historique) — secrets exclus | | am migrate export/import | bundle de transfert machine A → B (config + état + historique + backups) | | am service install --autostart | service système (systemd / launchd / tâche Windows) + démarrage auto | | am schedule add --at HH:MM | planifie une commande am (ex: update --all) ; list / remove / run | | am start group:dev --parallel | orchestration de groupes : ordre, --parallel, attente de santé (healthcheck) | | am run --container | exécute l'agent dans son profil conteneur (docker/podman) | **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 | installe (dépendances vérifiées et proposées) | | am install --method pip | choisit une méthode d'installation | | am update | 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 | 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 --background --env KEY=VALEUR | détaché, PID et log gérés ; --env NOM=@secret injecte un secret du trousseau | | am stop | arrêt gracieux puis forcé (--force : immédiat) | | am restart | arrête puis redémarre | | am run [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 history 12..25 --save · am playbook | exporte une plage en playbook YAML et la rejoue pas à pas ({{var}}) | | am lab --agents a,b --task [--parallel] [--json] | benchmark : même tâche sur plusieurs agents (durée, exit, coût) — tâches versionnables dans /lab/ | | am plugins [--test ] | scripts d'extension sur les événements (on_install/on_start/on_stop/on_update), contrat JSON stdin/stdout, timeout — exemples dans examples/plugins/ | | am logs --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 / am unfavorite | étoile ★ dans am list, am status et am info (persistante) | | am note | note libre affichée dans am info (am note : affiche) | | am tag … / am untag | 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 --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 --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 | ouvre le répertoire d'installation dans l'explorateur | | am completion [--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 | 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 # 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 # 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 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 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).