Installation
Installer Bosco depuis une release ou depuis son dépôt, le premier lancement, le service de l'utilisateur et le serveur MCP.
Bosco s'installe de deux façons :
- depuis une release, le plus simple : l'application du poste (paquet
.debou AppImage) embarque le service, l'interface et Node 26. Rien à construire ; - depuis le dépôt Git : le service tourne avec le Node du poste et sert son interface dans le navigateur. C'est la voie pour macOS, pour développer Bosco ou pour le faire tourner comme service systemd.
Dans les deux cas, Bosco tourne sur la boucle locale du poste et garde ses données dans ~/.local/share/bosco : passer de l'un à l'autre ne perd rien. L'application Android est facultative.
Prérequis
- Linux pour tout Bosco. Sous macOS, le service et l'interface marchent dans le navigateur, depuis le dépôt, sans application du poste.
- Claude Code installé, avec au moins un profil (
~/.claudepar défaut). - Docker, seulement pour le bac à sable. Sans Docker, tout le reste marche.
- Depuis le dépôt seulement : Node 26 (la version de
.nvmrc,nvm useà la racine : pnpm refuse d'installer avec une autre version) et pnpm 12, activé parcorepack enable.
Depuis une release
Télécharge le paquet .deb ou l'AppImage de la dernière version depuis la page Télécharger, puis :
sudo apt install ./bosco-desktop_*_amd64.deb # paquet .deb : Bosco rejoint le menu des applications
chmod +x bosco-desktop_*_x86_64.AppImage && ./bosco-desktop_*_x86_64.AppImage # ou l'AppImageL'application démarre son service sur http://127.0.0.1:4870 et ouvre sa fenêtre. Passe ensuite au premier lancement.
Depuis le dépôt
Récupérer le dépôt et ses dépendances
git clone https://github.com/fpasquet/bosco.git ~/www/bosco
cd ~/www/bosco
nvm use
corepack enable
make installmake install installe les dépendances et les skills épinglés par skills-lock.json.
Lancer le service
make startmake start construit chaque paquet, puis lance le service sur http://127.0.0.1:4870 et ouvre la vue d'ensemble dans le navigateur. Le port se change avec BOSCO_PORT, mais le service n'écoute jamais ailleurs que sur 127.0.0.1.
Premier lancement
Choisir les profils à surveiller
Au premier lancement, Bosco affiche « Bienvenue dans Bosco » et liste les profils Claude Code trouvés dans ton dossier personnel (~/.claude, ~/.claude-perso…), avec la date de leur dernière session. Tous sont cochés : décoche ceux que Bosco ne doit pas lire, puis « Surveiller ces profils ». Rien n'est lu avant ce clic.
Bosco importe alors les sessions des 30 derniers jours dans l'historique, ou tout l'historique encore présent dans les profils si tu le choisis. Il les lit sans les modifier. La période se change ensuite dans Réglages › Données.
Retrouver tes projets
Chaque dépôt git où une session a tourné devient un projet, sans rien faire : la barre latérale et l'usage se rangent aussitôt par projet. Les dossiers sans git restent dans les suggestions de la page Projets. Le détail est dans Projets et groupes.
Installer le suivi en direct
Sans suivi en direct, Bosco voit les sessions mais ne sait pas quand l'une t'attend. Ouvre Réglages › Sources, puis « Installer » sur la ligne du profil. Bosco ajoute ses hooks HTTP aux réglages du profil (settings.json), en gardant une copie des réglages actuels si tu laisses la case cochée. Ouvre ensuite une session Claude Code dans ce profil : la vérification passe à « Signal reçu d'une session ouverte ».
Le détail est dans Réglages.
En faire un service de l'utilisateur
Pour que Bosco démarre avec ta session Linux, sans terminal ouvert :
make service-install
systemctl --user daemon-reload && systemctl --user enable --now boscomake service-install construit Bosco, puis écrit ~/.config/systemd/user/bosco.service. Le service lance bosco start --no-open avec le Node qui a servi à l'installer, et redémarre seul en cas d'échec. Il reste lié au dépôt : après une mise à jour du dépôt, relance make build puis systemctl --user restart bosco.
L'application du poste embarque son propre service. Si elle trouve le service systemd déjà lancé, elle propose de s'y relier ou de le remplacer.
Brancher le serveur MCP de Bosco
Bosco expose un serveur MCP local, bosco, sur http://127.0.0.1:4870/mcp. Les agents y lisent le contexte de leur projet (instructions des groupes, décisions, place dans l'architecture) et y proposent des décisions. Pour l'ajouter à un profil Claude Code :
make mcp-install # profil ~/.claude
make mcp-install PROFILE=~/.claude-perso # un autre profil
make mcp-install-dev # pointé sur make dev (port 4880, données dans .data/)
make mcp-remove # le retirermake mcp-install appelle claude mcp add --scope user dans le profil choisi : le serveur vaut pour tous les projets de ce profil. Le détail des outils est dans Canal et serveur MCP.
Où sont les données
| Quoi | Où |
|---|---|
| Base, réglages, secret des hooks, bacs à sable | ~/.local/share/bosco (ou BOSCO_DATA_DIR) |
Service en développement (make dev) | .data/ du dépôt, port 4880 |
| Unité systemd | ~/.config/systemd/user/bosco.service |
| Hooks du suivi en direct | settings.json de chaque profil surveillé |
Le dossier ~/.local/share/bosco est le même pour le service lancé depuis le dépôt et pour l'application du poste. Ne le supprime pas à la main : il contient l'historique que Bosco garde même quand Claude Code efface ses transcripts après 30 jours.
Variables d'environnement
| Variable | Défaut | Rôle |
|---|---|---|
BOSCO_PORT | 4870 | Port du service, toujours sur 127.0.0.1 |
BOSCO_DATA_DIR | ~/.local/share/bosco | Dossier des données |
BOSCO_PHONE_PORT | BOSCO_PORT + 1 | Port HTTPS de l'accès du téléphone, ouvert seulement après activation |
BOSCO_PHONE_HOST | adresse du poste sur le réseau local | Adresse annoncée au téléphone |
Toutes sont validées au démarrage : une valeur invalide empêche le service de démarrer.
Télécharger
Les applications de Bosco pour Linux et Android, tirées de la dernière release publiée sur GitHub, et comment vérifier un téléchargement.
Application du poste (Linux)
Le paquet .deb et l'AppImage de Bosco, leurs mises à jour, la barre système, les notifications natives, et leur construction depuis le dépôt.