🚀 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 ask ""	langage naturel → commande(s) am : règles locales hors-ligne, raffinement LLM optionnel (settings.ask), confirmation avant exécution — ex: am ask "installe claude et lance-le"
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 providers list / add / set-token	registre LLM centralisé : base_url, modèles par provider, clé dans le trousseau (jamais en clair, résolue via @secret)
am catalog update / add	catalogue distant : rafraîchit l'officiel ou ajoute un catalogue d'équipe
am registry publish/search/install	registre communautaire de catalogues (Gitea) : publication, recherche, installation avec checksum sha256 vérifié et décision de confiance explicite
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 <cmd...> --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

📁 Où et comment agent-manager installe et gère les agents

am ne touche jamais au système : chaque agent est installé dans un répertoire utilisateur isolé, et ses exécutables (ou shims) sont centralisés dans un bin/ commun que am met automatiquement sur le PATH au lancement.

Plateforme	Répertoire de l'agent	Dossier bin partagé	Fichier d'état	Configuration utilisateur
Linux	~/.local/share/agent-manager/agents/<agent>/	~/.local/share/agent-manager/bin/	~/.local/state/agent-manager/state.json	~/.config/agent-manager/config.yaml
macOS	~/Library/Application Support/agent-manager/agents/<agent>/	~/Library/Application Support/agent-manager/bin/	~/Library/Application Support/agent-manager/state.json	~/.config/agent-manager/config.yaml
Windows	%LOCALAPPDATA%\agent-manager\agents\<agent>\	%LOCALAPPDATA%\agent-manager\bin\	%LOCALAPPDATA%\agent-manager\state.json	%APPDATA%\agent-manager\config.yaml

Les variables d'environnement AGENT_MANAGER_DATA, AGENT_MANAGER_STATE et AGENT_MANAGER_CONFIG_DIR peuvent déplacer ces emplacements. Le répertoire d'installation est aussi configurable via settings.install_dir et celui des logs via settings.log_dir.

Cycle d'installation (am install <agent>)

1. Résolution du catalogue — am fusionne le catalogue embarqué (72 agents) avec ~/.config/agent-manager/config.yaml et un éventuel ./agent-manager.yaml. Vos définitions remplacent les entrées par défaut du même nom.
2. Vérification des dépendances — les outils requis (node, python, uv, cargo, go, bun, git...) sont détectés sur le PATH. S'il en manque, am détecte l'OS et propose la commande d'installation (scoop, winget, apt, dnf, pacman, brew...). Avec --yes ou settings.auto_install_deps: true, il peut l'exécuter à votre place.
3. Choix de la méthode — chaque agent déclare une méthode principale et des alternatives. --method <nom> force le choix ; sinon am prend la première disponible. Pour am update, c'est la méthode utilisée lors de l'installation initiale qui est reconstruite.
4. Exécution de l'installateur — selon le type, les commandes réelles lancées sont :

Méthode	Ce que am exécute localement	Où ça atterrit
npm	npm install -g --prefix <root> <package>	binaires dans <root>/bin/, liens ou copie dans bin/
bun	BUN_INSTALL=<root> bun install -g <package>	binaires dans <root>/bin/, shims dans bin/
pip	python -m venv <root>/venv puis <venv>/bin/pip install --upgrade <package>	exécutables dans <root>/venv/bin/
uv	uv venv --python 3.13 <root>/venv puis uv pip install --python <venv>/bin/python <package>	exécutables dans <root>/venv/bin/
cargo	cargo install --root <root> <crate>	binaires dans <root>/bin/
go	GOBIN=<bindir> go install <module>@latest	binaire directement dans bin/
curl	télécharge le script, l'affiche en --verbose, puis l'exécute avec sh <script> dans <root>/	le script gère son propre déploiement ; am repère les binaires résultants
binary	télécharge un asset release (url ou repo), vérifie le sha256 si fourni, extrait dans <root>/dist/, copie dans bin/	binaire unique dans bin/
git	git clone --depth 1 <repo> <root>/repo, exécute les commandes build, puis copie binary_path dans bin/ ou crée un shim	bin/<agent> ou shim

5. Post-installation — am exécute les commandes post_install déclarées dans la fiche, avec <bindir> en tête du PATH.
6. Détection de version — am lance <binaire> --version (puis -V) pour enregistrer la version réelle.
7. Enregistrement — une entrée est écrite dans state.json (name, version, method, install_dir, bins, run, installed_at, pid, etc.).

Cycle de gestion (am start / stop / update / uninstall)

• Démarrage — am start <agent> lit state.json pour retrouver le binaire et la commande run configurée. En arrière-plan (--background), le PID est enregistré dans state.json et la sortie est redirigée vers <log_dir>/<agent>.log.
• Arrêt — am stop envoie SIGTERM, attend settings.stop_timeout_secs (5 s par défaut), puis SIGKILL si besoin. Le PID est effacé de state.json.
• Mise à jour — am update <agent> détermine la dernière version disponible (registre npm/PyPI/cargo/release), crée une sauvegarde (am update --rollback), réinstalle avec la même méthode et met à jour state.json. Les versions épinglées (pin_version) sont respectées.
• Désinstallation — am uninstall <agent> arrête le processus, supprime <root>/, supprime les binaires de bin/ et efface l'entrée de state.json. --purge efface aussi les logs et retire la définition du fichier de config utilisateur.

🚀 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)
am web [--port ]	dashboard web local en lecture seule (127.0.0.1) : vue d'ensemble, graphiques, sessions, événements, projets — API JSON /api/* avec les mêmes contrats que les sorties --json

🎯 Personnaliser

Commande	Rôle
am favorite / am unfavorite	étoile ★ dans am list, am status et am info (persistante)
am note <texte…>	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 serve --token [--port ]	API HTTP + WebSocket authentifiée pour piloter am à distance (stats, run, start, stop, ask…) — rate limiting par IP, TLS via reverse proxy
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
--lang <fr|en>	langue des messages : fr (défaut) ou en — AM_LANG/LANG lus sinon
-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 web                    # dashboard web local (ouvre le navigateur) : http://127.0.0.1:7878/
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
❯ web                     # ... et le dashboard web aussi (am web --port pour changer le port)
❯ 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
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.