claude-cluster docs1.10.1
ReferenceRéférence

Configuration referenceRéférence de configuration

Every section and key of config.toml with its default - generated from the template shipped in the binary.Chaque section et clé de config.toml avec son défaut - générée depuis le modèle embarqué dans le binaire.

~/.config/claude-cluster/config.toml is written, commented, on the first run and reloaded live when saved. Every key is optional: a missing key keeps its default. This page is generated from templates/config.toml: the defaults and the comments are those of the file. The same options with their labels are in the settings reference; the key bindings are in the keys reference.

~/.config/claude-cluster/config.toml est écrit, commenté, au premier lancement et rechargé à chaud quand il est sauvegardé. Chaque clé est optionnelle : une clé absente garde sa valeur par défaut. Cette page est générée depuis templates/config.toml : les valeurs par défaut et les commentaires sont ceux du fichier. Les mêmes options avec leurs libellés sont dans la référence des réglages ; les touches sont dans la référence des touches.

Les commentaires viennent du fichier, en anglais.

1. [ui] - Interface[ui] - Interface

KeyDefaultDescription
frontend"auto"auto | tty | gui (the --tty / --gui flags win)
layout"list"list (list + active panel) | grid | tabs (window / web page; the terminal shows the list)
mode"classic"classic (every view, every setting) | simple (what needs you, a card per session, the useful settings; --simple)
language"en"the words of the simple mode: en | fr
style"html-dark"html-light | html-dark | nord | gruvbox | solarized-light | mono, or a [styles.<name>] below
panels["skills", "tokens", "context", "cost", "usage", "git"]default panels of a new session (+ "diff", "tools", "files") usage: the vendor of the session today / 7 days / lifetime (tokens, cost), limits left
restore"ask"ask | always | never: sessions of the previous run at start (ask: like Firefox, r / n / q at every start)
prompt_origintruethe prompts of a transcript coloured by where they come from (+ a label: mcp, task, scheduled); false: all as before
prompt_color_user"""#rrggbb" of the prompts you type (empty: the accent of the style, as before)
prompt_color_mcp""of the prompts of the global session and the cluster (session_send / session_spawn, [reply from ...], answers): empty = violet
prompt_color_task""of the prompts of the tasks and the schedules ([tasks], [scheduled wN]): empty = magenta
notifytruedesktop notifications at all (the ones of the global session too)
restart_coretruea crashed core started again by its watcher, its sessions restored (false: no watcher)
start_menutrueat each start of the terminal: open the running claude-cluster / an independent instance / restore the previous run / start new / quit
notify_globaltruewhen the global session answers
notify_donetruewhen a sub-session finishes its turn
notify_permissiontruewhen a permission waits
notify_soundtruea short sound with them (the sounds of the desktop theme, one per kind)
notify_when"unfocused"unfocused: only when claude-cluster is not in front (its popups are) | always
notify_questiontruea question of an agent (its options as buttons)
notify_errortruean error, a crash, the safety check
notify_limitstruea limit close (80 / 95 %) or reached
notify_webtruea device asks to connect / connected (web access)
notify_taskstruethe task queue done
notify_task_eachfalseeach task done (task_add notify: true: that one)
notify_reminderstruea reminder (schedule add --notify)
notify_apptruethe same notifications published to the Android app (each phone opts in, its kinds in This device)
notify_readytruesomething slow ready: claude-cluster started, the speech model loaded, the map written
group_by_categoryfalsethe session list grouped by the category of its sessions (the palette: Group by category, /group)
vimfalsevim mode of the prompt: Esc Normal (hjkl w b e 0 $ x dd dw cw yy p u v V...), i / a / o Insert
paste_lines3a paste of more lines is one [Pasted text #N +L lines] in the prompt (0: never)
paste_chars800or of more characters (0: never)
stash_max10prompts kept in the stash (Ctrl+S puts the prompt aside, Ctrl+L lists them: load, remove, clear all); stored in stash.json of the data folder, over the restarts, shared by every session (each one shows where it was written)
stash_full"refuse"the stash is full: refuse (the prompt stays in the editor, nothing is lost) | drop_oldest (the oldest one makes room) the copies made by themselves (a prompt replaced by another one) are never refused
stash_rewoundfalseEsc (rewind chooser): the prompts it removes from the conversation are put in the stash too
editor""Ctrl+E; empty: nvim, vim, vi, $VISUAL, $EDITOR, emacs -nw, nano (the first installed)
machine_days30the map of this computer older than this: a sync proposed at start (0: never)
image_viewer""right click on an image chip; empty: xdg-open (the viewer of the desktop)
image_preview"blocks"terminal preview on hover: blocks (the pixels as half blocks) | chafa (its symbols)
typewritertruethe answers typed as they come, also when the agent sends them at once (false: as received)
typewriter_speed400characters per second (faster by itself when a long text is behind)
CléDéfautDescription
frontend"auto"auto | tty | gui (the --tty / --gui flags win)
layout"list"list (list + active panel) | grid | tabs (window / web page; the terminal shows the list)
mode"classic"classic (every view, every setting) | simple (what needs you, a card per session, the useful settings; --simple)
language"en"the words of the simple mode: en | fr
style"html-dark"html-light | html-dark | nord | gruvbox | solarized-light | mono, or a [styles.<name>] below
panels["skills", "tokens", "context", "cost", "usage", "git"]default panels of a new session (+ "diff", "tools", "files") usage: the vendor of the session today / 7 days / lifetime (tokens, cost), limits left
restore"ask"ask | always | never: sessions of the previous run at start (ask: like Firefox, r / n / q at every start)
prompt_origintruethe prompts of a transcript coloured by where they come from (+ a label: mcp, task, scheduled); false: all as before
prompt_color_user"""#rrggbb" of the prompts you type (empty: the accent of the style, as before)
prompt_color_mcp""of the prompts of the global session and the cluster (session_send / session_spawn, [reply from ...], answers): empty = violet
prompt_color_task""of the prompts of the tasks and the schedules ([tasks], [scheduled wN]): empty = magenta
notifytruedesktop notifications at all (the ones of the global session too)
restart_coretruea crashed core started again by its watcher, its sessions restored (false: no watcher)
start_menutrueat each start of the terminal: open the running claude-cluster / an independent instance / restore the previous run / start new / quit
notify_globaltruewhen the global session answers
notify_donetruewhen a sub-session finishes its turn
notify_permissiontruewhen a permission waits
notify_soundtruea short sound with them (the sounds of the desktop theme, one per kind)
notify_when"unfocused"unfocused: only when claude-cluster is not in front (its popups are) | always
notify_questiontruea question of an agent (its options as buttons)
notify_errortruean error, a crash, the safety check
notify_limitstruea limit close (80 / 95 %) or reached
notify_webtruea device asks to connect / connected (web access)
notify_taskstruethe task queue done
notify_task_eachfalseeach task done (task_add notify: true: that one)
notify_reminderstruea reminder (schedule add --notify)
notify_apptruethe same notifications published to the Android app (each phone opts in, its kinds in This device)
notify_readytruesomething slow ready: claude-cluster started, the speech model loaded, the map written
group_by_categoryfalsethe session list grouped by the category of its sessions (the palette: Group by category, /group)
vimfalsevim mode of the prompt: Esc Normal (hjkl w b e 0 $ x dd dw cw yy p u v V...), i / a / o Insert
paste_lines3a paste of more lines is one [Pasted text #N +L lines] in the prompt (0: never)
paste_chars800or of more characters (0: never)
stash_max10prompts kept in the stash (Ctrl+S puts the prompt aside, Ctrl+L lists them: load, remove, clear all); stored in stash.json of the data folder, over the restarts, shared by every session (each one shows where it was written)
stash_full"refuse"the stash is full: refuse (the prompt stays in the editor, nothing is lost) | drop_oldest (the oldest one makes room) the copies made by themselves (a prompt replaced by another one) are never refused
stash_rewoundfalseEsc (rewind chooser): the prompts it removes from the conversation are put in the stash too
editor""Ctrl+E; empty: nvim, vim, vi, $VISUAL, $EDITOR, emacs -nw, nano (the first installed)
machine_days30the map of this computer older than this: a sync proposed at start (0: never)
image_viewer""right click on an image chip; empty: xdg-open (the viewer of the desktop)
image_preview"blocks"terminal preview on hover: blocks (the pixels as half blocks) | chafa (its symbols)
typewritertruethe answers typed as they come, also when the agent sends them at once (false: as received)
typewriter_speed400characters per second (faster by itself when a long text is behind)

2. [agent][agent]

KeyDefaultDescription
provider"claude"Provider of EVERY session: the global session, every sub-session (existing ones at the next start, new ones, imported conversations): "<provider>[/<model>]" (claude-cluster auth list: every provider and its state). Applied at the next start. The global session needs a claude driver one. Replaces the old [agent] default and [global] backend (still read when this key is missing). A session of another driver (codex, opencode, qwen) keeps its own: its conversation needs it. claude driver (full: live permissions, MCP, Remote Control): anthropic (= claude, its login), anthropic-api, ollama (local), openrouter, deepseek, kimi, zai, minimax (Anthropic-compatible endpoints) qwen driver (Qwen Code): openai, ollama-openai (OpenAI-compatible endpoints) opencode driver: opencode/<provider>/<model> (its own providers, opencode auth) codex driver: codex[/<model>] (OpenAI Codex CLI, codex login)
permission_mode"auto"auto | manual | acceptEdits | plan | dontAsk | bypassPermissions (empty: the default of claude -p, manual)
effort""thinking / reasoning effort of the new sessions (empty: the default of the agent): claude low | medium | high | xhigh | max, codex / opencode minimal | low | medium | high... per session: /effort <level>, the palette (Effort), claude-cluster effort <s> <level>
allow_bypasstrueclaude: launched with --allow-dangerously-skip-permissions, so bypassPermissions can be chosen
extra_args[]
sub_pintruea sub-session may pin an item on its own view (never on another one); you always may, by hand
global_pintruethe global session may pin a message / display block at the bottom of any session (MCP session_pin)
taxonomy_edittruethe global session may edit the taxonomy of the categories / tags (MCP taxonomy: parent, rename, delete, merge)
orchestration"hybrid"compact | hybrid | ultra: how readily the global session splits work into sub-sessions (compact: the fewest, one per project, asks before splitting)
workflowfalsethe multi-agent workflows of the model itself, when it has them (Claude Code: its Workflow tool, ultracode: dozens of agents, a lot of tokens): true: allowed and asked (it uses them on a big task); false: never, the tool taken away from it (the sessions started from now)
work_method"free"Work method: how the work is organised, injected (short) in the system prompt of the sub-sessions and of the global session, which splits the requests accordingly (a session takes it at its next start). Only you change it (never the global session). free (nothing) | list-review (a task list, then a review, repeated until good) | one-task (one task at a time) | plan-first (a plan, then the work) | custom (only the text below)
work_method_text""your own words, added to the preset (400 characters at most)
work_method_detectfalsethe global session may PROPOSE a method from how you phrase requests (a small sample of your prompts, no model): a popup you answer Allow / Deny, never applied alone
work_method_every20sessions started by the global session between two checks (0: only when asked)
CléDéfautDescription
provider"claude"Provider of EVERY session: the global session, every sub-session (existing ones at the next start, new ones, imported conversations): "<provider>[/<model>]" (claude-cluster auth list: every provider and its state). Applied at the next start. The global session needs a claude driver one. Replaces the old [agent] default and [global] backend (still read when this key is missing). A session of another driver (codex, opencode, qwen) keeps its own: its conversation needs it. claude driver (full: live permissions, MCP, Remote Control): anthropic (= claude, its login), anthropic-api, ollama (local), openrouter, deepseek, kimi, zai, minimax (Anthropic-compatible endpoints) qwen driver (Qwen Code): openai, ollama-openai (OpenAI-compatible endpoints) opencode driver: opencode/<provider>/<model> (its own providers, opencode auth) codex driver: codex[/<model>] (OpenAI Codex CLI, codex login)
permission_mode"auto"auto | manual | acceptEdits | plan | dontAsk | bypassPermissions (empty: the default of claude -p, manual)
effort""thinking / reasoning effort of the new sessions (empty: the default of the agent): claude low | medium | high | xhigh | max, codex / opencode minimal | low | medium | high... per session: /effort <level>, the palette (Effort), claude-cluster effort <s> <level>
allow_bypasstrueclaude: launched with --allow-dangerously-skip-permissions, so bypassPermissions can be chosen
extra_args[]
sub_pintruea sub-session may pin an item on its own view (never on another one); you always may, by hand
global_pintruethe global session may pin a message / display block at the bottom of any session (MCP session_pin)
taxonomy_edittruethe global session may edit the taxonomy of the categories / tags (MCP taxonomy: parent, rename, delete, merge)
orchestration"hybrid"compact | hybrid | ultra: how readily the global session splits work into sub-sessions (compact: the fewest, one per project, asks before splitting)
workflowfalsethe multi-agent workflows of the model itself, when it has them (Claude Code: its Workflow tool, ultracode: dozens of agents, a lot of tokens): true: allowed and asked (it uses them on a big task); false: never, the tool taken away from it (the sessions started from now)
work_method"free"Work method: how the work is organised, injected (short) in the system prompt of the sub-sessions and of the global session, which splits the requests accordingly (a session takes it at its next start). Only you change it (never the global session). free (nothing) | list-review (a task list, then a review, repeated until good) | one-task (one task at a time) | plan-first (a plan, then the work) | custom (only the text below)
work_method_text""your own words, added to the preset (400 characters at most)
work_method_detectfalsethe global session may PROPOSE a method from how you phrase requests (a small sample of your prompts, no model): a popup you answer Allow / Deny, never applied alone
work_method_every20sessions started by the global session between two checks (0: only when asked)

3. [commands][commands] - Commandes

programs of the drivers

KeyDefaultDescription
sub_readtruea sub-session lists its own tasks / schedules (MCP task_list, schedule_list)
sub_taskstrue... queues tasks (MCP task_add; it manages its own ones only)
sub_schedulesfalse... creates schedules (MCP schedule_add, schedule_edit)
sub_spawnfalse... makes tasks / schedules that start sessions
sub_spawn_cap2the sessions of its tasks / schedules it may have waiting or open at once
claude"claude"
qwen"qwen"
opencode"opencode"
codex"codex"

programs of the drivers

CléDéfautDescription
sub_readtruea sub-session lists its own tasks / schedules (MCP task_list, schedule_list)
sub_taskstrue... queues tasks (MCP task_add; it manages its own ones only)
sub_schedulesfalse... creates schedules (MCP schedule_add, schedule_edit)
sub_spawnfalse... makes tasks / schedules that start sessions
sub_spawn_cap2the sessions of its tasks / schedules it may have waiting or open at once
claude"claude"
qwen"qwen"
opencode"opencode"
codex"codex"

4. [global] - Global session[global] - Session globale

KeyDefaultDescription
enabledtrue
cwd""working folder of the global session; empty: a folder of its own (~/.local/share/claude-cluster/global, trusted by claude-cluster for Remote Control: claude --bg never runs in the home folder)
model""
effort""of the global session at every start (empty: its own /effort, else the one of [agent])
context"auto"its context at most: compacted once it reaches this size (100k to 1M; auto: the window of the model); a smaller one costs less at every turn and reloads less after its cache expired
permission_mode"bypassPermissions"of the global session, applied at every start: it can do anything without asking (empty: the mode of [agent])
prompt"~/.config/claude-cluster/global.md"its own system prompt (added to the global CLAUDE.md)
remote_name"claude-cluster"name of the Remote Control session
CléDéfautDescription
enabledtrue
cwd""working folder of the global session; empty: a folder of its own (~/.local/share/claude-cluster/global, trusted by claude-cluster for Remote Control: claude --bg never runs in the home folder)
model""
effort""of the global session at every start (empty: its own /effort, else the one of [agent])
context"auto"its context at most: compacted once it reaches this size (100k to 1M; auto: the window of the model); a smaller one costs less at every turn and reloads less after its cache expired
permission_mode"bypassPermissions"of the global session, applied at every start: it can do anything without asking (empty: the mode of [agent])
prompt"~/.config/claude-cluster/global.md"its own system prompt (added to the global CLAUDE.md)
remote_name"claude-cluster"name of the Remote Control session

5. [sessions][sessions]

KeyDefaultDescription
trash_days14a closed session stays restorable this many days
max_parallel4task queue: sessions working at the same time
task_result_chars6000the answer kept in a task (its result, chained with {{tN.result}}): its first characters
budget_usd0.00 = no budget; reached: the session refuses new prompts (notified)
context"auto"the context of every other session at most, like [global] context (100k to 1M, auto); the global session may give a sub-session its own when it starts it (session_spawn context)
keep_warm"off"off | chosen (/keepwarm) | all | background: an idle session woken up before its prompt cache expires (a tiny turn; the previous wake-up taken back first: one in the conversation at most)
keep_warm_ttl5minutes the prompt cache lives (5; 60 with a 1 h cache), counted from the last request
keep_warm_margin45the wake-up this many seconds before it expires (16 to 600: checked every 10 s)
keep_warm_hours2kept warm so long after the last real use: a prompt, a take-back, /keepwarm (0: never stops); past it its ♨ goes
questions_to_globaltruea question of the agent of a sub-session shown on the global session (its own one greyed); answered with the keys, the mouse or the voice
global_answersfalsethe global session is told those questions and may choose their answer
bypass_to_globaltruethe permissions a sub-session in bypassPermissions still asks (safety check of Claude Code): decided by the global session (it asks you when unsure); off: you answer them
global_forkfalsethe global session may fork a sub-session (MCP session_fork); you can always (palette, fork)
rewrite_global_promptfalsethe global session may rewrite its own system prompt (MCP config_write global_prompt); old key global_prompts: same, as fallback
rewrite_sessions_prompttruethe global session may rewrite the system prompt of the sub-sessions (MCP config_write sessions_prompt)
archive_one_shottruea session the global session started for ONE task (session_spawn one_shot) is closed to the trash (restorable) once its answer is relayed; kept when you typed in it, look at it or it waits for you; off: the flag is ignored
global_editfalsethe global session may rewrite the conversation of a sub-session (MCP session_edit)
prompt"~/.config/claude-cluster/sessions.md"system prompt of every sub-session (claude driver, added to the global CLAUDE.md; an empty file: none), taken at the next start of each session
CléDéfautDescription
trash_days14a closed session stays restorable this many days
max_parallel4task queue: sessions working at the same time
task_result_chars6000the answer kept in a task (its result, chained with {{tN.result}}): its first characters
budget_usd0.00 = no budget; reached: the session refuses new prompts (notified)
context"auto"the context of every other session at most, like [global] context (100k to 1M, auto); the global session may give a sub-session its own when it starts it (session_spawn context)
keep_warm"off"off | chosen (/keepwarm) | all | background: an idle session woken up before its prompt cache expires (a tiny turn; the previous wake-up taken back first: one in the conversation at most)
keep_warm_ttl5minutes the prompt cache lives (5; 60 with a 1 h cache), counted from the last request
keep_warm_margin45the wake-up this many seconds before it expires (16 to 600: checked every 10 s)
keep_warm_hours2kept warm so long after the last real use: a prompt, a take-back, /keepwarm (0: never stops); past it its ♨ goes
questions_to_globaltruea question of the agent of a sub-session shown on the global session (its own one greyed); answered with the keys, the mouse or the voice
global_answersfalsethe global session is told those questions and may choose their answer
bypass_to_globaltruethe permissions a sub-session in bypassPermissions still asks (safety check of Claude Code): decided by the global session (it asks you when unsure); off: you answer them
global_forkfalsethe global session may fork a sub-session (MCP session_fork); you can always (palette, fork)
rewrite_global_promptfalsethe global session may rewrite its own system prompt (MCP config_write global_prompt); old key global_prompts: same, as fallback
rewrite_sessions_prompttruethe global session may rewrite the system prompt of the sub-sessions (MCP config_write sessions_prompt)
archive_one_shottruea session the global session started for ONE task (session_spawn one_shot) is closed to the trash (restorable) once its answer is relayed; kept when you typed in it, look at it or it waits for you; off: the flag is ignored
global_editfalsethe global session may rewrite the conversation of a sub-session (MCP session_edit)
prompt"~/.config/claude-cluster/sessions.md"system prompt of every sub-session (claude driver, added to the global CLAUDE.md; an empty file: none), taken at the next start of each session

6. [voice][voice] - Voix

KeyDefaultDescription
enabledfalse
mode"push"push: push-to-talk key | auto: every sentence heard | wake: only after the wake phrase
wake_word"ok claude"wake mode: phrase(s) that trigger the listening, variants separated by commas (speech recognition can bend it: "ok claude, okay claude, hey claude")
wake_seconds8wake mode: the phrase alone arms the listening this long (the next sentence is the prompt)
wake_reply""wake mode: spoken when armed (ex: "Oui ?"), empty: silent
only_metruevoice-listen --only-me (needs voice-enroll)
confirm_seconds3the transcription is shown this long before it is sent (0: sent at once)
speaktruespoken summary of the answers of the global session
summary_chars220
listen_model""The engines (settings page > Voice: what each one handles, its limits, its free use, its link; claude-cluster engines) speech to text, voice-listen --model: local parakeet (French, English, mixed) | whisper (99 languages, slower) | kroko-fr (French only, live text, the fastest); free-tier APIs groq (Whisper large, 8 h a day) | deepgram (Nova-3, $200 of credit), their key: claude-cluster auth login groq; empty: the choice of voice-models
listen_language""the language spoken, for whisper / groq / deepgram (fr, en...); empty: found by the model
end_silence0.0seconds of silence ending a sentence (0: the one of voice-listen, 1.0): a shorter pause goes on the same sentence, two sentences said in a row are one prompt
words""the cancel / send words said alone while a transcription waits (settings page > Voice > Voice words (edit)); empty: voice-words.txt of the config folder
cancel_words[]more cancel words here, added to the file
send_words[]more send words here, added to the file
vocabulary""proper names written back in every sentence heard (+ the sessions, the projects of the map of this computer, your names); empty: vocabulary.txt of the config folder
listen_command"voice-listen"
say_command"voice-say"
say_engine"piper"text to speech: local piper (instant, synthetic) | kokoro (natural, ~1 s a sentence: voice-models install kokoro); free-tier APIs elevenlabs | cartesia (claude-cluster auth login cartesia); an engine failing (no key, quota, model missing): Piper
say_voices""the voice of that engine per language: "fr=ff_siwis, en=bf_emma" (voice-tts --list kokoro); another engine for a language: "es=kokoro:ef_dora"; a language missing: the engine's default
voice_fr"tom-medium"the Piper voices (say_engine = piper, and the fallback of the others)
voice_en"en_GB-northern_english_male-medium"
CléDéfautDescription
enabledfalse
mode"push"push: push-to-talk key | auto: every sentence heard | wake: only after the wake phrase
wake_word"ok claude"wake mode: phrase(s) that trigger the listening, variants separated by commas (speech recognition can bend it: "ok claude, okay claude, hey claude")
wake_seconds8wake mode: the phrase alone arms the listening this long (the next sentence is the prompt)
wake_reply""wake mode: spoken when armed (ex: "Oui ?"), empty: silent
only_metruevoice-listen --only-me (needs voice-enroll)
confirm_seconds3the transcription is shown this long before it is sent (0: sent at once)
speaktruespoken summary of the answers of the global session
summary_chars220
listen_model""The engines (settings page > Voice: what each one handles, its limits, its free use, its link; claude-cluster engines) speech to text, voice-listen --model: local parakeet (French, English, mixed) | whisper (99 languages, slower) | kroko-fr (French only, live text, the fastest); free-tier APIs groq (Whisper large, 8 h a day) | deepgram (Nova-3, $200 of credit), their key: claude-cluster auth login groq; empty: the choice of voice-models
listen_language""the language spoken, for whisper / groq / deepgram (fr, en...); empty: found by the model
end_silence0.0seconds of silence ending a sentence (0: the one of voice-listen, 1.0): a shorter pause goes on the same sentence, two sentences said in a row are one prompt
words""the cancel / send words said alone while a transcription waits (settings page > Voice > Voice words (edit)); empty: voice-words.txt of the config folder
cancel_words[]more cancel words here, added to the file
send_words[]more send words here, added to the file
vocabulary""proper names written back in every sentence heard (+ the sessions, the projects of the map of this computer, your names); empty: vocabulary.txt of the config folder
listen_command"voice-listen"
say_command"voice-say"
say_engine"piper"text to speech: local piper (instant, synthetic) | kokoro (natural, ~1 s a sentence: voice-models install kokoro); free-tier APIs elevenlabs | cartesia (claude-cluster auth login cartesia); an engine failing (no key, quota, model missing): Piper
say_voices""the voice of that engine per language: "fr=ff_siwis, en=bf_emma" (voice-tts --list kokoro); another engine for a language: "es=kokoro:ef_dora"; a language missing: the engine's default
voice_fr"tom-medium"the Piper voices (say_engine = piper, and the fallback of the others)
voice_en"en_GB-northern_english_male-medium"

7. [web] - Web access[web] - Accès web

the devices of this LAN drive claude-cluster (palette: Web access, claude-cluster web on, --web)

KeyDefaultDescription
enabledfalseopened at each start; the code (6 digits) and the address shown at the top of the interface
port8787several devices at once; private addresses of the same subnet only (never the internet)
httpstrueTLS, certificate of its own (~/.config/claude-cluster/web): encrypted, the microphone of the page allowed
approvetruea new device: its code, then your yes here (allow, allow and trust, deny); the trusted ones: neither
discoverytruethe app finds this computer on this network by itself (UDP 8789 answered, this LAN only, never the code)

the devices of this LAN drive claude-cluster (palette: Web access, claude-cluster web on, --web)

CléDéfautDescription
enabledfalseopened at each start; the code (6 digits) and the address shown at the top of the interface
port8787several devices at once; private addresses of the same subnet only (never the internet)
httpstrueTLS, certificate of its own (~/.config/claude-cluster/web): encrypted, the microphone of the page allowed
approvetruea new device: its code, then your yes here (allow, allow and trust, deny); the trusted ones: neither
discoverytruethe app finds this computer on this network by itself (UDP 8789 answered, this LAN only, never the code)

8. [attachments][attachments] - Pièces jointes

files, images and photos attached to a prompt (paperclip, drop, paste; the app: the camera) (F9 > Attachments)

KeyDefaultDescription
enabledtrue
max_mb20the largest file; a bigger one is refused
max_files10per prompt
keep200kept per session (the oldest go; all go when the session is deleted; 0: all kept)
max_pixels2048a larger image is downscaled to this side before it is stored (0: as it is); needs ImageMagick
strip_exiftrueimages re-encoded without EXIF (GPS, camera); needs ImageMagick
dir""stored where, one folder per session (empty: <data>/attachments)
linktruea file of this computer linked by its path (nothing copied): window, terminal, a page on this computer
globaltruethe global session may attach a local file to a prompt (project folder / home only, no hidden folder)
global_max5files per prompt of the global session

files, images and photos attached to a prompt (paperclip, drop, paste; the app: the camera) (F9 > Attachments)

CléDéfautDescription
enabledtrue
max_mb20the largest file; a bigger one is refused
max_files10per prompt
keep200kept per session (the oldest go; all go when the session is deleted; 0: all kept)
max_pixels2048a larger image is downscaled to this side before it is stored (0: as it is); needs ImageMagick
strip_exiftrueimages re-encoded without EXIF (GPS, camera); needs ImageMagick
dir""stored where, one folder per session (empty: <data>/attachments)
linktruea file of this computer linked by its path (nothing copied): window, terminal, a page on this computer
globaltruethe global session may attach a local file to a prompt (project folder / home only, no hidden folder)
global_max5files per prompt of the global session

9. [mcp][mcp]

MCP of the global session (F9 > MCP)

KeyDefaultDescription
servers[]custom servers it gets too: "name: command args" (stdio; env VAR=value command... for its variables) | "name: https://url" (HTTP); its tools: mcp__<name>__*; at its next start

MCP of the global session (F9 > MCP)

CléDéfautDescription
servers[]custom servers it gets too: "name: command args" (stdio; env VAR=value command... for its variables) | "name: https://url" (HTTP); its tools: mcp__<name>__*; at its next start

10. [user][user] - Utilisateur

about you, for the global session (asked at the first map of this computer, F9 > User)

KeyDefaultDescription
nickname""
email""
editor""your main editor (Ctrl+E too when [ui] editor is empty)
language""of the answers: fr | en | empty (the one of the message)
notes""anything the global session should know

about you, for the global session (asked at the first map of this computer, F9 > User)

CléDéfautDescription
nickname""
email""
editor""your main editor (Ctrl+E too when [ui] editor is empty)
language""of the answers: fr | en | empty (the one of the message)
notes""anything the global session should know

11. [service][service]

claude-cluster service enable: "ok claude" opens claude-cluster (voice on) when none runs

KeyDefaultDescription
keep_awake"working"off | working | always: no idle sleep (systemd-inhibit) while a session works / while claude-cluster runs; the lid and the suspend menu still work
frontend"auto"auto: a window (when built with it and a display), else / on its failure a terminal gui: a window, a terminal on its failure | tty: a terminal only; every failure logged
terminal""tty: the terminal with its option to run a command ("kitty", "alacritty -e"...), empty: the first installed
voice_mode"auto"the voice of the claude-cluster opened: auto (every sentence) | wake | push
wake_word""empty: [voice] wake_word

claude-cluster service enable: "ok claude" opens claude-cluster (voice on) when none runs

CléDéfautDescription
keep_awake"working"off | working | always: no idle sleep (systemd-inhibit) while a session works / while claude-cluster runs; the lid and the suspend menu still work
frontend"auto"auto: a window (when built with it and a display), else / on its failure a terminal gui: a window, a terminal on its failure | tty: a terminal only; every failure logged
terminal""tty: the terminal with its option to run a command ("kitty", "alacritty -e"...), empty: the first installed
voice_mode"auto"the voice of the claude-cluster opened: auto (every sentence) | wake | push
wake_word""empty: [voice] wake_word

12. [orchestrator][orchestrator] - Orchestrateur

the heavy jobs of the sessions (builds, tests, containers / GPU) queued and limited: cluster-run, heavy_run (F9 > Orchestrator)

KeyDefaultDescription
enabledtrueoff: nothing is queued, cluster-run runs its command at once
profile"low"low (1 thread, nice 19, ionice idle) | normal (2-4 threads, nice 10) | max (the share of cores, nice 5)
max_jobs0heavy jobs running at once (0: from the hardware, the profile, the live load and memory)
max_per_session2running at once for one session (0: no limit)
reserved_cpu2cores left to you and the interface
reserved_ram_mb3072memory left to you and the interface
threads0parallelism granted to a job (-j, --parallel, CARGO_BUILD_JOBS...; 0: from the profile)
build_max0per class (build, tests, container, gpu, custom): running at once (0: auto; container 2, gpu 1 by default)
tests_max0
container_max2
gpu_max1
custom_max0
build_ram_mb2000per class: the memory of one job (a clang++ job takes 1.5 - 2.5 GB); a job starts when it fits
tests_ram_mb1200
container_ram_mb1500
gpu_ram_mb2000
custom_ram_mb1000
patterns[]more heavy commands: "text" (class custom) or "text = class": a command containing it goes through the queue
session_prio[]"s3=5": the jobs of a session come first (higher) or last (negative)
session_quota[]"s3=1": jobs of a session running at once
detect_cpu_seconds60a command outside the queue that burned this many CPU seconds: its session is told (0: off)
detect_action"notice"off | notice (a notice, listed in the jobs) | tell (its session is also told: a prompt)
hold_load1.5load per core: nothing new starts
reduce_load3.0load per core: the running jobs are reniced, the lowest priority one stopped until it falls
hold_mem_mb3000MemAvailable below: nothing new starts
reduce_mem_mb1200MemAvailable below: the running jobs are slowed
oom_mem_mb500MemAvailable below (kill_on_oom): the newest job is killed
hold_swap_mb4096swap used above, with the memory short too: nothing new starts
psi_cpu_hold80pressure stall information (avg10, %, /proc/pressure): nothing new starts / jobs slowed
psi_cpu_reduce95
psi_mem_hold20
psi_mem_reduce40
psi_io_hold50
psi_io_reduce80
resume_after20seconds under the thresholds before a stopped job resumes (hysteresis)
kill_on_oomfalsenever kill by default; true: the newest job killed under oom_mem_mb
memory_guardtrueunder guard_free_mb available: the biggest of what claude-cluster runs is killed (never the core) before the system kills anything itself; its session is told what and why, a notice and a notification too
guard_free_mb0the memory kept free (0: 5 % of the RAM, at least 500 MB)
guard_min_mb100a command smaller than this is never the one killed
aging_seconds30a waiting job gains one point every so many seconds (nothing starves; a priority step is 10 points)
focus_boost15points of the session you look at
sub_addfalsea sub-session may queue heavy jobs through the MCP (heavy_run, jobs_add): off by default (no permission prompt on that path); its Bash tool, cluster-run included, works as usual
sub_kill_owntrue... kill its own jobs
sub_see_othersfalse... see the jobs of the other sessions
notify_killedtruea notification when a job is killed (desktop, app)
notify_donefalse... when one finishes
history200finished jobs kept
proc_dir"/proc"where the load and the memory are read (a fake tree: the tests)
sys_dir"/sys"
python"~/.local/share/voice/venv/bin/python"the python of voice-listen (sherpa-onnx), its model is used
source""microphone (PulseAudio / PipeWire source), empty: the default one

the heavy jobs of the sessions (builds, tests, containers / GPU) queued and limited: cluster-run, heavy_run (F9 > Orchestrator)

CléDéfautDescription
enabledtrueoff: nothing is queued, cluster-run runs its command at once
profile"low"low (1 thread, nice 19, ionice idle) | normal (2-4 threads, nice 10) | max (the share of cores, nice 5)
max_jobs0heavy jobs running at once (0: from the hardware, the profile, the live load and memory)
max_per_session2running at once for one session (0: no limit)
reserved_cpu2cores left to you and the interface
reserved_ram_mb3072memory left to you and the interface
threads0parallelism granted to a job (-j, --parallel, CARGO_BUILD_JOBS...; 0: from the profile)
build_max0per class (build, tests, container, gpu, custom): running at once (0: auto; container 2, gpu 1 by default)
tests_max0
container_max2
gpu_max1
custom_max0
build_ram_mb2000per class: the memory of one job (a clang++ job takes 1.5 - 2.5 GB); a job starts when it fits
tests_ram_mb1200
container_ram_mb1500
gpu_ram_mb2000
custom_ram_mb1000
patterns[]more heavy commands: "text" (class custom) or "text = class": a command containing it goes through the queue
session_prio[]"s3=5": the jobs of a session come first (higher) or last (negative)
session_quota[]"s3=1": jobs of a session running at once
detect_cpu_seconds60a command outside the queue that burned this many CPU seconds: its session is told (0: off)
detect_action"notice"off | notice (a notice, listed in the jobs) | tell (its session is also told: a prompt)
hold_load1.5load per core: nothing new starts
reduce_load3.0load per core: the running jobs are reniced, the lowest priority one stopped until it falls
hold_mem_mb3000MemAvailable below: nothing new starts
reduce_mem_mb1200MemAvailable below: the running jobs are slowed
oom_mem_mb500MemAvailable below (kill_on_oom): the newest job is killed
hold_swap_mb4096swap used above, with the memory short too: nothing new starts
psi_cpu_hold80pressure stall information (avg10, %, /proc/pressure): nothing new starts / jobs slowed
psi_cpu_reduce95
psi_mem_hold20
psi_mem_reduce40
psi_io_hold50
psi_io_reduce80
resume_after20seconds under the thresholds before a stopped job resumes (hysteresis)
kill_on_oomfalsenever kill by default; true: the newest job killed under oom_mem_mb
memory_guardtrueunder guard_free_mb available: the biggest of what claude-cluster runs is killed (never the core) before the system kills anything itself; its session is told what and why, a notice and a notification too
guard_free_mb0the memory kept free (0: 5 % of the RAM, at least 500 MB)
guard_min_mb100a command smaller than this is never the one killed
aging_seconds30a waiting job gains one point every so many seconds (nothing starves; a priority step is 10 points)
focus_boost15points of the session you look at
sub_addfalsea sub-session may queue heavy jobs through the MCP (heavy_run, jobs_add): off by default (no permission prompt on that path); its Bash tool, cluster-run included, works as usual
sub_kill_owntrue... kill its own jobs
sub_see_othersfalse... see the jobs of the other sessions
notify_killedtruea notification when a job is killed (desktop, app)
notify_donefalse... when one finishes
history200finished jobs kept
proc_dir"/proc"where the load and the memory are read (a fake tree: the tests)
sys_dir"/sys"
python"~/.local/share/voice/venv/bin/python"the python of voice-listen (sherpa-onnx), its model is used
source""microphone (PulseAudio / PipeWire source), empty: the default one

13. [limits] - Accounts and limits[limits] - Comptes et limites

KeyDefaultDescription
daily_usd0.0What the sessions may spend together (the USD of the usage ledger); 0 = no limit. Settings > Accounts & limits. since the local midnight
weekly_usd0.0the last 7 days
monthly_usd0.0since the 1st of the local month
scope"keys"keys: only what an API key is billed for | all: every turn, the notional cost of a subscription too
blocktruea limit reached: the prompts are refused (send --force passes); false: only warned
warn_percent80warned at this share of a limit (0: only when it is reached)
CléDéfautDescription
daily_usd0.0What the sessions may spend together (the USD of the usage ledger); 0 = no limit. Settings > Accounts & limits. since the local midnight
weekly_usd0.0the last 7 days
monthly_usd0.0since the 1st of the local month
scope"keys"keys: only what an API key is billed for | all: every turn, the notional cost of a subscription too
blocktruea limit reached: the prompts are refused (send --force passes); false: only warned
warn_percent80warned at this share of a limit (0: only when it is reached)

14. [policy] - Model policy[policy] - Politique des modèles

KeyDefaultDescription
default_model""The model / thinking policy of the global session (Settings > Model policy): what it may choose for the sub-sessions. It runs on [global] model / effort itself (until you change them); it sets the model and the thinking of the sub-sessions by the difficulty of each task, and asks you first for the costly ones (below). the model sub-sessions start from (empty: none)
default_effort""the thinking effort they start from (empty: the default of the agent)
model_mode"advise"free: no default, by the task | advise: the default is the start, deviate for a reason | force: nothing else
effort_mode"advise"
allowed_models[]the only models it may choose (empty: every one), by name or a part of it: ["haiku", "sonnet"]
allowed_efforts[]the only efforts (empty: every one)
ask_costlytruea costly model / effort: you decide each time (Allow / Deny)
costly_models["opus", "fable"]models that cost as much or more
costly_efforts["xhigh", "max"]efforts of this level or above
CléDéfautDescription
default_model""The model / thinking policy of the global session (Settings > Model policy): what it may choose for the sub-sessions. It runs on [global] model / effort itself (until you change them); it sets the model and the thinking of the sub-sessions by the difficulty of each task, and asks you first for the costly ones (below). the model sub-sessions start from (empty: none)
default_effort""the thinking effort they start from (empty: the default of the agent)
model_mode"advise"free: no default, by the task | advise: the default is the start, deviate for a reason | force: nothing else
effort_mode"advise"
allowed_models[]the only models it may choose (empty: every one), by name or a part of it: ["haiku", "sonnet"]
allowed_efforts[]the only efforts (empty: every one)
ask_costlytruea costly model / effort: you decide each time (Allow / Deny)
costly_models["opus", "fable"]models that cost as much or more
costly_efforts["xhigh", "max"]efforts of this level or above

15. Environment variablesVariables d'environnement

VariableEffect
CLAUDE_CLUSTER_CONFIG_DIRconfig folder (default ~/.config/claude-cluster)
CLAUDE_CLUSTER_DATA_DIRstate, trash, history (default ~/.local/share/claude-cluster)
CLAUDE_CLUSTER_SOCKETcontrol socket (default $XDG_RUNTIME_DIR/claude-cluster/control.sock)
CLAUDE_CLUSTER_BACKENDsame as --backend
CLAUDE_CLUSTER_RTKsame as --rtk
CLAUDE_CLUSTER_TRANSCRIPTSfolders of the transcripts read for the usage, separated by : (empty: none)
VariableEffet
CLAUDE_CLUSTER_CONFIG_DIRdossier de configuration (défaut ~/.config/claude-cluster)
CLAUDE_CLUSTER_DATA_DIRétat, corbeille, historique (défaut ~/.local/share/claude-cluster)
CLAUDE_CLUSTER_SOCKETsocket de contrôle (défaut $XDG_RUNTIME_DIR/claude-cluster/control.sock)
CLAUDE_CLUSTER_BACKENDcomme --backend
CLAUDE_CLUSTER_RTKcomme --rtk
CLAUDE_CLUSTER_TRANSCRIPTSdossiers des transcriptions lus pour l'usage, séparés par : (vide : aucun)