claude-cluster docs1.10.1
User guideGuide utilisateur

SettingsRéglages

The settings page, config.toml, dangerous values, protected settings, the Services tab and searching a setting.La page de réglages, config.toml, valeurs dangereuses, réglages protégés, l'onglet Services et la recherche d'un réglage.

1. The settings pageLa page de réglages

F9 (or the palette, Settings; the ⚙ of the web page) opens a page like a BIOS setup: one tab per section (Interface, Agent, Commands, Global session, Sessions, Voice, Keys, Web, Attachments, Notifications, Orchestrator, Services...), the help of the selected option on the right.

  • Terminal: ↑↓ select, ←→ or Enter change a choice, toggle or number, Enter edits a text, Tab / Shift+Tab change section, Ctrl+S saves (the page stays), F10 saves and leaves, Esc leaves (unsaved changes: Save the changes?). * marks the changed ones.
  • Changes are written in config.toml (only the values, its comments kept) and reloaded live. Options marked applied at the next start need a restart. Every option is listed in the settings reference, and its default in the configuration reference.
  • Profiles ([profiles.<name>]), own providers ([providers.<name>]) and own styles ([styles.<name>]) stay in the file.

F9 (ou la palette, Settings ; le ⚙ de la page web) ouvre une page façon BIOS : un onglet par section (Interface, Agent, Commands, Global session, Sessions, Voice, Keys, Web, Attachments, Notifications, Orchestrator, Services...), l'aide de l'option choisie à droite.

  • Terminal : ↑↓ choisir, ←→ ou Entrée changer un choix, basculer ou modifier un nombre, Entrée édite un texte, Tab / Shift+Tab changent de section, Ctrl+S sauvegarde (la page reste), F10 sauvegarde et quitte, Échap quitte (changements non sauvegardés : Save the changes?). * marque les modifiés.
  • Les changements sont écrits dans config.toml (seulement les valeurs, ses commentaires conservés) et rechargés à chaud. Les options marquées applied at the next start demandent un redémarrage. Chaque option est listée dans la référence des réglages, et son défaut dans la référence de configuration.
  • Les profils ([profiles.<nom>]), fournisseurs propres ([providers.<nom>]) et styles propres ([styles.<nom>]) restent dans le fichier.

3. Dangerous valuesValeurs dangereuses

A yellow ⚠ marks each setting that can be dangerous and its name turns red while its value is the dangerous one: bypassPermissions for new sessions or the global session, allow_bypass, bypass_to_global, extra_args that skip permissions, the web access without approval, open to the Internet (remote = router), its shell, plain http, an added MCP server. Changing one asks nothing; the save lists them with their warnings in one popup. :set needs :set! for them and the control socket / MCP refuse without confirmed.

Un ⚠ jaune marque chaque réglage qui peut être dangereux et son nom devient rouge tant que sa valeur est la dangereuse : bypassPermissions pour les nouvelles sessions ou la session globale, allow_bypass, bypass_to_global, des extra_args qui sautent les permissions, l'accès web sans approbation, ouvert à Internet (remote = router), son shell, http simple, un serveur MCP ajouté. En changer un ne demande rien ; la sauvegarde les liste avec leurs avertissements dans une seule fenêtre. :set exige :set! pour eux et le socket de contrôle / le MCP refusent sans confirmed.

4. Protected settingsRéglages protégés

The global session can change most settings (settings_set) but never the protected ones: the web opened wider, the permissions of the agents, the programs run as you (commands.*, editors, viewers), the limits and the model policy, the plugin sources, the MCP servers. It asks you, and you change them here. The list is in Security.

La session globale peut changer la plupart des réglages (settings_set) mais jamais les protégés : le web ouvert plus largement, les permissions des agents, les programmes lancés comme vous (commands.*, éditeurs, visionneuses), les limites et la politique de modèles, les sources de plugins, les serveurs MCP. Elle vous demande, et vous les changez ici. La liste est dans Sécurité.

5. What a setting needsCe dont un réglage a besoin

What is missing for a setting is told in red on its right (✗ ...): a program not found (editor, viewer, agent), upnpc for remote = router, tailscale not connected. When a package installs it, [i] / Install... does it (the terminal asks sudo, the window and the web page use the password window of the desktop).

Ce qui manque à un réglage est dit en rouge à sa droite (✗ ...) : un programme introuvable (éditeur, visionneuse, agent), upnpc pour remote = router, tailscale non connecté. Quand un paquet l'installe, [i] / Install... le fait (le terminal demande sudo, la fenêtre et la page web utilisent la fenêtre de mot de passe du bureau).

6. The Services tabL'onglet Services

One card per sub service, with its state and buttons:

  • Service (systemd): the wake phrase while claude-cluster is closed (claude-cluster service setup | enable | disable | start | stop | restart | status | logs | remove). The unit ~/.config/systemd/user/claude-cluster.service is started with the graphical session; what it opens is Interface > Front-end (a window, else a terminal).
  • Web access: state, address, code, whether the outside is reached; open / close, new code.
  • Core: pid, version and build, who started it, its interfaces by kind, sessions working, how long it will stay in the background; restart, stop all.
  • Voice, MCP servers, Outside (router / tailscale).

Une carte par sous-service, avec son état et ses boutons :

  • Service (systemd) : la phrase de réveil pendant que claude-cluster est fermé (claude-cluster service setup | enable | disable | start | stop | restart | status | logs | remove). L'unité ~/.config/systemd/user/claude-cluster.service démarre avec la session graphique ; ce qu'elle ouvre est Interface > Front-end (une fenêtre, sinon un terminal).
  • Web access : état, adresse, code, si l'extérieur est joint ; ouvrir / fermer, nouveau code.
  • Core : pid, version et build, qui l'a lancé, ses interfaces par genre, sessions au travail, combien de temps il restera en arrière-plan ; redémarrer, tout arrêter.
  • Voice, MCP servers, Outside (router / tailscale).

7. ProfilesProfils

Every claude-cluster of the computer shares config.toml and reads it again when it changes: a setting changed anywhere is changed everywhere. Settings > Profiles keeps named copies of every setting: Save the settings of now as… (any name), then on each profile Apply (the settings before kept: Undo the last apply), Save the settings of now into it, Rename…, Note…, Archive / Unarchive, Delete (the trash for 7 days: Restore or Delete for good, then gone). The same cards in the terminal, the window, the page and the app.

Chaque claude-cluster de l'ordinateur partage config.toml et le relit quand il change : un réglage changé quelque part l'est partout. Réglages > Profiles garde des copies nommées de tous les réglages : Save the settings of now as… (n'importe quel nom), puis sur chaque profil Apply (les réglages d'avant gardés : Undo the last apply), Save the settings of now into it, Rename…, Note…, Archive / Unarchive, Delete (la corbeille 7 jours : Restore ou Delete for good, puis supprimé). Les mêmes cartes dans le terminal, la fenêtre, la page et l'app.

8. Accounts and limitsComptes et limites

Accounts & limits lists every provider with its state (a key stored, a login done, or what is missing). claude-cluster auth login <provider> asks a key without echo and stores it in the keyring (secret-tool) or credentials.json (0600), never in config.toml. The limits cap what sessions may spend together per day, week and month ([limits]), counted for API keys only (scope = keys) or everything, with Block at the limit and Warn at a share.

Accounts & limits liste chaque fournisseur avec son état (clé stockée, connexion faite, ou ce qui manque). claude-cluster auth login <fournisseur> demande une clé sans écho et la stocke dans le trousseau (secret-tool) ou credentials.json (0600), jamais dans config.toml. Les limites plafonnent ce que les sessions peuvent dépenser ensemble par jour, semaine et mois ([limits]), comptées pour les clés d'API seulement (scope = keys) ou tout, avec Block at the limit et Warn at une part.

9. Plugins and skillsPlugins et skills

The Plugins page (/plugins, the palette Plugins, in every interface) lists the sources first - a repository, a folder, a .zip - each with what it offers, has installed and has on, its last sync and its last commit (or its date). A source opened shows its offer as a checklist: tick several (or all), then install, remove, turn on or off the ticked ones at once. Each source can be synced now, installed or removed whole, turned off (every item of it off, kept installed) and on again, have its auto sync turned off (pulled by hand only), or be dropped. Sync all pulls every source; [plugins] sync_hours (24) is how often the auto ones are pulled. The settings page keeps only the sources and that period. A source's code runs as you: add only sources you trust.

La page Plugins (/plugins, la palette Plugins, dans chaque interface) liste d'abord les sources - un dépôt, un dossier, un .zip - chacune avec ce qu'elle propose, a installé et a activé, sa dernière synchronisation et son dernier commit (ou sa date). Une source ouverte montre son offre en liste à cocher : cochez-en plusieurs (ou toutes), puis installez, retirez, activez ou désactivez les cochées d'un coup. Chaque source peut être synchronisée tout de suite, installée ou retirée en entier, désactivée (tout ce qu'elle a désactivé, gardé installé) puis réactivée, voir sa synchro auto coupée (tirée à la main seulement), ou être retirée. Sync all tire toutes les sources ; [plugins] sync_hours (24) fixe la fréquence des sources en auto. La page de réglages ne garde que les sources et cette fréquence. Le code d'une source s'exécute en votre nom : n'ajoutez que des sources de confiance.

10. Context and keep warmContexte et maintien au chaud

  • Context at most ([global] context for the global session, [sessions] context for the others; auto by default, 100k to 1M): the conversation is compacted once it reaches this size (Claude Code CLAUDE_CODE_AUTO_COMPACT_WINDOW, given at every start). Every turn costs less, and a wake-up after its cache expired reloads that much, not 1M tokens. The global session may give a sub-session its own when it starts it (session_spawn context); a value out of 100k..1M is refused.
  • Workflows of the model ([agent] workflow, off by default, under the orchestration mode): the multi-agent workflows of the model itself, when it has them (Claude Code: its Workflow tool, ultracode; dozens of agents, a lot of tokens). Off: never, the tool is taken away from it. On: allowed and asked, it uses them on a big task. For the sessions started from then on.
  • Keep warm ([sessions] keep_warm: off, chosen, all, background): an idle session woken up a little before its prompt cache expires (keep_warm_ttl, keep_warm_margin), counted from the last request of its agent, so a session taken back (Esc) stays warm. A wake-up never piles up: when the last prompt is still a wake-up, it is taken back first and the same prompt sent again on the same cached prefix (one in the conversation at most). A wake-up is silent: no notification (desktop, page, app), sound, face nor notice. Its background running (shells / agents) changes nothing: an idle session waiting on a long compilation is woken up like any other (the background mode keeps warm only those). The sessions marked (/keepwarm) stay marked over a restart or an update, and the wake-ups go on while an update waits for the turns running. The cache counts from the last request the agent answered: a wake-up that failed is tried again until it really expires, and a refused wake-up, an expired cache or the keep_warm_hours stop are told in a notice (debug topic keepwarm). A wake-up never takes back the previous one while the background of the session runs: that would restart its agent and stop its background. Kept warm keep_warm_hours after the last real use (a prompt, a take-back, /keepwarm; 0: never stops): past it the session is no longer kept warm and its ♨ goes away, told once in a notice; a prompt or /keepwarm warms it again.
  • Contexte maximum ([global] context pour la session globale, [sessions] context pour les autres ; auto par défaut, 100k à 1M) : la conversation est compactée dès qu'elle atteint cette taille (Claude Code CLAUDE_CODE_AUTO_COMPACT_WINDOW, donné à chaque démarrage). Chaque tour coûte moins, et un réveil après l'expiration de son cache recharge cette taille, pas 1M de tokens. La session globale peut donner le sien à une sous-session quand elle la démarre (session_spawn context) ; une valeur hors de 100k..1M est refusée.
  • Workflows du modèle ([agent] workflow, désactivé par défaut, sous le mode d'orchestration) : les workflows multi-agents du modèle lui-même, quand il en a (Claude Code : son outil Workflow, ultracode ; des dizaines d'agents, beaucoup de tokens). Désactivé : jamais, l'outil lui est retiré. Activé : permis et demandés, il les utilise sur une grosse tâche. Pour les sessions démarrées à partir de là.
  • Maintien au chaud ([sessions] keep_warm : off, chosen, all, background) : une session inactive réveillée un peu avant que son cache expire (keep_warm_ttl, keep_warm_margin), compté depuis la dernière requête de son agent, donc une session reprise en arrière (Échap) reste au chaud. Un réveil ne s'empile jamais : quand le dernier prompt est encore un réveil, il est d'abord repris et le même prompt renvoyé sur le même préfixe en cache (un seul dans la conversation au plus). Un réveil est silencieux : ni notification (bureau, page, app), ni son, ni visage, ni notice. Son arrière-plan en cours (shells / agents) ne change rien : une session au repos qui attend une longue compilation est réveillée comme les autres (le mode background ne garde au chaud que celles-là). Les sessions marquées (/keepwarm) le restent après un redémarrage ou une mise à jour, et les réveils continuent pendant qu'une mise à jour attend les tours en cours. Le cache compte depuis la dernière requête à laquelle l'agent a répondu : un réveil échoué est retenté jusqu'à l'expiration réelle, et un réveil refusé, un cache expiré ou l'arrêt de keep_warm_hours sont dits dans une notice (sujet de debug keepwarm). Un réveil ne reprend jamais le précédent tant que l'arrière-plan de la session tourne : cela relancerait son agent et arrêterait cet arrière-plan. Gardée au chaud keep_warm_hours après la dernière vraie utilisation (un prompt, une reprise, /keepwarm ; 0 : jamais d'arrêt) : passé ce délai, la session n'est plus gardée au chaud et son ♨ disparaît, signalé une fois par une notice ; un prompt ou /keepwarm la réchauffe.

11. Debug and the showcaseDebug et la vitrine

Debug has a showcase that shows for real everything claude-cluster can draw (display blocks, question and permission popups, session states, progress and failure popups, notifications) in a session of its own whose agent is never asked anything: nothing is spent.

Below it, a soundboard: each sound of the notifications (a turn done, a job done, for you, a problem, ready) and all of them in a row, played on the computer of the core whatever With a sound says. The settings stay open, from any interface.

Debug a une vitrine qui montre pour de vrai tout ce que claude-cluster sait dessiner (blocs d'affichage, fenêtres de question et de permission, états de session, fenêtres de progression et d'échec, notifications) dans une session à part dont l'agent n'est jamais sollicité : rien n'est dépensé.

En dessous, un soundboard : chaque son des notifications (a turn done, a job done, for you, a problem, ready) et tous à la suite, joués sur l'ordinateur du cœur quoi que dise With a sound. Les réglages restent ouverts, depuis n'importe quelle interface.