Aller au contenu
Bosco

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 .deb ou 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 (~/.claude par 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é par corepack 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'AppImage

L'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 install

make install installe les dépendances et les skills épinglés par skills-lock.json.

Lancer le service

make start

make 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 bosco

make 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 retirer

make 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

QuoiOù
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 directsettings.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

VariableDéfautRôle
BOSCO_PORT4870Port du service, toujours sur 127.0.0.1
BOSCO_DATA_DIR~/.local/share/boscoDossier des données
BOSCO_PHONE_PORTBOSCO_PORT + 1Port HTTPS de l'accès du téléphone, ouvert seulement après activation
BOSCO_PHONE_HOSTadresse du poste sur le réseau localAdresse annoncée au téléphone

Toutes sont validées au démarrage : une valeur invalide empêche le service de démarrer.

Sur cette page