MCP toolsOutils MCP
Every tool of the global session, generated from the code: 79 tools with their parameters.Tous les outils de la session globale, générés depuis le code : 79 outils avec leurs paramètres.
The global session drives claude-cluster through the MCP server claude-cluster mcp. This page is generated from the tool schemas in the sources (Mcp.cpp, Orchestrator-Control.cpp): the names, descriptions and parameters below are exactly what the model is told. Each tool can be turned off in [mcp_tools] (settings page MCP): <tool> = false.
A sub-session of the claude driver has its own small MCP with task_*, schedule_* and the job tools only, limited to what it created.
La session globale pilote claude-cluster par le serveur MCP claude-cluster mcp. Cette page est générée à partir des schémas d'outils des sources (Mcp.cpp, Orchestrator-Control.cpp) : les noms, descriptions et paramètres ci-dessous sont exactement ce que le modèle reçoit. Chaque outil peut être désactivé dans [mcp_tools] (page de réglages MCP) : <outil> = false.
Les descriptions viennent du code et sont donc en anglais, la langue dans laquelle le modèle les lit.
Une sous-session du pilote claude a son propre petit MCP avec seulement task_*, schedule_* et les outils de travaux, limités à ce qu'elle a créé.
1. SessionsSessions
session_list
Every session of the cluster: id, name, project folder, backend, state, category, tags, permission mode, tokens, context, cost, pending permissions. Filters: category, tag (one or several, all required), under (a node of the taxonomy: every session below it), state (open: the live ones, default | archived: the trash | all | working, idle...). A category / tag also matches the sessions under the labels below it in the taxonomy (descendants: false: itself only).
| Parameter | Type | Description |
|---|---|---|
category | string | only this category (and the ones below it in the taxonomy) |
tag | string | only the sessions with this tag (several: separated by commas; the tags below each included) |
under | string | every session under this category / tag node of the taxonomy |
descendants | boolean | false: category / tag match themselves only, not the labels below them (default true) |
state | string | open (default) | archived (the trash) | all | a state: working, idle, waiting... |
session_status
Details of one session and its last 20 messages (skills loaded, files modified).
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
session_read
Same as session_status: the last messages of a session.
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
session_spawn
Start a new session in a project folder. backend: <provider>[/<model>] (claude, ollama/<model>, openai/<model>, opencode/<provider>/<model>, codex...). For a one-off task set one_shot: true, the session is then archived by itself when it is done.
| Parameter | Type | Description |
|---|---|---|
cwd (required) | string | project folder (~ allowed), or the name of a project of machine.md (its git repositories: the closest by its name) |
name | string | name of the session (default: the folder name) |
backend | string | provider[/model], default from the config |
mode | string | auto | manual | acceptEdits | plan | dontAsk | bypassPermissions |
profile | string | profile of the config |
prompt | string | first prompt |
reply | boolean | the answer to the first prompt (and later wake-up turns) sent back to you as "[reply from ...]" (default true) |
one_shot | boolean | this session is for ONE precise task, never to be reused: closed to the trash (restorable) once its answer is relayed to you (needs reply, and the setting Archive one-shot sessions on; kept when the user typed in it, looks at it or it waits for them). Never for the session of a project you will talk to again (default false) |
effort | string | thinking effort: default | low | medium | high | xhigh | max |
context | string | its context at most, compacted past it: 100k to 1M (200k, 500k) or auto (the setting Context at most of the sessions). Size it to the task: a small fix needs far less than a long refactor; every turn and a wake-up after its cache expired cost what it holds |
session_send
Send a prompt to a session (queued when it is working). By default (reply: true) its answer comes back to you as a message "[reply from <name> (<id>)] ..." when it is done: go on with something else or end your turn, never poll it with session_read / session_status. A local command of claude-cluster (/clear, /model <m>, /mode <m>, /rename, /cd, /close, /cost, /context, /export...) runs at once, as typed in its prompt (no reply): /clear starts a new conversation for the session.
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
text (required) | string | the prompt |
reply | boolean | its answer sent back to you when done (default true) |
attachments | string[] | paths of local files to attach to the prompt (images as pictures, the others as @path): inside the project folder of the session or the home of the user only, no hidden folder; the number is limited by a setting |
session_wait
Wait until a session is done (up to timeout seconds, 110 max) and get only its last answer (not its context); its outcome tells how its last turn ended - finished, cancelled (interrupted before it finished), error, closed: only finished is done, never take the others as finished: when you need the answer now to go on. A permission waiting is told.
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
timeout | integer | seconds (default 100) |
session_allow
Answer a pending permission of a session; a question of its agent (AskUserQuestion, its options in session_status): answers {question text: the label chosen, several joined by ", "} (behavior deny: declined).
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
request_id | string | request id (empty: the oldest one) |
behavior | string | allow | always | deny |
answers | object | AskUserQuestion: {question text: answer} |
session_set_mode
Permission mode of a session.
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
mode (required) | string | auto | manual | acceptEdits | plan | dontAsk | bypassPermissions |
session_set_model
Model and / or thinking effort of a session (the same conversation goes on); none given: its current ones and the choices of its backend. Under the policy of the user (models_policy): a forbidden one is refused with the reason; a costly one (opus, xhigh...) returns {asked}: the user answers Allow / Deny in their interface and the result comes back to you as a message.
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
model | string | a model of its provider (opus, sonnet, claude-opus-5-5, an Ollama model...) |
effort | string | default | low | medium | high | xhigh | max (claude); minimal... (codex, opencode) |
session_interrupt
Stop the running turn of a session.
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
session_close
Close a session: it goes to the trash, restorable with session_restore.
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
session_restore
Restore a closed session from the trash (with its conversation).
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id or name in the trash |
session_trash
Closed sessions that can still be restored.
No parameter.
session_purge
Delete for good a session of the trash (its conversation and history), "*" for the whole trash. Irreversible: only when the user asked it.
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id or name in the trash, or * |
session_rename
Rename a session.
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
name (required) | string | new name |
session_continue
A session goes on where it stopped (interrupted, an error of the API or of the connection): "continue" sent in the same conversation; a turn waiting for a retry of the API: stopped and asked again at once.
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
session_describe
Give a session its short description (a few words: what it works on, holds; shown under its name, the trash too, to find it again), its category (ONE word: bugfix, feature, docs, refactor, research, ops...) and its tags (several short words: the topic, the project, the kind of work), the way to find and group sessions (session_list filters, search "#tag"). Set them when you spawn or route a session and keep them true as its topic moves; reuse the ones already in session_list. A text given: kept; empty: claude-cluster writes it again; no text: untouched. category "" removes it; tags replaces all of them, add_tags / remove_tags change some. The user can edit them too; no model is called.
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
text | string | a few words, empty: written again; leave out to keep it |
category | string | one word, "" removes it |
tags | string[] | all its tags (replaces them) |
add_tags | string[] | tags to add |
remove_tags | string[] | tags to remove |
session_cd
Move a session to another project folder (a new conversation there, same name).
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
cwd (required) | string | folder |
session_fanout
A request on several sessions / projects at once (a group): a task each, sent as many at once as the parallel sessions allow (the others wait in the task queue); you are woken ONCE with their answers as [group fN ...] to merge them - end your turn after it, never poll. tasks: [{session or cwd, prompt (else the common prompt), after: [indexes of tasks of this group it builds on: their answers given to it]}]; match: {under: folder, has: a file marking a project (default: a git repository), name: part of its name, max} for every project found (its session reused, else created: shown to the user first, then confirmed: true); wait: {mode: all | first | count, count, timeout_minutes (then woken with what came), stop_others (the wait met: the others stopped)}; retry (a failed task tried once more, default true); merge: here (you) | session (a big merge by a session of its own, its answer to you); table: a comparison table asked too.
| Parameter | Type | Description |
|---|---|---|
label (required) | string | what the group does, a few words |
prompt | string | the common prompt |
tasks | object[] | [{session | cwd, prompt, after: [index]}] |
match | object | {under, has, name, max} |
wait | object | {mode: all | first | count, count, timeout_minutes, stop_others} |
retry | boolean | |
merge | string | here | session |
table | boolean | |
confirmed | boolean | the user agreed to the projects found (match) |
group_status
The progress of a group (its tasks, their state and answers so far); none: every group of this run.
| Parameter | Type | Description |
|---|---|---|
group | string | fN |
group_cancel
Stop a group: its tasks not started are cancelled, the running ones interrupted when interrupt is true.
| Parameter | Type | Description |
|---|---|---|
group (required) | string | fN |
interrupt | boolean |
session_fork
A copy of a sub-session of Claude Code: a new sub-session with its conversation so far (its context), each one goes on apart. Only when the user allowed it (settings: Global session can fork).
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
name | string | name of the copy |
session_import
Open a conversation of another agent (external_conversations) as a sub-session resuming it: its transcript shown, the same conversation goes on here. fork (Claude Code): a copy, the original untouched - use it when it may still be open elsewhere.
| Parameter | Type | Description |
|---|---|---|
agent (required) | string | claude | codex | opencode | qwen |
id (required) | string | its id (a unique prefix is enough) |
name | string | name of the session |
fork | boolean | a copy (Claude Code) |
external_conversations
The conversations of the agents of this computer opened outside claude-cluster (Claude Code, Codex, opencode, Qwen Code): agent, id, title, folder, first prompt, age; the newest first. To open one here: session_import.
| Parameter | Type | Description |
|---|---|---|
agent | string | claude | codex | opencode | qwen (empty: all) |
limit | integer | 30 by default |
session_context
Give a context to a session as a prompt it keeps for its next requests (it answers "ok"): source = session:<id> (the conversation of another session), <agent>:<id> (a conversation of external_conversations), or a file path.
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
source (required) | string | session:<id> | claude:<id> | codex:<id> | qwen:<id> | a file |
session_transcript
The transcript of a session, whole entries (not cut like session_read): index, kind (user, assistant, tool, tool_result, system, display), text. from: the first index (negative: from the end, -50 by default), count (50, 500 max).
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
from | integer | |
count | integer |
session_messages
The real conversation of a sub-session of Claude Code (what its model sees): its messages with index, role, text, tools. To rewrite it: session_edit.
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
session_edit
Rewrite the conversation of a sub-session of Claude Code (indexes of session_messages): replace texts, delete messages (a tool call and its result go together), keep only the first N; written as a new conversation (the old one kept), the session started again on it, its transcript shown again. Only when it is idle and the user allowed it (settings: Global session can edit).
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
replace | any[] | [{index, text}] |
delete | any[] | [index, ...] |
keep | integer | keep the first N messages |
search
Full-text search in the history of every session, and in their categories and tags ("#bugfix": the sessions with that category or tag only).
| Parameter | Type | Description |
|---|---|---|
text (required) | string | text to find |
export
Export the conversation of a session as Markdown (to a file when path is given: a .md / .txt out of the hidden folders).
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
path | string | file (optional) |
taxonomy
The tree of the categories and tags of the sessions: each node (a category or a tag) has an optional parent, none: it hangs under the root "global"; a session hangs under its category, else its first tag. The graph and the grouped list show it nested, session_list filters work on the descendants. action list (default): {parents: {node: parent}, labels: {label: sessions}}; set_parent (node, parent; none or global: the root; a cycle is refused); rename (node, to: also on every session); merge (node, to: the node it joins); delete (node: its children go to its parent; strip: the label also removed from the sessions). Build it as the sessions come: group the tags you reuse (api, ui, db) under one broader node (backend, frontend), not one node per session. Only when the user allowed it (settings: Global session can edit the taxonomy); they edit it by hand too.
| Parameter | Type | Description |
|---|---|---|
action | string | default list |
node | string | the category / tag to change |
parent | string | set_parent: its parent node (none or global: under the root) |
to | string | rename: the new name; merge: the node it joins |
strip | boolean | delete: also remove the label from the sessions (default false) |
session_list
Every session of the cluster: id, name, project folder, backend, state, category, tags, permission mode, tokens, context, cost, pending permissions. Filters: category, tag (one or several, all required), under (a node of the taxonomy: every session below it), state (open: the live ones, default | archived: the trash | all | working, idle...). A category / tag also matches the sessions under the labels below it in the taxonomy (descendants: false: itself only).
| Paramètre | Type | Description |
|---|---|---|
category | string | only this category (and the ones below it in the taxonomy) |
tag | string | only the sessions with this tag (several: separated by commas; the tags below each included) |
under | string | every session under this category / tag node of the taxonomy |
descendants | boolean | false: category / tag match themselves only, not the labels below them (default true) |
state | string | open (default) | archived (the trash) | all | a state: working, idle, waiting... |
session_status
Details of one session and its last 20 messages (skills loaded, files modified).
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
session_read
Same as session_status: the last messages of a session.
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
session_spawn
Start a new session in a project folder. backend: <provider>[/<model>] (claude, ollama/<model>, openai/<model>, opencode/<provider>/<model>, codex...). For a one-off task set one_shot: true, the session is then archived by itself when it is done.
| Paramètre | Type | Description |
|---|---|---|
cwd (requis) | string | project folder (~ allowed), or the name of a project of machine.md (its git repositories: the closest by its name) |
name | string | name of the session (default: the folder name) |
backend | string | provider[/model], default from the config |
mode | string | auto | manual | acceptEdits | plan | dontAsk | bypassPermissions |
profile | string | profile of the config |
prompt | string | first prompt |
reply | boolean | the answer to the first prompt (and later wake-up turns) sent back to you as "[reply from ...]" (default true) |
one_shot | boolean | this session is for ONE precise task, never to be reused: closed to the trash (restorable) once its answer is relayed to you (needs reply, and the setting Archive one-shot sessions on; kept when the user typed in it, looks at it or it waits for them). Never for the session of a project you will talk to again (default false) |
effort | string | thinking effort: default | low | medium | high | xhigh | max |
context | string | its context at most, compacted past it: 100k to 1M (200k, 500k) or auto (the setting Context at most of the sessions). Size it to the task: a small fix needs far less than a long refactor; every turn and a wake-up after its cache expired cost what it holds |
session_send
Send a prompt to a session (queued when it is working). By default (reply: true) its answer comes back to you as a message "[reply from <name> (<id>)] ..." when it is done: go on with something else or end your turn, never poll it with session_read / session_status. A local command of claude-cluster (/clear, /model <m>, /mode <m>, /rename, /cd, /close, /cost, /context, /export...) runs at once, as typed in its prompt (no reply): /clear starts a new conversation for the session.
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
text (requis) | string | the prompt |
reply | boolean | its answer sent back to you when done (default true) |
attachments | string[] | paths of local files to attach to the prompt (images as pictures, the others as @path): inside the project folder of the session or the home of the user only, no hidden folder; the number is limited by a setting |
session_wait
Wait until a session is done (up to timeout seconds, 110 max) and get only its last answer (not its context); its outcome tells how its last turn ended - finished, cancelled (interrupted before it finished), error, closed: only finished is done, never take the others as finished: when you need the answer now to go on. A permission waiting is told.
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
timeout | integer | seconds (default 100) |
session_allow
Answer a pending permission of a session; a question of its agent (AskUserQuestion, its options in session_status): answers {question text: the label chosen, several joined by ", "} (behavior deny: declined).
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
request_id | string | request id (empty: the oldest one) |
behavior | string | allow | always | deny |
answers | object | AskUserQuestion: {question text: answer} |
session_set_mode
Permission mode of a session.
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
mode (requis) | string | auto | manual | acceptEdits | plan | dontAsk | bypassPermissions |
session_set_model
Model and / or thinking effort of a session (the same conversation goes on); none given: its current ones and the choices of its backend. Under the policy of the user (models_policy): a forbidden one is refused with the reason; a costly one (opus, xhigh...) returns {asked}: the user answers Allow / Deny in their interface and the result comes back to you as a message.
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
model | string | a model of its provider (opus, sonnet, claude-opus-5-5, an Ollama model...) |
effort | string | default | low | medium | high | xhigh | max (claude); minimal... (codex, opencode) |
session_interrupt
Stop the running turn of a session.
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
session_close
Close a session: it goes to the trash, restorable with session_restore.
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
session_restore
Restore a closed session from the trash (with its conversation).
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id or name in the trash |
session_trash
Closed sessions that can still be restored.
Aucun paramètre.
session_purge
Delete for good a session of the trash (its conversation and history), "*" for the whole trash. Irreversible: only when the user asked it.
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id or name in the trash, or * |
session_rename
Rename a session.
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
name (requis) | string | new name |
session_continue
A session goes on where it stopped (interrupted, an error of the API or of the connection): "continue" sent in the same conversation; a turn waiting for a retry of the API: stopped and asked again at once.
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
session_describe
Give a session its short description (a few words: what it works on, holds; shown under its name, the trash too, to find it again), its category (ONE word: bugfix, feature, docs, refactor, research, ops...) and its tags (several short words: the topic, the project, the kind of work), the way to find and group sessions (session_list filters, search "#tag"). Set them when you spawn or route a session and keep them true as its topic moves; reuse the ones already in session_list. A text given: kept; empty: claude-cluster writes it again; no text: untouched. category "" removes it; tags replaces all of them, add_tags / remove_tags change some. The user can edit them too; no model is called.
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
text | string | a few words, empty: written again; leave out to keep it |
category | string | one word, "" removes it |
tags | string[] | all its tags (replaces them) |
add_tags | string[] | tags to add |
remove_tags | string[] | tags to remove |
session_cd
Move a session to another project folder (a new conversation there, same name).
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
cwd (requis) | string | folder |
session_fanout
A request on several sessions / projects at once (a group): a task each, sent as many at once as the parallel sessions allow (the others wait in the task queue); you are woken ONCE with their answers as [group fN ...] to merge them - end your turn after it, never poll. tasks: [{session or cwd, prompt (else the common prompt), after: [indexes of tasks of this group it builds on: their answers given to it]}]; match: {under: folder, has: a file marking a project (default: a git repository), name: part of its name, max} for every project found (its session reused, else created: shown to the user first, then confirmed: true); wait: {mode: all | first | count, count, timeout_minutes (then woken with what came), stop_others (the wait met: the others stopped)}; retry (a failed task tried once more, default true); merge: here (you) | session (a big merge by a session of its own, its answer to you); table: a comparison table asked too.
| Paramètre | Type | Description |
|---|---|---|
label (requis) | string | what the group does, a few words |
prompt | string | the common prompt |
tasks | object[] | [{session | cwd, prompt, after: [index]}] |
match | object | {under, has, name, max} |
wait | object | {mode: all | first | count, count, timeout_minutes, stop_others} |
retry | boolean | |
merge | string | here | session |
table | boolean | |
confirmed | boolean | the user agreed to the projects found (match) |
group_status
The progress of a group (its tasks, their state and answers so far); none: every group of this run.
| Paramètre | Type | Description |
|---|---|---|
group | string | fN |
group_cancel
Stop a group: its tasks not started are cancelled, the running ones interrupted when interrupt is true.
| Paramètre | Type | Description |
|---|---|---|
group (requis) | string | fN |
interrupt | boolean |
session_fork
A copy of a sub-session of Claude Code: a new sub-session with its conversation so far (its context), each one goes on apart. Only when the user allowed it (settings: Global session can fork).
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
name | string | name of the copy |
session_import
Open a conversation of another agent (external_conversations) as a sub-session resuming it: its transcript shown, the same conversation goes on here. fork (Claude Code): a copy, the original untouched - use it when it may still be open elsewhere.
| Paramètre | Type | Description |
|---|---|---|
agent (requis) | string | claude | codex | opencode | qwen |
id (requis) | string | its id (a unique prefix is enough) |
name | string | name of the session |
fork | boolean | a copy (Claude Code) |
external_conversations
The conversations of the agents of this computer opened outside claude-cluster (Claude Code, Codex, opencode, Qwen Code): agent, id, title, folder, first prompt, age; the newest first. To open one here: session_import.
| Paramètre | Type | Description |
|---|---|---|
agent | string | claude | codex | opencode | qwen (empty: all) |
limit | integer | 30 by default |
session_context
Give a context to a session as a prompt it keeps for its next requests (it answers "ok"): source = session:<id> (the conversation of another session), <agent>:<id> (a conversation of external_conversations), or a file path.
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
source (requis) | string | session:<id> | claude:<id> | codex:<id> | qwen:<id> | a file |
session_transcript
The transcript of a session, whole entries (not cut like session_read): index, kind (user, assistant, tool, tool_result, system, display), text. from: the first index (negative: from the end, -50 by default), count (50, 500 max).
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
from | integer | |
count | integer |
session_messages
The real conversation of a sub-session of Claude Code (what its model sees): its messages with index, role, text, tools. To rewrite it: session_edit.
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
session_edit
Rewrite the conversation of a sub-session of Claude Code (indexes of session_messages): replace texts, delete messages (a tool call and its result go together), keep only the first N; written as a new conversation (the old one kept), the session started again on it, its transcript shown again. Only when it is idle and the user allowed it (settings: Global session can edit).
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
replace | any[] | [{index, text}] |
delete | any[] | [index, ...] |
keep | integer | keep the first N messages |
search
Full-text search in the history of every session, and in their categories and tags ("#bugfix": the sessions with that category or tag only).
| Paramètre | Type | Description |
|---|---|---|
text (requis) | string | text to find |
export
Export the conversation of a session as Markdown (to a file when path is given: a .md / .txt out of the hidden folders).
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
path | string | file (optional) |
taxonomy
The tree of the categories and tags of the sessions: each node (a category or a tag) has an optional parent, none: it hangs under the root "global"; a session hangs under its category, else its first tag. The graph and the grouped list show it nested, session_list filters work on the descendants. action list (default): {parents: {node: parent}, labels: {label: sessions}}; set_parent (node, parent; none or global: the root; a cycle is refused); rename (node, to: also on every session); merge (node, to: the node it joins); delete (node: its children go to its parent; strip: the label also removed from the sessions). Build it as the sessions come: group the tags you reuse (api, ui, db) under one broader node (backend, frontend), not one node per session. Only when the user allowed it (settings: Global session can edit the taxonomy); they edit it by hand too.
| Paramètre | Type | Description |
|---|---|---|
action | string | default list |
node | string | the category / tag to change |
parent | string | set_parent: its parent node (none or global: under the root) |
to | string | rename: the new name; merge: the node it joins |
strip | boolean | delete: also remove the label from the sessions (default false) |
2. Tasks, schedules and notificationsTâches, planifications et notifications
task_add
Queue a task for a free session (target = session id / name, a project folder, or empty: any idle one). Runs when its triggers are met (after: task ids; after_sessions: sessions idle; on_event) and a place is free (max_parallel). The result (its answer, capped) stays in task_list; "{{t3.result}}" in a prompt is replaced by the result of t3 (a chain: t3 runs first). A task is cheaper than a session: no new context.
| Parameter | Type | Description |
|---|---|---|
prompt (required) | string | the task |
target | string | session or folder (optional) |
after | string[] | task ids to finish first |
after_sessions | string[] | sessions (id / name) that must be idle first |
on_event | object | wait for {type: session_idle (session) | git_push (repo, branch: a commit pushed) | command (command; met when it exits 0, or code: N; and its output: stdout exactly / contains / regex; every: seconds or 'constantly' (default 30); fail_after: N failures in a row = the task fails and you are told, 1 = the first, 0 = never) | file (path, changed: true = modified, not only present)} |
spawn | object | its own session instead of looking for one: {cwd, name, backend, mode, effort, profile, one_shot (closed to the trash after it)} |
priority | integer | higher first (default 0) |
timeout_minutes | integer | stopped when running longer |
retry | integer | tried again this many times after an error |
retry_delay_minutes | integer | wait before a new try |
max_concurrency | integer | at most this many tasks of its lane running |
lane | string | the group max_concurrency counts in |
max_cost | number | stopped when its session costs more (USD) |
max_tokens | integer | stopped past this many tokens |
expect | string | output asked: compact, or a file path it writes (the result is then the file) |
notify | boolean | a desktop notification at its end |
reply | boolean | its end told to you as a message (default true) |
task_list
Tasks of the queue and their status, result, retries (a failed one: its reason in "error"; the finished ones are archived after 30 minutes: archived: true lists them too).
| Parameter | Type | Description |
|---|---|---|
archived | boolean | also the archived tasks (default false) |
status | string | only this status: queued | running | done | failed | cancelled |
id | string | one task |
task_act
Act on a task: cancel | delete | archive | unarchive | force (started now, past the limit of parallel sessions) | retry (a failed one again) | set (change priority, timeout_minutes, retry, max_cost, max_tokens, notify, prompt of one not ended).
| Parameter | Type | Description |
|---|---|---|
id (required) | string | task id (task_list) |
action (required) | string | cancel | delete | archive | unarchive | force | retry | set |
reason | string | why (optional) |
priority | integer | set |
timeout_minutes | integer | set |
retry | integer | set |
max_cost | number | |
max_tokens | integer | set |
notify | boolean | set |
task_cancel
Cancel a task.
| Parameter | Type | Description |
|---|---|---|
id (required) | string | task id (t1...) |
schedule_add
Do something at a time or on a rule, while claude-cluster runs. action: prompt (default: to session, you by default - a wake up / reminder "[scheduled wN] text") | notify (desktop) | spawn (a session, options.cwd, text = its prompt) | task (queue a task with options) | command (options.command run locally, NO model: only its output, when not empty, is sent to session / notified - 0 token). When: when (+30m, HH:MM, YYYY-MM-DD HH:MM) once, every (minutes), cron ("min hour day month weekday"), reset (5h | 7d: at each reset of that limit window); limited by days (mon-fri), window ("09:00-18:00"), quiet ("22:00-07:00"), tz (Europe/Paris), until, max_runs. Condition if: {session_idle, command (exits 0), file_changed, usage: "5h>80" | "7d<30"}; not met: that run is skipped. ack: asked again every nag minutes until schedule_act ack. dry_run: only shows when it would fire.
| Parameter | Type | Description |
|---|---|---|
when | string | +30m, +2h, +1d, HH:MM (today, else tomorrow), YYYY-MM-DD HH:MM (in tz) |
text (required) | string | the prompt / the notification / the task |
action | string | prompt (default) | notify | spawn | task | command |
session | string | the session of a prompt / of the output (default: g, you) |
every | integer | minutes between two (0 / missing: once) |
cron | string | min hour day-of-month month weekday: */15 9-17 * * mon-fri |
days | string | only these days: mon-fri, mon,wed, weekdays, weekend |
window | string | only inside: HH:MM-HH:MM[,HH:MM-HH:MM] |
quiet | string | never inside: HH:MM-HH:MM |
tz | string | timezone of the above (default: this computer's) |
until | string | ended after this time (when's formats) |
max_runs | integer | ended after this many runs |
reset | string | 5h | 7d |
ack | boolean | asked again until acknowledged |
nag | integer | minutes between asks (default 10) |
if | object | {session_idle, command (+ code, stdout / contains / regex: what it must return; fail_after: failures in a row before the schedule is cancelled), file_changed, usage} |
options | object | spawn: {cwd, name, backend, mode, effort, profile, one_shot}; task: the options of task_add (target, priority, retry...); command: {command, output: prompt | notify, cwd, timeout_seconds} |
dry_run | boolean | nothing made: the next times it would fire |
schedule_list
The schedules: id, status, next time and the next ones, rules, conditions, runs, skipped, last runs (history), note.
| Parameter | Type | Description |
|---|---|---|
archived | boolean | also the archived |
id | string | one schedule |
schedule_edit
Change a schedule not ended: any field of schedule_add (when, text, every, cron, days, window, quiet, tz, until, max_runs, if, options...), pause: true / false.
| Parameter | Type | Description |
|---|---|---|
id (required) | string | schedule id (w1...) |
when | string | a new time |
text | string | |
every | integer | minutes |
cron | string | |
days | string | |
window | string | |
quiet | string | |
tz | string | |
until | string | |
max_runs | integer | |
pause | boolean | paused / resumed |
if | object | |
options | object |
schedule_act
Act on a schedule: pause | resume | snooze (minutes: pushed back, default 30) | ack (stops the asks of an ack reminder) | trigger (run now, its conditions skipped) | cancel | delete | archive | unarchive.
| Parameter | Type | Description |
|---|---|---|
id (required) | string | schedule id |
action (required) | string | pause | resume | snooze | ack | trigger | cancel | delete | archive | unarchive |
minutes | integer | snooze |
reason | string | why (optional) |
schedule_cancel
Cancel a schedule.
| Parameter | Type | Description |
|---|---|---|
id (required) | string | schedule id (w1...) |
notify
A desktop notification to the user now (something done, something needing them); off when the user turned them off.
| Parameter | Type | Description |
|---|---|---|
text (required) | string | the message |
title | string | its title (default: claude-cluster) |
urgent | boolean | stays on screen |
task_add
Queue a task for a free session (target = session id / name, a project folder, or empty: any idle one). Runs when its triggers are met (after: task ids; after_sessions: sessions idle; on_event) and a place is free (max_parallel). The result (its answer, capped) stays in task_list; "{{t3.result}}" in a prompt is replaced by the result of t3 (a chain: t3 runs first). A task is cheaper than a session: no new context.
| Paramètre | Type | Description |
|---|---|---|
prompt (requis) | string | the task |
target | string | session or folder (optional) |
after | string[] | task ids to finish first |
after_sessions | string[] | sessions (id / name) that must be idle first |
on_event | object | wait for {type: session_idle (session) | git_push (repo, branch: a commit pushed) | command (command; met when it exits 0, or code: N; and its output: stdout exactly / contains / regex; every: seconds or 'constantly' (default 30); fail_after: N failures in a row = the task fails and you are told, 1 = the first, 0 = never) | file (path, changed: true = modified, not only present)} |
spawn | object | its own session instead of looking for one: {cwd, name, backend, mode, effort, profile, one_shot (closed to the trash after it)} |
priority | integer | higher first (default 0) |
timeout_minutes | integer | stopped when running longer |
retry | integer | tried again this many times after an error |
retry_delay_minutes | integer | wait before a new try |
max_concurrency | integer | at most this many tasks of its lane running |
lane | string | the group max_concurrency counts in |
max_cost | number | stopped when its session costs more (USD) |
max_tokens | integer | stopped past this many tokens |
expect | string | output asked: compact, or a file path it writes (the result is then the file) |
notify | boolean | a desktop notification at its end |
reply | boolean | its end told to you as a message (default true) |
task_list
Tasks of the queue and their status, result, retries (a failed one: its reason in "error"; the finished ones are archived after 30 minutes: archived: true lists them too).
| Paramètre | Type | Description |
|---|---|---|
archived | boolean | also the archived tasks (default false) |
status | string | only this status: queued | running | done | failed | cancelled |
id | string | one task |
task_act
Act on a task: cancel | delete | archive | unarchive | force (started now, past the limit of parallel sessions) | retry (a failed one again) | set (change priority, timeout_minutes, retry, max_cost, max_tokens, notify, prompt of one not ended).
| Paramètre | Type | Description |
|---|---|---|
id (requis) | string | task id (task_list) |
action (requis) | string | cancel | delete | archive | unarchive | force | retry | set |
reason | string | why (optional) |
priority | integer | set |
timeout_minutes | integer | set |
retry | integer | set |
max_cost | number | |
max_tokens | integer | set |
notify | boolean | set |
task_cancel
Cancel a task.
| Paramètre | Type | Description |
|---|---|---|
id (requis) | string | task id (t1...) |
schedule_add
Do something at a time or on a rule, while claude-cluster runs. action: prompt (default: to session, you by default - a wake up / reminder "[scheduled wN] text") | notify (desktop) | spawn (a session, options.cwd, text = its prompt) | task (queue a task with options) | command (options.command run locally, NO model: only its output, when not empty, is sent to session / notified - 0 token). When: when (+30m, HH:MM, YYYY-MM-DD HH:MM) once, every (minutes), cron ("min hour day month weekday"), reset (5h | 7d: at each reset of that limit window); limited by days (mon-fri), window ("09:00-18:00"), quiet ("22:00-07:00"), tz (Europe/Paris), until, max_runs. Condition if: {session_idle, command (exits 0), file_changed, usage: "5h>80" | "7d<30"}; not met: that run is skipped. ack: asked again every nag minutes until schedule_act ack. dry_run: only shows when it would fire.
| Paramètre | Type | Description |
|---|---|---|
when | string | +30m, +2h, +1d, HH:MM (today, else tomorrow), YYYY-MM-DD HH:MM (in tz) |
text (requis) | string | the prompt / the notification / the task |
action | string | prompt (default) | notify | spawn | task | command |
session | string | the session of a prompt / of the output (default: g, you) |
every | integer | minutes between two (0 / missing: once) |
cron | string | min hour day-of-month month weekday: */15 9-17 * * mon-fri |
days | string | only these days: mon-fri, mon,wed, weekdays, weekend |
window | string | only inside: HH:MM-HH:MM[,HH:MM-HH:MM] |
quiet | string | never inside: HH:MM-HH:MM |
tz | string | timezone of the above (default: this computer's) |
until | string | ended after this time (when's formats) |
max_runs | integer | ended after this many runs |
reset | string | 5h | 7d |
ack | boolean | asked again until acknowledged |
nag | integer | minutes between asks (default 10) |
if | object | {session_idle, command (+ code, stdout / contains / regex: what it must return; fail_after: failures in a row before the schedule is cancelled), file_changed, usage} |
options | object | spawn: {cwd, name, backend, mode, effort, profile, one_shot}; task: the options of task_add (target, priority, retry...); command: {command, output: prompt | notify, cwd, timeout_seconds} |
dry_run | boolean | nothing made: the next times it would fire |
schedule_list
The schedules: id, status, next time and the next ones, rules, conditions, runs, skipped, last runs (history), note.
| Paramètre | Type | Description |
|---|---|---|
archived | boolean | also the archived |
id | string | one schedule |
schedule_edit
Change a schedule not ended: any field of schedule_add (when, text, every, cron, days, window, quiet, tz, until, max_runs, if, options...), pause: true / false.
| Paramètre | Type | Description |
|---|---|---|
id (requis) | string | schedule id (w1...) |
when | string | a new time |
text | string | |
every | integer | minutes |
cron | string | |
days | string | |
window | string | |
quiet | string | |
tz | string | |
until | string | |
max_runs | integer | |
pause | boolean | paused / resumed |
if | object | |
options | object |
schedule_act
Act on a schedule: pause | resume | snooze (minutes: pushed back, default 30) | ack (stops the asks of an ack reminder) | trigger (run now, its conditions skipped) | cancel | delete | archive | unarchive.
| Paramètre | Type | Description |
|---|---|---|
id (requis) | string | schedule id |
action (requis) | string | pause | resume | snooze | ack | trigger | cancel | delete | archive | unarchive |
minutes | integer | snooze |
reason | string | why (optional) |
schedule_cancel
Cancel a schedule.
| Paramètre | Type | Description |
|---|---|---|
id (requis) | string | schedule id (w1...) |
notify
A desktop notification to the user now (something done, something needing them); off when the user turned them off.
| Paramètre | Type | Description |
|---|---|---|
text (requis) | string | the message |
title | string | its title (default: claude-cluster) |
urgent | boolean | stays on screen |
3. Displays and pinsAffichages et épingles
session_display
Show something in the transcript of a session (any sub-session, or g: yours) without a prompt: its agent never sees it, the user does (terminal, window, web page). display = {type, title?, ...}: (the catalogue of display types: see Rich displays). Or only text (markdown). For the user: a summary table, a chart of numbers, a diagram of an architecture, an image file, a drawing (SVG), a callout, a progress bar.
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
display | object | {type, ...} |
text | string | markdown (when no display) |
title | string | its title |
session_display_update
Replace a display you put (its id, given back by session_display): the steps of a long work, a progress, a checklist, a table that changes. The user sees it change in place.
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
id (required) | string | its id |
display (required) | object | {type, ...} |
session_display_get
A display of a session as it is now: the items the user ticked (checklist), the buttons clicked (actions), the values sent (form, they also come to you as a message).
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
id (required) | string | its id |
session_pin
Pin something at the bottom of the view of a session (above its prompt, always visible whatever the scroll; one pin per session, a new one replaces it): a task list / checklist / steps / form the user needs to keep seeing, a table, a note. A live display stays live while pinned (session_display_update). Give display (the id of a display, or a block {type, ...} put in the transcript and pinned at once) or index (an entry of session_transcript: a display or a message). Only when the user allowed it (settings: Global session can pin); they can unpin by hand.
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
display | any | id of a display (session_display), or a block {type, ...} |
index | integer | an entry of the transcript (negative: from the end) |
title | string | its title |
session_unpin
Remove the pin of a session (its item stays in the transcript).
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
session_pin_get
What is pinned on a session: {kind, id, title, by}, or nothing.
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
session_display
Show something in the transcript of a session (any sub-session, or g: yours) without a prompt: its agent never sees it, the user does (terminal, window, web page). display = {type, title?, ...}: (the catalogue of display types: see Rich displays). Or only text (markdown). For the user: a summary table, a chart of numbers, a diagram of an architecture, an image file, a drawing (SVG), a callout, a progress bar.
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
display | object | {type, ...} |
text | string | markdown (when no display) |
title | string | its title |
session_display_update
Replace a display you put (its id, given back by session_display): the steps of a long work, a progress, a checklist, a table that changes. The user sees it change in place.
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
id (requis) | string | its id |
display (requis) | object | {type, ...} |
session_display_get
A display of a session as it is now: the items the user ticked (checklist), the buttons clicked (actions), the values sent (form, they also come to you as a message).
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
id (requis) | string | its id |
session_pin
Pin something at the bottom of the view of a session (above its prompt, always visible whatever the scroll; one pin per session, a new one replaces it): a task list / checklist / steps / form the user needs to keep seeing, a table, a note. A live display stays live while pinned (session_display_update). Give display (the id of a display, or a block {type, ...} put in the transcript and pinned at once) or index (an entry of session_transcript: a display or a message). Only when the user allowed it (settings: Global session can pin); they can unpin by hand.
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
display | any | id of a display (session_display), or a block {type, ...} |
index | integer | an entry of the transcript (negative: from the end) |
title | string | its title |
session_unpin
Remove the pin of a session (its item stays in the transcript).
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
session_pin_get
What is pinned on a session: {kind, id, title, by}, or nothing.
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
4. Orchestrator and heavy jobsOrchestrateur et travaux lourds
heavy_run
Run a HEAVY command (a build, the tests, a container / media job, a local model) through the resource orchestrator of this computer: it waits in the queue for a free slot, then runs in the low profile (nice, ionice, the parallelism lowered to the share granted), and its result comes back HERE: finished (exit code, duration, tail of its output), failed, killed (by whom), or - when it waits or runs longer than the timeout - waiting (position, ETA, what it waits for) / running: then go on with something else and ask job_status (cheap) or job_wait, never poll in a loop. Use it instead of running heavy commands yourself, or cluster-run -- <cmd> in your own shell. Light commands (ls, grep, git status...) never go through it.
| Parameter | Type | Description |
|---|---|---|
command (required) | string | the shell command |
class | string | build | tests | container | gpu | custom (default: guessed from the command) |
prio | integer | -10..10, higher first (default 0) |
name | string | a short name shown in the queue |
cwd | string | folder it runs in (default: the one of claude-cluster) |
timeout_minutes | integer | killed when it runs longer |
ram_mb | integer | memory it needs, when not the usual of its class |
timeout | integer | seconds to wait here (default 100, 110 max): then the job is told waiting / running and goes on, follow it with job_status / job_wait |
jobs_add
Queue a heavy command WITHOUT waiting for it: you get its id and position at once, and are woken up with a message [job jN finished|failed|killed] (exit code, duration, tail of the output; killed: by whom) when it ends, so end your turn instead of polling. Same queue and low profile as heavy_run.
| Parameter | Type | Description |
|---|---|---|
command (required) | string | the shell command |
class | string | build | tests | container | gpu | custom (default: guessed from the command) |
prio | integer | -10..10, higher first (default 0) |
name | string | a short name shown in the queue |
cwd | string | folder it runs in (default: the one of claude-cluster) |
timeout_minutes | integer | killed when it runs longer |
ram_mb | integer | memory it needs, when not the usual of its class |
callback | boolean | you are woken up with a message [job jN ...] (exit code, duration, tail) when it ends or is killed (default true) |
session | string | the session the job belongs to and to wake up (global session only; default: you) |
jobs_list
The jobs of the orchestrator: running, waiting (position, what they wait for), stopped; state all adds the finished ones. A sub-session sees its own jobs (the user's settings may show it the others).
| Parameter | Type | Description |
|---|---|---|
state | string | active (default: running, waiting, stopped) | all | waiting | running | stopped | finished | failed | killed |
session | string | only this session (the global session) |
job_status
One job, cheap: its state - finished (exit code, duration, tail), killed (by whom: user / global / pressure / archived), failed, waiting (position, ETA, what it waits for), running, stopped (partial: stopped by the user or the pressure of the computer, resumed later) - and the end of its output.
| Parameter | Type | Description |
|---|---|---|
id (required) | string | job id (j3) |
job_wait
Wait for a job to end (up to timeout seconds, 110 max) and get the same answer as job_status; when it is still waiting / running, wait again or end your turn (a job added by jobs_add wakes you up).
| Parameter | Type | Description |
|---|---|---|
id (required) | string | job id (j3) |
timeout | integer | seconds (default 100) |
job_kill
Kill a job: removed from the queue when it waits, its process group terminated when it runs. The owner is told who did it.
| Parameter | Type | Description |
|---|---|---|
id (required) | string | job id (j3) |
reason | string | why |
job_stop
Stop a running job (SIGSTOP of its process group: it keeps its memory, uses no CPU) until job_resume; its slot is free for the next one.
| Parameter | Type | Description |
|---|---|---|
id (required) | string | job id (j3) |
job_resume
Resume a stopped job (by you, or by the pressure of the computer).
| Parameter | Type | Description |
|---|---|---|
id (required) | string | job id (j3) |
job_prio
Change the priority of a job (-10..10, higher first): it passes the others in the queue.
| Parameter | Type | Description |
|---|---|---|
id (required) | string | job id (j3) |
prio (required) | integer | -10..10 |
hardware_scan
Scan this computer again (cores / threads, RAM, swap, disk, GPU, power, temperature), saved with the version of the scan; also tells the live load, memory, swap and pressure the limits of the orchestrator follow.
No parameter.
orchestrator_config
The settings of the orchestrator ([orchestrator]: profile low | normal | max, max_jobs, max_per_session, reserved CPU / RAM, threads per job, per class limits, thresholds, session priorities / quotas, what a sub-session may do) with the limits they give now. action get (default) | set (key, value) | enable | disable.
| Parameter | Type | Description |
|---|---|---|
action | string | get | set | enable | disable |
key | string | a key of [orchestrator] (get lists them) |
value | string | its new value |
heavy_run
Run a HEAVY command (a build, the tests, a container / media job, a local model) through the resource orchestrator of this computer: it waits in the queue for a free slot, then runs in the low profile (nice, ionice, the parallelism lowered to the share granted), and its result comes back HERE: finished (exit code, duration, tail of its output), failed, killed (by whom), or - when it waits or runs longer than the timeout - waiting (position, ETA, what it waits for) / running: then go on with something else and ask job_status (cheap) or job_wait, never poll in a loop. Use it instead of running heavy commands yourself, or cluster-run -- <cmd> in your own shell. Light commands (ls, grep, git status...) never go through it.
| Paramètre | Type | Description |
|---|---|---|
command (requis) | string | the shell command |
class | string | build | tests | container | gpu | custom (default: guessed from the command) |
prio | integer | -10..10, higher first (default 0) |
name | string | a short name shown in the queue |
cwd | string | folder it runs in (default: the one of claude-cluster) |
timeout_minutes | integer | killed when it runs longer |
ram_mb | integer | memory it needs, when not the usual of its class |
timeout | integer | seconds to wait here (default 100, 110 max): then the job is told waiting / running and goes on, follow it with job_status / job_wait |
jobs_add
Queue a heavy command WITHOUT waiting for it: you get its id and position at once, and are woken up with a message [job jN finished|failed|killed] (exit code, duration, tail of the output; killed: by whom) when it ends, so end your turn instead of polling. Same queue and low profile as heavy_run.
| Paramètre | Type | Description |
|---|---|---|
command (requis) | string | the shell command |
class | string | build | tests | container | gpu | custom (default: guessed from the command) |
prio | integer | -10..10, higher first (default 0) |
name | string | a short name shown in the queue |
cwd | string | folder it runs in (default: the one of claude-cluster) |
timeout_minutes | integer | killed when it runs longer |
ram_mb | integer | memory it needs, when not the usual of its class |
callback | boolean | you are woken up with a message [job jN ...] (exit code, duration, tail) when it ends or is killed (default true) |
session | string | the session the job belongs to and to wake up (global session only; default: you) |
jobs_list
The jobs of the orchestrator: running, waiting (position, what they wait for), stopped; state all adds the finished ones. A sub-session sees its own jobs (the user's settings may show it the others).
| Paramètre | Type | Description |
|---|---|---|
state | string | active (default: running, waiting, stopped) | all | waiting | running | stopped | finished | failed | killed |
session | string | only this session (the global session) |
job_status
One job, cheap: its state - finished (exit code, duration, tail), killed (by whom: user / global / pressure / archived), failed, waiting (position, ETA, what it waits for), running, stopped (partial: stopped by the user or the pressure of the computer, resumed later) - and the end of its output.
| Paramètre | Type | Description |
|---|---|---|
id (requis) | string | job id (j3) |
job_wait
Wait for a job to end (up to timeout seconds, 110 max) and get the same answer as job_status; when it is still waiting / running, wait again or end your turn (a job added by jobs_add wakes you up).
| Paramètre | Type | Description |
|---|---|---|
id (requis) | string | job id (j3) |
timeout | integer | seconds (default 100) |
job_kill
Kill a job: removed from the queue when it waits, its process group terminated when it runs. The owner is told who did it.
| Paramètre | Type | Description |
|---|---|---|
id (requis) | string | job id (j3) |
reason | string | why |
job_stop
Stop a running job (SIGSTOP of its process group: it keeps its memory, uses no CPU) until job_resume; its slot is free for the next one.
| Paramètre | Type | Description |
|---|---|---|
id (requis) | string | job id (j3) |
job_resume
Resume a stopped job (by you, or by the pressure of the computer).
| Paramètre | Type | Description |
|---|---|---|
id (requis) | string | job id (j3) |
job_prio
Change the priority of a job (-10..10, higher first): it passes the others in the queue.
| Paramètre | Type | Description |
|---|---|---|
id (requis) | string | job id (j3) |
prio (requis) | integer | -10..10 |
hardware_scan
Scan this computer again (cores / threads, RAM, swap, disk, GPU, power, temperature), saved with the version of the scan; also tells the live load, memory, swap and pressure the limits of the orchestrator follow.
Aucun paramètre.
orchestrator_config
The settings of the orchestrator ([orchestrator]: profile low | normal | max, max_jobs, max_per_session, reserved CPU / RAM, threads per job, per class limits, thresholds, session priorities / quotas, what a sub-session may do) with the limits they give now. action get (default) | set (key, value) | enable | disable.
| Paramètre | Type | Description |
|---|---|---|
action | string | get | set | enable | disable |
key | string | a key of [orchestrator] (get lists them) |
value | string | its new value |
5. InterfaceInterface
ui_state
What the interface of claude-cluster shows: the session shown, the layout, the style, Remote Control, vim; the choices.
No parameter.
ui_focus
Show a session in the interface (a sub-session, or g: you again), while you go on talking.
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
ui_layout
Layout of the interface: list (the list + one session), grid (every session at once), tabs (window / web page only: the terminal shows the list).
| Parameter | Type | Description |
|---|---|---|
layout (required) | string | list | grid | tabs |
ui_style
Colors of the interface (ui_state: the styles).
| Parameter | Type | Description |
|---|---|---|
style (required) | string | a style name |
ui_panel
Show / hide a panel of a session: skills, tokens, context, cost, git, diff, tools, files.
| Parameter | Type | Description |
|---|---|---|
session (required) | string | id (s1, g) or name of the session |
panel (required) | string | skills | tokens | context | cost | git | diff | tools | files |
ui_state
What the interface of claude-cluster shows: the session shown, the layout, the style, Remote Control, vim; the choices.
Aucun paramètre.
ui_focus
Show a session in the interface (a sub-session, or g: you again), while you go on talking.
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
ui_layout
Layout of the interface: list (the list + one session), grid (every session at once), tabs (window / web page only: the terminal shows the list).
| Paramètre | Type | Description |
|---|---|---|
layout (requis) | string | list | grid | tabs |
ui_style
Colors of the interface (ui_state: the styles).
| Paramètre | Type | Description |
|---|---|---|
style (requis) | string | a style name |
ui_panel
Show / hide a panel of a session: skills, tokens, context, cost, git, diff, tools, files.
| Paramètre | Type | Description |
|---|---|---|
session (requis) | string | id (s1, g) or name of the session |
panel (requis) | string | skills | tokens | context | cost | git | diff | tools | files |
6. Settings, policy and the computerRéglages, politique et ordinateur
settings_get
The settings of claude-cluster (the settings page): section, key, value, choices, help. section: one section only.
| Parameter | Type | Description |
|---|---|---|
section | string | ui | agent | commands | global | sessions | voice | service (optional) |
settings_set
Change one setting of claude-cluster (written in its config.toml, applied live except the ones marked at_next_start).
| Parameter | Type | Description |
|---|---|---|
section (required) | string | section of the option |
key (required) | string | its key (settings_get) |
value (required) | string | the new value (true / false, a number, a choice, a text) |
confirmed | string | "true" only when the user explicitly asked for this value: a dangerous one is refused without it - ask the user first. The protected ones (a shell or the web open wider, the permissions of the agents, the programs run, the MCP servers and tools) are refused anyway: the user changes them in the settings page |
config_files
The editable files of claude-cluster: your own system prompt, the one of the sub-sessions, the vocabulary and the words of the voice, config.toml, the map of this computer (read only); their path, what they hold, when a change is taken.
No parameter.
config_read
The content of one of them (config_files).
| Parameter | Type | Description |
|---|---|---|
name (required) | string | global_prompt | sessions_prompt | vocabulary | voice_words | config | machine_map |
config_write
Replace one of them with this content: read it first (config_read) and keep what the user did not ask to change. config is checked (TOML) before it is written, its protected settings stay the user's; the system prompts only when the user allowed it (settings: Global session can rewrite its own system prompt / the system prompt of the sub-sessions, one each), else give them the text; your own system prompt: you are started again on it after this turn.
| Parameter | Type | Description |
|---|---|---|
name (required) | string | global_prompt | sessions_prompt | vocabulary | voice_words | config |
content (required) | string | the whole new content |
cluster_info
Everything about this claude-cluster in one call, instead of searching its files: version, binary, the paths of its files (config, logs, history, usage, prompts, vocabulary, voice words, map of this computer), the global session, the agents and their commands, the voice (speech model, models installed, what is missing), the service, the interface, counts.
No parameter.
models_policy
The model / thinking policy of the user: the default model and effort, whether they are advised or forced, the allowed ones, the costly ones (the user is asked first), and the model of the global session. Read it before choosing the model of a sub-session.
No parameter.
work_method
The work method of the user (how they like the work organised: a task list then a review repeated until good, one task at a time, plan first, free): read it (default) to split the requests accordingly. Only the user changes the setting. Detection (when the user turned it on; a spawn result tells work_method_due): action sample = counts and a few of their prompts read from the transcripts (no model; cheap, once), then action propose (preset, text, reason in one sentence) ONLY when their habits clearly differ from the current method - the user answers Allow / Deny in a popup, the answer comes back to you as a message; never apply or repeat a refused one.
| Parameter | Type | Description |
|---|---|---|
action | string | read (default) | sample | propose |
preset | string | propose: free | list-review | one-task | plan-first | custom |
text | string | propose: the user's words added to the preset (short; alone with custom) |
reason | string | propose: why, one sentence shown to the user |
max | integer | sample: prompts shown (10, 20 at most) |
usage
Tokens and cost used per vendor (anthropic, ollama, openai...) over every session: today, the last 7 days, lifetime; the 5 h / 7 d limits left when the vendor tells them.
| Parameter | Type | Description |
|---|---|---|
vendor | string | one vendor (empty: all) |
providers
Providers / backends and whether they are ready (logged in, key stored, server up).
No parameter.
voice_engines
The engines of the voice: speech to text ([voice] listen_model) and text to speech ([voice] say_engine), local or free-tier APIs: what each one handles (languages), its strengths and limits against the others, its free use, its voices, its links, ready (installed / API key stored), used. To change one: settings_set; a key: the user runs claude-cluster auth login <provider>.
No parameter.
web_access
The web access of claude-cluster on this LAN (a browser of the same network drives it after a 6-digit code, one at a time): its address, code and the browser connected; action on / off (this run), kick (the browser out, a new code), pin (a new code). Give the user the address and the code when they ask to open it.
| Parameter | Type | Description |
|---|---|---|
action | string | empty: the state only |
remote_control
Remote Control of the global session (you): on, the user can go on with you from claude.ai / the Claude app (live both ways); off.
| Parameter | Type | Description |
|---|---|---|
on (required) | boolean | true: on, false: off |
machine_sync
Ask the user to map this computer again (when asked to, or the map is clearly outdated): its question is shown in the interface (yes / no), the scan then runs as started by hand.
No parameter.
docs
The documentation of claude-cluster itself (its sessions, tools, settings, keys, interfaces, security), embedded in the program: action search (default) finds the pages, settings, tools and keys that answer a question (typos are tolerated); page gives the page of a screen of the app or a page name; open shows it to the user in their browser. Use it to answer a question about how claude-cluster works instead of guessing.
| Parameter | Type | Description |
|---|---|---|
action | string | search (default) | page | open |
query | string | what to look for (search) |
page | string | a page (settings, orchestrator, taxonomy...) or a screen of the app (settings, question, graph...) (page, open) |
lang | string | en (default) | fr |
settings_get
The settings of claude-cluster (the settings page): section, key, value, choices, help. section: one section only.
| Paramètre | Type | Description |
|---|---|---|
section | string | ui | agent | commands | global | sessions | voice | service (optional) |
settings_set
Change one setting of claude-cluster (written in its config.toml, applied live except the ones marked at_next_start).
| Paramètre | Type | Description |
|---|---|---|
section (requis) | string | section of the option |
key (requis) | string | its key (settings_get) |
value (requis) | string | the new value (true / false, a number, a choice, a text) |
confirmed | string | "true" only when the user explicitly asked for this value: a dangerous one is refused without it - ask the user first. The protected ones (a shell or the web open wider, the permissions of the agents, the programs run, the MCP servers and tools) are refused anyway: the user changes them in the settings page |
config_files
The editable files of claude-cluster: your own system prompt, the one of the sub-sessions, the vocabulary and the words of the voice, config.toml, the map of this computer (read only); their path, what they hold, when a change is taken.
Aucun paramètre.
config_read
The content of one of them (config_files).
| Paramètre | Type | Description |
|---|---|---|
name (requis) | string | global_prompt | sessions_prompt | vocabulary | voice_words | config | machine_map |
config_write
Replace one of them with this content: read it first (config_read) and keep what the user did not ask to change. config is checked (TOML) before it is written, its protected settings stay the user's; the system prompts only when the user allowed it (settings: Global session can rewrite its own system prompt / the system prompt of the sub-sessions, one each), else give them the text; your own system prompt: you are started again on it after this turn.
| Paramètre | Type | Description |
|---|---|---|
name (requis) | string | global_prompt | sessions_prompt | vocabulary | voice_words | config |
content (requis) | string | the whole new content |
cluster_info
Everything about this claude-cluster in one call, instead of searching its files: version, binary, the paths of its files (config, logs, history, usage, prompts, vocabulary, voice words, map of this computer), the global session, the agents and their commands, the voice (speech model, models installed, what is missing), the service, the interface, counts.
Aucun paramètre.
models_policy
The model / thinking policy of the user: the default model and effort, whether they are advised or forced, the allowed ones, the costly ones (the user is asked first), and the model of the global session. Read it before choosing the model of a sub-session.
Aucun paramètre.
work_method
The work method of the user (how they like the work organised: a task list then a review repeated until good, one task at a time, plan first, free): read it (default) to split the requests accordingly. Only the user changes the setting. Detection (when the user turned it on; a spawn result tells work_method_due): action sample = counts and a few of their prompts read from the transcripts (no model; cheap, once), then action propose (preset, text, reason in one sentence) ONLY when their habits clearly differ from the current method - the user answers Allow / Deny in a popup, the answer comes back to you as a message; never apply or repeat a refused one.
| Paramètre | Type | Description |
|---|---|---|
action | string | read (default) | sample | propose |
preset | string | propose: free | list-review | one-task | plan-first | custom |
text | string | propose: the user's words added to the preset (short; alone with custom) |
reason | string | propose: why, one sentence shown to the user |
max | integer | sample: prompts shown (10, 20 at most) |
usage
Tokens and cost used per vendor (anthropic, ollama, openai...) over every session: today, the last 7 days, lifetime; the 5 h / 7 d limits left when the vendor tells them.
| Paramètre | Type | Description |
|---|---|---|
vendor | string | one vendor (empty: all) |
providers
Providers / backends and whether they are ready (logged in, key stored, server up).
Aucun paramètre.
voice_engines
The engines of the voice: speech to text ([voice] listen_model) and text to speech ([voice] say_engine), local or free-tier APIs: what each one handles (languages), its strengths and limits against the others, its free use, its voices, its links, ready (installed / API key stored), used. To change one: settings_set; a key: the user runs claude-cluster auth login <provider>.
Aucun paramètre.
web_access
The web access of claude-cluster on this LAN (a browser of the same network drives it after a 6-digit code, one at a time): its address, code and the browser connected; action on / off (this run), kick (the browser out, a new code), pin (a new code). Give the user the address and the code when they ask to open it.
| Paramètre | Type | Description |
|---|---|---|
action | string | empty: the state only |
remote_control
Remote Control of the global session (you): on, the user can go on with you from claude.ai / the Claude app (live both ways); off.
| Paramètre | Type | Description |
|---|---|---|
on (requis) | boolean | true: on, false: off |
machine_sync
Ask the user to map this computer again (when asked to, or the map is clearly outdated): its question is shown in the interface (yes / no), the scan then runs as started by hand.
Aucun paramètre.
docs
The documentation of claude-cluster itself (its sessions, tools, settings, keys, interfaces, security), embedded in the program: action search (default) finds the pages, settings, tools and keys that answer a question (typos are tolerated); page gives the page of a screen of the app or a page name; open shows it to the user in their browser. Use it to answer a question about how claude-cluster works instead of guessing.
| Paramètre | Type | Description |
|---|---|---|
action | string | search (default) | page | open |
query | string | what to look for (search) |
page | string | a page (settings, orchestrator, taxonomy...) or a screen of the app (settings, question, graph...) (page, open) |
lang | string | en (default) | fr |
7. Other toolsAutres outils
report_status
A sub-session tells whoever follows it (the global session, the session whose task it runs) something now, without ending its turn: "[status from <name> (<id>)] text". Your final message reaches them by itself: this is only for what cannot wait for it. One every 30 s, each one costs them a turn.
report_status
A sub-session tells whoever follows it (the global session, the session whose task it runs) something now, without ending its turn: "[status from <name> (<id>)] text". Your final message reaches them by itself: this is only for what cannot wait for it. One every 30 s, each one costs them a turn.