Workflows
A workflow is a saved template of steps that Keyoku learned from your activity (or that you approved by hand). Suggest, approve, execute — with pause points wherever judgment is required.
From suggestion to template
workflow_suggest mines ~/.keyoku/activity.jsonl for sequences of 2–6 steps that occurred at least 3 times (configurable via min_count) and contain at least one action step — a file change, git mutation, non-inspection command, or connector call. Run-specific values like commit messages, quoted strings, hex hashes, and absolute paths are normalized away first, and sub-sequences collapse into the longest repeated chain.
workflow_approve saves the result as a template with a slug, name, description, and steps. If an SLM key is configured, the model parameterizes run-specific values with {{placeholders}} before you approve; with no key, your coding agent is instructed to do the same refinement.
Step types
| Type | Fields | Behavior |
|---|---|---|
bash | command, cwd? | Runs a shell command. cwd defaults to the server's working directory. 30-second timeout (SIGTERM, then SIGKILL). Output is captured and truncated to 2000 characters. |
mcp_call | connector, tool, args | Calls a tool on a registered connector. Gated by the connector's autonomy level — at the approve level, the step pauses the execution and queues an approval request. |
agent_prompt | — | Pauses and returns a prompt to the coding agent. The agent does the work, then resumes via execution_complete with { id, step_index, result }. |
human_review | — | Pauses the execution for explicit human sign-off before anything else runs. |
Example template
{
"slug": "patch-release",
"name": "Patch release",
"description": "Test, bump, and gate a patch release on sign-off.",
"steps": [
{ "type": "bash", "command": "npm test" },
{ "type": "bash", "command": "npm version {{bump}}" },
{ "type": "human_review" }
]
}Executions
workflow_execute runs a template. Executions persist step-by-step to ~/.keyoku/executions.json, so a paused execution survives across sessions. When a step pauses — agent_prompt, human_review, or an approval-gated mcp_call — resume it with execution_complete, which enforces in-order step completion. execution_list shows history, and each template's timesRun increments per completed run.
Tool reference
| Tool | Purpose |
|---|---|
workflow_suggest | Mine the activity trace for repeated patterns and propose workflow drafts |
workflow_approve | Save a draft as a template (slug, name, description, steps) |
workflow_execute | Run a template step by step |
execution_complete | Resume a paused step with its result — in-order completion is enforced |
execution_list | Show execution history |
workflow_template_list | List saved templates |
workflow_template_delete | Delete a template |
A note on trust
Approval is the trust boundary: approved templates execute shell commands with your user privileges. Review templates the way you would review a shell script. See Security for the full model.
Related
- How it works — the mining rules in detail
- Connectors — what mcp_call steps can reach
- MCP Tools — the full 31-tool surface