Get Started
Install it once, then wire it up:
npm install -g keyoku
keyoku init
A global install keeps keyoku on a durable path. Running npx keyoku init
from the throwaway npx cache is refused — npm can evict that directory and
break the hooks — so install globally first.
The init command wires everything automatically:
- Registers the MCP server — via
claude mcp add --scope user, so Claude Code connects on next launch
- Installs the hooks — activity recording (every Bash/Edit/Write/Read/MCP call), a session-start brief, and prompt-time practice injection
- Wires Codex too — when
~/.codex exists, the MCP server lands in config.toml automatically (same tools, same workflows)
- Stays local — no cloud, no telemetry; state lives in
~/.keyoku with the same file permissions as ~/.aws. keyoku pause stops everything instantly.
Restart Claude Code and keyoku is live. Then skip the cold start entirely:
keyoku import # backfill months of history from your Claude Code transcripts
Now ask your agent to run workflow_suggest — keyoku mines your real history immediately instead of waiting days for new activity. Approved workflows appear as native slash commands (MCP prompts), and keyoku export <slug> bakes one into your repo as a Claude Code skill your whole team inherits.
How It Works
Without Keyoku: you describe the same multi-step process to your agent every session.
With Keyoku: you approve a workflow once, then run it with one command. The agent never has to rediscover it.
1. Activity tracing — automatic
Every tool call your agent makes is recorded as a lightweight ActivityEvent — tool name, summary, extracted entities. Purely local.
2. Pattern detection — heuristics for recall, a model for precision
workflow_suggest mines recurring sequences from your recent activity (non-overlapping counting, noise suppression, longest-chain collapsing — no model required). If an SLM key is configured (GEMINI_API_KEY or ANTHROPIC_API_KEY), the model then refines the drafts: filters coincidences, names workflows properly, and parameterizes run-specific values with {{placeholders}}.
2b. Muscle memory — converged goals become reusable workflows
A goal that converges (goal_assess reports all criteria met) promotes its action trace into a learned workflow. Next time you start a similar goal, keyoku surfaces what worked before — so the agent never rediscovers it.
- Capture happens three ways: explicit
goal_record, live goal_focus (real actions stream into the goal's trace as you work), or activity backfill (if you just did the work without recording, keyoku lifts the steps from the activity log). Already have hollow workflows from older runs? keyoku backfill repopulates them.
- Reuse needs no API key. keyoku is driven by a frontier coding agent, so the agent is the judge of relevance.
goal_assess returns candidateWorkflows and the agent picks the ones that genuinely apply — which matches verbose, differently-worded goals that token-overlap never could. A lite model is an optional accelerator for headless runs (keyoku watch/cron), not a requirement.
- It self-prunes. Suggestions rank by
similarity × precision, where precision is learned from whether a workflow's steps actually recur — so word-matching-but-never-useful workflows sink.
- Negative memory too. Approaches that failed on the way to convergence are captured as pitfalls and surfaced as "avoid (failed before): …" on similar goals.
- Refine raw into clean.
keyoku refine <slug> turns noisy captured steps into a tight, {{parameterized}} template ready to run.
3. Approval — you are the trust boundary
workflow_approve { slug: "deploy-staging", name: "Deploy staging", steps: [...] }
Review the draft like you'd review a shell script, then approve. Templates live in ~/.keyoku/templates.json.
4. Execution — bash runs, judgment pauses
workflow_execute { slug: "deploy-staging" }
- bash steps run directly (per-step
cwd, timeouts, output captured)
- agent_prompt steps pause and hand the step to your coding agent, which resumes with
execution_complete
- human_review steps wait for your explicit sign-off
Every execution persists step-by-step — crash-safe, fully inspectable via execution_list.
MCP Tools
| Tool | What it does |
|---|
activity_record / activity_list | Log and browse the observation stream |
workflow_suggest | Mine patterns → model-refined draft workflows |
workflow_capture | "Save what I just did" — last N session actions become a draft |
workflow_approve / workflow_update | Save or edit templates (slash commands stay current) |
workflow_template_list / workflow_template_delete | Manage the catalog |
workflow_execute | Run a template (params fill {{placeholders}}) |
execution_complete / execution_cancel / execution_list | Resume, stop, browse runs |
knowledge_submit / knowledge_query | The context layer — research, conventions, practice |
goal_create / goal_assess / … | Goals with machine-checkable success criteria |
goal_focus / goal_unfocus | Live capture — record real actions into a goal's trace as you work |
connector_add / connector_call / … | Plug in external MCP servers (GitHub, GCP, …) with autonomy gating |
CLI
keyoku [serve] Start the MCP server on stdio (Claude Code does this automatically)
keyoku init Wire up the hook + MCP registration
keyoku import Backfill activity from Claude Code + Codex transcripts (kills the cold start)
keyoku export <slug> Bake a workflow into ./.claude/skills — or AGENTS.md with --agents-md
keyoku pause | resume Privacy switch: stop/start all recording and injection
keyoku doctor Verify hooks, MCP registrations, engine, and activity health
keyoku inspect Show exactly what's stored in ~/.keyoku (--secrets scans for leaks)
keyoku status Show goals, templates, connectors
keyoku learn Mine patterns from the activity log
keyoku backfill Repopulate hollow learned workflows from the activity log (--dry-run)
keyoku refine <slug> Turn a workflow's raw steps into a clean, parameterized template (--apply)
keyoku focus <goal> Live-capture actions into a goal's trace (--clear to stop; no arg to show)
keyoku assess <goal> One-shot convergence check
keyoku watch <goal> Re-assess on an interval
keyoku approvals Approve/deny gated connector calls
keyoku audit [n] Show the audit trail
Architecture
Your machine
├── Claude Code (or Cursor, Codex)
│ ├── PostToolUse hook → keyoku record (activity logging)
│ └── MCP connection → keyoku serve (tool calls)
│
└── ~/.keyoku/
├── activity.jsonl (event stream, capped)
├── templates.json (approved workflows)
├── executions.json (run history)
├── goals.json (convergence targets)
└── connectors.json (external MCP services)
The division of labor: heuristics generate candidates for free, the small model refines them cheaply, and your coding agent does the heavy lifting on the subscription you already pay for. Keyoku orchestrates; it never burns frontier tokens.
Configuration
| Env var | Default | Purpose |
|---|
KEYOKU_HOME | ~/.keyoku | State directory |
GEMINI_API_KEY / ANTHROPIC_API_KEY | — | Enable model-refined suggestions |
KEYOKU_SLM_PROVIDER | auto | gemini, anthropic, openai-compat, or none |
KEYOKU_SLM_BASE_URL / KEYOKU_SLM_MODEL | — | Any OpenAI-compatible endpoint (Ollama, LM Studio, LiteLLM, Groq, …) |
KEYOKU_ENGINE_URL | — | Connect a running keyoku-engine: knowledge mirrors into it and queries upgrade to semantic search |
KEYOKU_WF_MIN_SIMILARITY | 0.2 | Jaccard floor for suggesting a learned workflow on a new goal |
KEYOKU_WF_SUGGEST_LIMIT | 2 | Max learned workflows surfaced per assessment |
KEYOKU_BACKFILL_LOOKBACK_MIN | 45 | Minutes before a goal's creation to scan for build-then-verify work |
KEYOKU_BACKFILL_HEAD_STEPS | 8 | Setup steps kept from the front when a backfilled workflow is capped |
KEYOKU_DEBUG | — | Full error stacks |
Security
Approved templates execute shell commands with your privileges — the approval step is the trust boundary. Read SECURITY.md before installing.
keyoku-engine
The Go backend for teams: knowledge graph, semantic search, memory decay, and cross-device sync. Available at github.com/Keyoku-ai/keyoku-engine.
License
MIT — see LICENSE.
