KeyokuKeyoku is the harness with muscle memory — it watches how you work in Claude Code or Codex, learns the patterns you repeat, and proactively offers them back as one-command workflows — Observe, Learn, Run.
TypeScript MCP server + CLI. Local-first. No cloud, no telemetry.
Tool calls → activity trace → mined patterns → approved templates → one-command runs.
A PostToolUse hook appends an ActivityEvent for every tool call — Bash, Edit, Write, Read, and every MCP tool call — to ~/.keyoku/activity.jsonl.
The hook matches Bash|Edit|Write|Read|mcp__.* and runs `keyoku record`. Secrets are redacted at record time, before anything is stored. The log is size-capped at roughly 10k events. Everything stays on your machine — and `keyoku pause` / `resume` silences recording and all context injection.
keyoku recordHeuristic pattern mining finds sequences of 2–6 steps that repeat at least 3 times — your real workflows.
Mining runs over the most recent 5000 events. Sequences are mined within each session but counted across sessions, with non-overlapping occurrence counting. A sequence must contain at least one ACTION step, so pure looking-around chains never qualify, and sub-sequences collapse into the longest repeated chain. Don't want to wait for three repetitions? workflow_capture turns the last N actions of your session into a reviewable draft — you vouch once.
workflow_suggestApprove a suggestion to save it as a template, then run it as a one-command workflow from any session.
workflow_approve saves a template with a slug, name, description, and steps — and publishes it as an MCP prompt, a native slash command in Claude Code. workflow_execute runs it step by step with params filling {{placeholders}}, persisting execution state to ~/.keyoku/executions.json so paused steps can resume in order.
workflow_executeThe PostToolUse hook (matcher Bash|Edit|Write|Read|mcp__.*) appends events to ~/.keyoku/activity.jsonl, size-capped at ~10k events, with secrets redacted before they are written.
tool_use, shell, file_change, git, or manual
One-line description of what happened
Optional longer detail for the event
The tool that produced the event
Auto-extracted entities (files, repos, services)
The coding-agent session the event belongs to
Working directory — scopes patterns and practice to a project
When the event was recorded
Pattern detection
workflow_suggest runs heuristic mining over the most recent 5000 events of the activity trace. Six rules keep suggestions honest.
Sequences shorter than 2 or longer than 6 steps are never suggested.
Occurrences are counted without overlap — mined within each session, counted across sessions.
A sequence must repeat at least 3 times (configurable via min_count).
A file change, git mutation, non-inspection command, or connector call. Pure looking-around chains never qualify.
Sub-sequences collapse into the longest repeated chain — no duplicate fragments.
Detections with two or more executable steps (or a majority) are classified automation and offered as runnable workflows. The rest — like files that change together — are classified practice and filed silently as project knowledge, never a run button.
The MCP server recomputes pattern ripeness every 60 seconds in the background, and the hooks deliver it. Each pattern surfaces exactly once — set KEYOKU_NUDGE_EVERY=0 to disable nudges.
A one-time nudge when a pattern newly crosses threshold.
The agent sees "repeated 4× — offer to save it" and offers the workflow in conversation — you decide.
Every session opens with a status brief for the agent.
Something like "3 workflows available; 2 unsaved patterns" — so the agent knows what muscle memory exists before you type a word.
Saved workflows that match your request are injected at prompt time.
"A saved workflow matches this request — prefer workflow_execute", plus house practice patterns for the project you are in (by cwd).
So the same workflow matches even when the details differ between runs.
Redacted at record time, before normalization: credential-shaped assignments (TOKEN=, api_key:, password:) and Bearer tokens become «redacted».
Stripped before comparison, so `git commit -m "..."` matches across runs.
Run-specific quoted values are normalized away.
Commit SHAs and other hex identifiers don't break a match.
Stripped, so the same workflow matches across directories.
File edits are keyed by file extension, not exact filename.
An optional small model polishes suggestions before you approve them. Without a key, your coding agent does the same job.
A small model filters noise, names drafts, and parameterizes run-specific values as {{placeholders}} — grounded with the knowledge layer.
Set GEMINI_API_KEY or ANTHROPIC_API_KEY, or point KEYOKU_SLM_BASE_URL at any OpenAI-compatible endpoint — Ollama, LM Studio, a LiteLLM proxy, Groq — with KEYOKU_SLM_MODEL (and KEYOKU_SLM_API_KEY if needed). A local endpoint wins auto-detection. Pick explicitly with KEYOKU_SLM_PROVIDER=gemini|anthropic|openai-compat|none.
The response guidance instructs your connected coding agent to do the refinement before approving.
Zero API keys are required to use Keyoku. The heuristic miner plus your coding agent cover the full pipeline.
Approved templates are made of steps. Each runs, pauses, or gates differently.
Runs a shell command with an optional cwd (defaults to the server's cwd).
30-second timeout with SIGTERM then SIGKILL. Output is captured and truncated to 2000 characters.
Calls a tool on a registered connector with the given args.
Gated by the connector's autonomy level. At the approve level, the step pauses the execution and queues an approval request.
Pauses and returns a prompt to the coding agent.
The agent does the work, then resumes the execution via execution_complete with { id, step_index, result }.
Pauses the execution for explicit human sign-off.
Nothing runs past this step until a person approves it.
Define what done looks like with machine-checkable criteria, and let the harness keep checking.
Define a goal with machine-checkable criteria.
Probes are command, http, or mcp calls with assertions — pass/fail, not vibes.
Re-check every criterion and report which pass.
Run it from the agent, or from the CLI with `keyoku assess <goal>`.
A CLI watch loop that re-assesses goals on an interval.
Watch one goal or --all, with a configurable --interval.
Mines patterns from traces to converge on the goal.
The same pattern miner, pointed at goal convergence instead of suggestion.
Quick example
# Install: registers the MCP server + three hooks (Codex too)
keyoku init
# ...work normally — Keyoku nudges when a pattern ripens...
# Or pull, in your agent:
workflow_suggest # mine repeated patterns
workflow_approve # save one as a template
workflow_execute # run it, any session, one commandNo cloud, no telemetry. All state lives in ~/.keyoku (dir 0700, files 0600).
Claude Code and Codex are wired by keyoku init; Cursor and any MCP client via standard registration.
Pattern mining is deterministic. A model only refines — and only if you configure one.
Nothing executes until you approve a template. Review templates like shell scripts.
Every action lands in an append-only audit trail — audit_list or `keyoku audit`.
Executions persist step-by-step, and execution_complete enforces in-order completion.
One command sets up the MCP server and all three hooks.
keyoku init