Quickstart

Keyoku installs with a global npm install, then one init command. It registers itself as an MCP server in Claude Code (and Codex, if present) and installs three hooks that trace your tool calls and brief your agent — everything stays on your machine, and no API keys are required.

1. Install

npm install -g keyoku 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 three hooks	Adds to ~/.claude/settings.json: PostToolUse (matcher "Bash\|Edit\|Write\|Read\|mcp__.*", command keyoku record), SessionStart (keyoku brief), and UserPromptSubmit (keyoku context).
Wire Codex	If ~/.codex exists (or you pass --codex), adds [mcp_servers.keyoku] to ~/.codex/config.toml — same tools, same workflows.

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

2. Skip the cold start — import your history

keyoku import

This backfills activity from your existing Claude Code session transcripts (~/.claude/projects) and Codex rollouts (~/.codex/sessions) — months of real tool calls become minable in seconds, so your first suggestions arrive minutes after install instead of days. It also ingests each project's CLAUDE.md sections as conventions knowledge. It is idempotent: re-running imports nothing twice.

Codex users: keyoku init wires the MCP server into ~/.codex/config.toml automatically, and keyoku import reads ~/.codex/sessions too — same tools, same workflows. Bake a workflow for Codex with keyoku export <slug> --agents-md.

3. Verify

keyoku doctor

doctor checks the hooks, both MCP registrations (Claude Code and Codex), pause state, activity freshness, SLM tier, and engine reachability. Then work normally. Every Bash, Edit, Write, Read, and MCP tool call is appended as an ActivityEvent to ~/.keyoku/activity.jsonl (size-capped at roughly 10k events), with secrets redacted at record time. Need to go off the record? keyoku pause / keyoku resume toggles all recording and context injection.

4. Get your first workflow

You usually don't have to ask. The server recomputes pattern ripeness in the background, and the hooks deliver it: a one-time nudge when a sequence newly crosses threshold ("repeated 4× — offer to save it"), a brief at session start, and matching workflows injected at prompt time. You can also pull: workflow_suggest mines the trace for sequences of 2–6 steps that occurred at least 3 times, and workflow_capture saves what you just did — no repetition needed. Approve with workflow_approve (the workflow becomes a native slash command), then run it any time with workflow_execute.

# In Claude Code, just ask:
"Save what I just did as a workflow"            # → workflow_capture
"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 — or KEYOKU_SLM_BASE_URL points at any OpenAI-compatible endpoint (Ollama, LM Studio, LiteLLM, Groq) — a small model filters noise from suggestions, names drafts, and parameterizes run-specific values with {{placeholders}}, grounded with the knowledge layer. 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 \| openai-compat \| none
`KEYOKU_SLM_MODEL`	Override the refinement model
`KEYOKU_SLM_BASE_URL`	Any OpenAI-compatible endpoint — Ollama, LM Studio, LiteLLM, Groq. A local endpoint wins auto-detection
`KEYOKU_SLM_API_KEY`	Key for the compatible endpoint, if it needs one
`KEYOKU_ENGINE_URL`	Connect a running keyoku-engine — knowledge mirrors in and queries upgrade to semantic search
`KEYOKU_NUDGE_EVERY`	Proactive nudge cadence — set to 0 to disable nudges

Other agents

Claude Code and Codex are wired automatically by keyoku init. Cursor and any other MCP client work too — register Keyoku as an MCP server 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