komrad

list_workflows

List workflows by name.

read-onlyidempotentMCP toolWorkflow

Archived workflows are left out unless archived is set.

Calling it#

curl -X POST http://127.0.0.1:8787/komrad.workflow.v1.WorkflowService/ListWorkflows \
  -H 'Content-Type: application/json' \
  -d '{}'

Request#

ListWorkflowsRequest#

FieldTypeDescription
paginationPagination

The page to read.

archivedbool

Whether to list only archived workflows instead of live ones.

Response#

ListWorkflowsResponse#

FieldTypeDescription
workflowsWorkflow[]

One page of workflows, by name.

next_page_tokenstring

The cursor for the next page. Unset on the last page.

Types#

Pagination#

Pagination selects one page of a listing.

FieldTypeDescription
limitint32

at least 0

How many records to return. Komrad caps the value, and picks one when unset.

cursorstring

at most 2048 characters

The next_page_token from the previous response. Unset to start from the first page.

Workflow#

Workflow is a group of tasks that share a directory, a context and the settings for each role.

FieldTypeDescription
iduuid*

The workflow's id.

namestring

The workflow's name.

contextstring

The workflow's context, added to the system prompt of every agent the workflow launches. Each agent keeps the context it was launched with.

cwdstring

The directory the workflow's agents start in, and the repository worktrees are created from.

archived_attimestamp

When the workflow was archived. Unset while the workflow is live.

worktreeWorktreeConfig

Whether the workflow's tasks get worktrees, and how komrad creates them.

hooksWorkflowHook[]

The workflow's hooks, at most one for each moment.

event_promptsWorkflowEventPrompt[]

The prompts komrad adds to the mail it sends the workflow's agents about events, one for each event.

writerRoleSettings

What the workflow launches its writers with.

reviewerReviewerSettings

What the workflow launches its reviewers with and holds them to.

orchestratorOrchestratorSettings

What the workflow launches its orchestrator with and holds it to.

WorktreeConfig#

WorktreeConfig is whether a workflow's tasks get worktrees, and how komrad creates them.

FieldTypeDescription
enabledbool

Whether each task gets a worktree. False runs agents in the workflow's directory.

base_branchstring

at most 255 characters

must not contain shell metacharacters

The workflow's base branch. Empty on create reads the branch from the repository.

copy_pathsstring[]

at most 50 items

each at most 255 characters

each must be a relative path without a leading / or ~ or a .. segment

The untracked files to copy into each new worktree, such as ones a build needs.

diff_excludestring[]

at most 50 items

each not empty

each at most 255 characters

each must be a relative path without a leading / or ~ or a .. segment

The paths or globs left out of a task's diff and line counts, such as generated output.

dirstring

at most 4096 characters

must be blank, absolute, or start with ~

The directory new worktrees are created in. Empty uses the directory all workflows share.

setup_commandstring

at most 1000 characters

must not contain control characters

The shell command run in each worktree before its writer starts and before every resume of the writer, such as one that installs the repository's tools. Keep it quick when nothing is missing. Empty runs nothing.

shrink_pathsstring[]

at most 50 items

each at most 255 characters

each must be a gitignore pattern that does not start with ! or # and has no control characters

The gitignore patterns, relative to the worktree, such as /bin/ or *.test, naming ignored files komrad may delete from the worktree of an archived task.

WorkflowHook#

WorkflowHook is a hook that runs at one moment in the life of a workflow's task or agent.

FieldTypeDescription
eventMoment*

one of

agent.pre-launch

agent.post-launch

agent.pre-resume

agent.post-resume

agent.pre-archive

agent.post-archive

agent.pre-restore

agent.post-restore

agent.pre-delete

agent.post-delete

task.pre-open

task.post-archive

task.pre-delete

The moment the hook runs at.

scriptstring*

at most 255 characters

must be blank or a file name without a slash, a leading dot or control characters

The hook's script, by file name in the hooks directory.

WorkflowEventPrompt#

WorkflowEventPrompt is what a workflow's agents are told to do when komrad mails them an event.

FieldTypeDescription
eventEvent*

The event.

promptstring

at most 500 characters

The text added to the mail about the event. Empty adds nothing.

mutedbool

Whether the event is muted. A muted event doesn't send mail of its own, and updates the agent's unread mail without its prompt.

RoleSettings#

RoleSettings is what a workflow launches every agent in one role with. An empty or unset setting uses the one komrad's config sets for the role.

FieldTypeDescription
harnessstring

at most 40 characters

matching ^[a-z0-9-]*$

The harness the role's agents run. Empty uses the config's harness for the role, then komrad's default.

flagsstring

at most 500 characters

must not contain shell metacharacters

The flags the role's agents start with. Empty uses the config's flags for the role when harness is empty too.

contextstring

at most 50000 characters

The text added to the system prompt of the role's agents only, after the workflow's context. Each agent keeps the context it was launched with.

auto_compactionint32

at least 0

The conversation size in tokens the role's agents are held under. 0 leaves the CLI's own default, and unset uses the config's value for the role.

ReviewerSettings#

ReviewerSettings is what a workflow launches its reviewers with and holds them to.

FieldTypeDescription
roleRoleSettings

The settings every role has.

max_per_taskint32

at least 1

How many live reviewers one of the workflow's tasks may hold at once. Unset uses the config's value.

archive_on_approvalbool

Whether komrad archives a reviewer once it releases an approval. Unset uses the config's value.

OrchestratorSettings#

OrchestratorSettings is what a workflow launches its orchestrator with and holds it to.

FieldTypeDescription
roleRoleSettings

The settings every role has.

max_tasksint32

at least 0

How many live tasks the orchestrator may have started at once. 0 sets no cap of its own, and unset uses the config's value.

Moment#

Moment is a point in the life of an agent or task at which komrad runs a script.

ValueDescription
agent.provision

runs the provisioner before komrad creates an agent's directory

agent.resume

reruns the provisioner before komrad resumes an agent

agent.deprovision

runs the deprovisioner as komrad releases an agent's directory

agent.pre-launch

runs in the agent's directory before its pane opens, and a failure abandons the create

agent.post-launch

runs once the agent's pane opens

agent.pre-resume

runs in the agent's directory before a dormant agent's pane opens, and a failure refuses the resume

agent.post-resume

runs once a dormant agent is back in a pane

agent.pre-archive

runs while the agent is still running, and a failure refuses the archive

agent.post-archive

runs in the agent's directory after komrad closes its pane and archives it

agent.pre-restore

runs before an archived agent's row comes back, and a failure refuses the restore

agent.post-restore

runs when an archived agent's row comes back

agent.pre-delete

runs in the agent's directory as komrad deletes it, before komrad releases the worktree

agent.post-delete

runs once the agent and its worktree are gone

task.pre-open

runs before a task's first live agent opens its pane, and a failure abandons the create or restore

task.post-archive

runs after komrad archives a task's last live agent, and the task with it

task.pre-delete

runs as komrad deletes a task, before it releases the worktree, and a failure keeps the task

Event#

Event is something komrad tells an agent about through mail.

ValueDescription
pull_request.checks_failing_running

some checks on the head failed while others still run

pull_request.checks_failing

checks on the head failed and the run has finished

pull_request.checks_passing

checks on the head passed and the forge would merge it

pull_request.changes_requested

the forge review decision asks for changes

pull_request.approved

the forge review decision is approved

pull_request.conflicting

the branch conflicts with its base

pull_request.behind

the branch is behind its base

pull_request.merged

the pull request was merged

pull_request.closed

the pull request was closed unmerged

pull_request.auto_merge_on

the forge will merge it once its checks and reviews pass

worktree.rebased

the worktree was rebased and its commits replayed

worktree.landed

the work was already in the base, so the branch moved onto it

worktree.rebase_conflicted

a rebase stopped on conflicts

document.written_by_person

a person wrote or edited the agent's document

review.approved

a reviewer approved the agent's work

review.changes_requested

a reviewer asked for changes

review.commented

a reviewer released comments without a verdict either way

review.commented_by_person

a person commented on the agent's work

review.forge_commented

a comment from the pull request on the forge was released

review.answered

the agent under review answered in a thread, read by its reviewer

pull_request.head_stale

the forge hasn't moved the pull request onto the branch's newest commit

task.quiet

every agent on a task went quiet with the task neither parked nor waiting on komrad

worktree.shrunk

komrad deleted build output from the worktree while its task was archived