Quickstart

Keyoku installs with one command. It registers itself as an MCP server in Claude Code and adds a hook that traces your tool calls — everything stays on your machine, and no API keys are required.

1. Install

npx keyoku init

What init does:

Step	Detail
Register the MCP server	Runs claude mcp add --scope user keyoku. If the claude CLI isn't available, falls back to editing ~/.claude.json directly.
Install the activity hook	Adds a PostToolUse hook to ~/.claude/settings.json with matcher "Bash\|Edit\|Write\|Read" and command keyoku record.

Restart Claude Code after running init so the MCP server and hook are picked up.

2. Verify

keyoku status

Then work normally. Every Bash, Edit, Write, and Read tool call is appended as an ActivityEvent to ~/.keyoku/activity.jsonl (size-capped at roughly 10k events).

3. Get your first workflow

Once you've repeated a sequence a few times, ask your agent to call workflow_suggest. It mines the trace for sequences of 2–6 steps that occurred at least 3 times and contain at least one action step. Approve a suggestion with workflow_approve, then run it any time with workflow_execute.

# In Claude Code, just ask:
"Suggest workflows from my recent activity"     # → workflow_suggest
"Approve the release workflow"                  # → workflow_approve
"Run the release workflow"                      # → workflow_execute

Optional: model refinement

If GEMINI_API_KEY or ANTHROPIC_API_KEY is set, a small model filters noise from suggestions, names drafts, and parameterizes run-specific values with {{placeholders}}. With no key, the response guidance instructs your connected coding agent to do that refinement before you approve — zero keys are required to use Keyoku.

Environment variables

Variable	Purpose
`KEYOKU_HOME`	State directory. Default: ~/.keyoku
`KEYOKU_DEBUG`	Enable debug logging
`GEMINI_API_KEY`	Optional — enables SLM refinement via Gemini
`ANTHROPIC_API_KEY`	Optional — enables SLM refinement via Anthropic
`KEYOKU_SLM_PROVIDER`	gemini \| anthropic \| none
`KEYOKU_SLM_MODEL`	Override the refinement model

Other agents

Keyoku is built for Claude Code first, but works with Cursor and Codex too — register it as an MCP server in those tools the same way you would any other server.

Next steps

How it works — the full Observe → Learn → Run pipeline
Workflows — templates, step types, and executions
Connectors — wire in external MCP servers and APIs