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
| Key | Default | Description |
|---|---|---|
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_origin | true | the 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 |
notify | true | desktop notifications at all (the ones of the global session too) |
restart_core | true | a crashed core started again by its watcher, its sessions restored (false: no watcher) |
start_menu | true | at each start of the terminal: open the running claude-cluster / an independent instance / restore the previous run / start new / quit |
notify_global | true | when the global session answers |
notify_done | true | when a sub-session finishes its turn |
notify_permission | true | when a permission waits |
notify_sound | true | a 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_question | true | a question of an agent (its options as buttons) |
notify_error | true | an error, a crash, the safety check |
notify_limits | true | a limit close (80 / 95 %) or reached |
notify_web | true | a device asks to connect / connected (web access) |
notify_tasks | true | the task queue done |
notify_task_each | false | each task done (task_add notify: true: that one) |
notify_reminders | true | a reminder (schedule add --notify) |
notify_app | true | the same notifications published to the Android app (each phone opts in, its kinds in This device) |
notify_ready | true | something slow ready: claude-cluster started, the speech model loaded, the map written |
group_by_category | false | the session list grouped by the category of its sessions (the palette: Group by category, /group) |
vim | false | vim 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_lines | 3 | a paste of more lines is one [Pasted text #N +L lines] in the prompt (0: never) |
paste_chars | 800 | or of more characters (0: never) |
stash_max | 10 | prompts 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_rewound | false | Esc (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_days | 30 | the 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) |
typewriter | true | the answers typed as they come, also when the agent sends them at once (false: as received) |
typewriter_speed | 400 | characters per second (faster by itself when a long text is behind) |
| Clé | Défaut | Description |
|---|---|---|
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_origin | true | the 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 |
notify | true | desktop notifications at all (the ones of the global session too) |
restart_core | true | a crashed core started again by its watcher, its sessions restored (false: no watcher) |
start_menu | true | at each start of the terminal: open the running claude-cluster / an independent instance / restore the previous run / start new / quit |
notify_global | true | when the global session answers |
notify_done | true | when a sub-session finishes its turn |
notify_permission | true | when a permission waits |
notify_sound | true | a 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_question | true | a question of an agent (its options as buttons) |
notify_error | true | an error, a crash, the safety check |
notify_limits | true | a limit close (80 / 95 %) or reached |
notify_web | true | a device asks to connect / connected (web access) |
notify_tasks | true | the task queue done |
notify_task_each | false | each task done (task_add notify: true: that one) |
notify_reminders | true | a reminder (schedule add --notify) |
notify_app | true | the same notifications published to the Android app (each phone opts in, its kinds in This device) |
notify_ready | true | something slow ready: claude-cluster started, the speech model loaded, the map written |
group_by_category | false | the session list grouped by the category of its sessions (the palette: Group by category, /group) |
vim | false | vim 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_lines | 3 | a paste of more lines is one [Pasted text #N +L lines] in the prompt (0: never) |
paste_chars | 800 | or of more characters (0: never) |
stash_max | 10 | prompts 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_rewound | false | Esc (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_days | 30 | the 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) |
typewriter | true | the answers typed as they come, also when the agent sends them at once (false: as received) |
typewriter_speed | 400 | characters per second (faster by itself when a long text is behind) |
2. [agent][agent]
| Key | Default | Description |
|---|---|---|
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_bypass | true | claude: launched with --allow-dangerously-skip-permissions, so bypassPermissions can be chosen |
extra_args | [] | |
sub_pin | true | a sub-session may pin an item on its own view (never on another one); you always may, by hand |
global_pin | true | the global session may pin a message / display block at the bottom of any session (MCP session_pin) |
taxonomy_edit | true | the 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) |
workflow | false | 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): 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_detect | false | the 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_every | 20 | sessions started by the global session between two checks (0: only when asked) |
| Clé | Défaut | Description |
|---|---|---|
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_bypass | true | claude: launched with --allow-dangerously-skip-permissions, so bypassPermissions can be chosen |
extra_args | [] | |
sub_pin | true | a sub-session may pin an item on its own view (never on another one); you always may, by hand |
global_pin | true | the global session may pin a message / display block at the bottom of any session (MCP session_pin) |
taxonomy_edit | true | the 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) |
workflow | false | 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): 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_detect | false | the 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_every | 20 | sessions started by the global session between two checks (0: only when asked) |
3. [commands][commands] - Commandes
programs of the drivers
| Key | Default | Description |
|---|---|---|
sub_read | true | a sub-session lists its own tasks / schedules (MCP task_list, schedule_list) |
sub_tasks | true | ... queues tasks (MCP task_add; it manages its own ones only) |
sub_schedules | false | ... creates schedules (MCP schedule_add, schedule_edit) |
sub_spawn | false | ... makes tasks / schedules that start sessions |
sub_spawn_cap | 2 | the 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éfaut | Description |
|---|---|---|
sub_read | true | a sub-session lists its own tasks / schedules (MCP task_list, schedule_list) |
sub_tasks | true | ... queues tasks (MCP task_add; it manages its own ones only) |
sub_schedules | false | ... creates schedules (MCP schedule_add, schedule_edit) |
sub_spawn | false | ... makes tasks / schedules that start sessions |
sub_spawn_cap | 2 | the 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
| Key | Default | Description |
|---|---|---|
enabled | true | |
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éfaut | Description |
|---|---|---|
enabled | true | |
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]
| Key | Default | Description |
|---|---|---|
trash_days | 14 | a closed session stays restorable this many days |
max_parallel | 4 | task queue: sessions working at the same time |
task_result_chars | 6000 | the answer kept in a task (its result, chained with {{tN.result}}): its first characters |
budget_usd | 0.0 | 0 = 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_ttl | 5 | minutes the prompt cache lives (5; 60 with a 1 h cache), counted from the last request |
keep_warm_margin | 45 | the wake-up this many seconds before it expires (16 to 600: checked every 10 s) |
keep_warm_hours | 2 | kept warm so long after the last real use: a prompt, a take-back, /keepwarm (0: never stops); past it its ♨ goes |
questions_to_global | true | a 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_answers | false | the global session is told those questions and may choose their answer |
bypass_to_global | true | the 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_fork | false | the global session may fork a sub-session (MCP session_fork); you can always (palette, fork) |
rewrite_global_prompt | false | the global session may rewrite its own system prompt (MCP config_write global_prompt); old key global_prompts: same, as fallback |
rewrite_sessions_prompt | true | the global session may rewrite the system prompt of the sub-sessions (MCP config_write sessions_prompt) |
archive_one_shot | true | a 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_edit | false | the 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éfaut | Description |
|---|---|---|
trash_days | 14 | a closed session stays restorable this many days |
max_parallel | 4 | task queue: sessions working at the same time |
task_result_chars | 6000 | the answer kept in a task (its result, chained with {{tN.result}}): its first characters |
budget_usd | 0.0 | 0 = 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_ttl | 5 | minutes the prompt cache lives (5; 60 with a 1 h cache), counted from the last request |
keep_warm_margin | 45 | the wake-up this many seconds before it expires (16 to 600: checked every 10 s) |
keep_warm_hours | 2 | kept warm so long after the last real use: a prompt, a take-back, /keepwarm (0: never stops); past it its ♨ goes |
questions_to_global | true | a 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_answers | false | the global session is told those questions and may choose their answer |
bypass_to_global | true | the 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_fork | false | the global session may fork a sub-session (MCP session_fork); you can always (palette, fork) |
rewrite_global_prompt | false | the global session may rewrite its own system prompt (MCP config_write global_prompt); old key global_prompts: same, as fallback |
rewrite_sessions_prompt | true | the global session may rewrite the system prompt of the sub-sessions (MCP config_write sessions_prompt) |
archive_one_shot | true | a 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_edit | false | the 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
| Key | Default | Description |
|---|---|---|
enabled | false | |
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_seconds | 8 | wake 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_me | true | voice-listen --only-me (needs voice-enroll) |
confirm_seconds | 3 | the transcription is shown this long before it is sent (0: sent at once) |
speak | true | spoken summary of the answers of the global session |
summary_chars | 220 | |
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_silence | 0.0 | seconds 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éfaut | Description |
|---|---|---|
enabled | false | |
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_seconds | 8 | wake 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_me | true | voice-listen --only-me (needs voice-enroll) |
confirm_seconds | 3 | the transcription is shown this long before it is sent (0: sent at once) |
speak | true | spoken summary of the answers of the global session |
summary_chars | 220 | |
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_silence | 0.0 | seconds 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)
| Key | Default | Description |
|---|---|---|
enabled | false | opened at each start; the code (6 digits) and the address shown at the top of the interface |
port | 8787 | several devices at once; private addresses of the same subnet only (never the internet) |
https | true | TLS, certificate of its own (~/.config/claude-cluster/web): encrypted, the microphone of the page allowed |
approve | true | a new device: its code, then your yes here (allow, allow and trust, deny); the trusted ones: neither |
discovery | true | the 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éfaut | Description |
|---|---|---|
enabled | false | opened at each start; the code (6 digits) and the address shown at the top of the interface |
port | 8787 | several devices at once; private addresses of the same subnet only (never the internet) |
https | true | TLS, certificate of its own (~/.config/claude-cluster/web): encrypted, the microphone of the page allowed |
approve | true | a new device: its code, then your yes here (allow, allow and trust, deny); the trusted ones: neither |
discovery | true | the 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)
| Key | Default | Description |
|---|---|---|
enabled | true | |
max_mb | 20 | the largest file; a bigger one is refused |
max_files | 10 | per prompt |
keep | 200 | kept per session (the oldest go; all go when the session is deleted; 0: all kept) |
max_pixels | 2048 | a larger image is downscaled to this side before it is stored (0: as it is); needs ImageMagick |
strip_exif | true | images re-encoded without EXIF (GPS, camera); needs ImageMagick |
dir | "" | stored where, one folder per session (empty: <data>/attachments) |
link | true | a file of this computer linked by its path (nothing copied): window, terminal, a page on this computer |
global | true | the global session may attach a local file to a prompt (project folder / home only, no hidden folder) |
global_max | 5 | files 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éfaut | Description |
|---|---|---|
enabled | true | |
max_mb | 20 | the largest file; a bigger one is refused |
max_files | 10 | per prompt |
keep | 200 | kept per session (the oldest go; all go when the session is deleted; 0: all kept) |
max_pixels | 2048 | a larger image is downscaled to this side before it is stored (0: as it is); needs ImageMagick |
strip_exif | true | images re-encoded without EXIF (GPS, camera); needs ImageMagick |
dir | "" | stored where, one folder per session (empty: <data>/attachments) |
link | true | a file of this computer linked by its path (nothing copied): window, terminal, a page on this computer |
global | true | the global session may attach a local file to a prompt (project folder / home only, no hidden folder) |
global_max | 5 | files per prompt of the global session |
9. [mcp][mcp]
MCP of the global session (F9 > MCP)
| Key | Default | Description |
|---|---|---|
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éfaut | Description |
|---|---|---|
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)
| Key | Default | Description |
|---|---|---|
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éfaut | Description |
|---|---|---|
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
| Key | Default | Description |
|---|---|---|
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éfaut | Description |
|---|---|---|
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)
| Key | Default | Description |
|---|---|---|
enabled | true | off: 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_jobs | 0 | heavy jobs running at once (0: from the hardware, the profile, the live load and memory) |
max_per_session | 2 | running at once for one session (0: no limit) |
reserved_cpu | 2 | cores left to you and the interface |
reserved_ram_mb | 3072 | memory left to you and the interface |
threads | 0 | parallelism granted to a job (-j, --parallel, CARGO_BUILD_JOBS...; 0: from the profile) |
build_max | 0 | per class (build, tests, container, gpu, custom): running at once (0: auto; container 2, gpu 1 by default) |
tests_max | 0 | |
container_max | 2 | |
gpu_max | 1 | |
custom_max | 0 | |
build_ram_mb | 2000 | per class: the memory of one job (a clang++ job takes 1.5 - 2.5 GB); a job starts when it fits |
tests_ram_mb | 1200 | |
container_ram_mb | 1500 | |
gpu_ram_mb | 2000 | |
custom_ram_mb | 1000 | |
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_seconds | 60 | a 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_load | 1.5 | load per core: nothing new starts |
reduce_load | 3.0 | load per core: the running jobs are reniced, the lowest priority one stopped until it falls |
hold_mem_mb | 3000 | MemAvailable below: nothing new starts |
reduce_mem_mb | 1200 | MemAvailable below: the running jobs are slowed |
oom_mem_mb | 500 | MemAvailable below (kill_on_oom): the newest job is killed |
hold_swap_mb | 4096 | swap used above, with the memory short too: nothing new starts |
psi_cpu_hold | 80 | pressure stall information (avg10, %, /proc/pressure): nothing new starts / jobs slowed |
psi_cpu_reduce | 95 | |
psi_mem_hold | 20 | |
psi_mem_reduce | 40 | |
psi_io_hold | 50 | |
psi_io_reduce | 80 | |
resume_after | 20 | seconds under the thresholds before a stopped job resumes (hysteresis) |
kill_on_oom | false | never kill by default; true: the newest job killed under oom_mem_mb |
memory_guard | true | under 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_mb | 0 | the memory kept free (0: 5 % of the RAM, at least 500 MB) |
guard_min_mb | 100 | a command smaller than this is never the one killed |
aging_seconds | 30 | a waiting job gains one point every so many seconds (nothing starves; a priority step is 10 points) |
focus_boost | 15 | points of the session you look at |
sub_add | false | a 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_own | true | ... kill its own jobs |
sub_see_others | false | ... see the jobs of the other sessions |
notify_killed | true | a notification when a job is killed (desktop, app) |
notify_done | false | ... when one finishes |
history | 200 | finished 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éfaut | Description |
|---|---|---|
enabled | true | off: 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_jobs | 0 | heavy jobs running at once (0: from the hardware, the profile, the live load and memory) |
max_per_session | 2 | running at once for one session (0: no limit) |
reserved_cpu | 2 | cores left to you and the interface |
reserved_ram_mb | 3072 | memory left to you and the interface |
threads | 0 | parallelism granted to a job (-j, --parallel, CARGO_BUILD_JOBS...; 0: from the profile) |
build_max | 0 | per class (build, tests, container, gpu, custom): running at once (0: auto; container 2, gpu 1 by default) |
tests_max | 0 | |
container_max | 2 | |
gpu_max | 1 | |
custom_max | 0 | |
build_ram_mb | 2000 | per class: the memory of one job (a clang++ job takes 1.5 - 2.5 GB); a job starts when it fits |
tests_ram_mb | 1200 | |
container_ram_mb | 1500 | |
gpu_ram_mb | 2000 | |
custom_ram_mb | 1000 | |
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_seconds | 60 | a 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_load | 1.5 | load per core: nothing new starts |
reduce_load | 3.0 | load per core: the running jobs are reniced, the lowest priority one stopped until it falls |
hold_mem_mb | 3000 | MemAvailable below: nothing new starts |
reduce_mem_mb | 1200 | MemAvailable below: the running jobs are slowed |
oom_mem_mb | 500 | MemAvailable below (kill_on_oom): the newest job is killed |
hold_swap_mb | 4096 | swap used above, with the memory short too: nothing new starts |
psi_cpu_hold | 80 | pressure stall information (avg10, %, /proc/pressure): nothing new starts / jobs slowed |
psi_cpu_reduce | 95 | |
psi_mem_hold | 20 | |
psi_mem_reduce | 40 | |
psi_io_hold | 50 | |
psi_io_reduce | 80 | |
resume_after | 20 | seconds under the thresholds before a stopped job resumes (hysteresis) |
kill_on_oom | false | never kill by default; true: the newest job killed under oom_mem_mb |
memory_guard | true | under 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_mb | 0 | the memory kept free (0: 5 % of the RAM, at least 500 MB) |
guard_min_mb | 100 | a command smaller than this is never the one killed |
aging_seconds | 30 | a waiting job gains one point every so many seconds (nothing starves; a priority step is 10 points) |
focus_boost | 15 | points of the session you look at |
sub_add | false | a 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_own | true | ... kill its own jobs |
sub_see_others | false | ... see the jobs of the other sessions |
notify_killed | true | a notification when a job is killed (desktop, app) |
notify_done | false | ... when one finishes |
history | 200 | finished 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
| Key | Default | Description |
|---|---|---|
daily_usd | 0.0 | What the sessions may spend together (the USD of the usage ledger); 0 = no limit. Settings > Accounts & limits. since the local midnight |
weekly_usd | 0.0 | the last 7 days |
monthly_usd | 0.0 | since 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 |
block | true | a limit reached: the prompts are refused (send --force passes); false: only warned |
warn_percent | 80 | warned at this share of a limit (0: only when it is reached) |
| Clé | Défaut | Description |
|---|---|---|
daily_usd | 0.0 | What the sessions may spend together (the USD of the usage ledger); 0 = no limit. Settings > Accounts & limits. since the local midnight |
weekly_usd | 0.0 | the last 7 days |
monthly_usd | 0.0 | since 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 |
block | true | a limit reached: the prompts are refused (send --force passes); false: only warned |
warn_percent | 80 | warned at this share of a limit (0: only when it is reached) |
14. [policy] - Model policy[policy] - Politique des modèles
| Key | Default | Description |
|---|---|---|
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_costly | true | a 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éfaut | Description |
|---|---|---|
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_costly | true | a 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
| Variable | Effect |
|---|---|
CLAUDE_CLUSTER_CONFIG_DIR | config folder (default ~/.config/claude-cluster) |
CLAUDE_CLUSTER_DATA_DIR | state, trash, history (default ~/.local/share/claude-cluster) |
CLAUDE_CLUSTER_SOCKET | control socket (default $XDG_RUNTIME_DIR/claude-cluster/control.sock) |
CLAUDE_CLUSTER_BACKEND | same as --backend |
CLAUDE_CLUSTER_RTK | same as --rtk |
CLAUDE_CLUSTER_TRANSCRIPTS | folders of the transcripts read for the usage, separated by : (empty: none) |
| Variable | Effet |
|---|---|
CLAUDE_CLUSTER_CONFIG_DIR | dossier de configuration (défaut ~/.config/claude-cluster) |
CLAUDE_CLUSTER_DATA_DIR | état, corbeille, historique (défaut ~/.local/share/claude-cluster) |
CLAUDE_CLUSTER_SOCKET | socket de contrôle (défaut $XDG_RUNTIME_DIR/claude-cluster/control.sock) |
CLAUDE_CLUSTER_BACKEND | comme --backend |
CLAUDE_CLUSTER_RTK | comme --rtk |
CLAUDE_CLUSTER_TRANSCRIPTS | dossiers des transcriptions lus pour l'usage, séparés par : (vide : aucun) |