The harness with muscle memory.
_{Keyoku watches what you do in Claude Code, Cursor, or Codex, learns your patterns, and turns them into one-command workflows — automatically.}

Get Started • How It Works • MCP Tools • Architecture • keyoku-engine

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:

1. Registers the MCP server — via claude mcp add --scope user, so Claude Code connects on next launch
2. Installs the hooks — activity recording (every Bash/Edit/Write/Read/MCP call), a session-start brief, and prompt-time practice injection
3. Wires Codex too — when ~/.codex exists, the MCP server lands in config.toml automatically (same tools, same workflows)
4. 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}}.

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
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 status           Show goals, templates, connectors
keyoku learn            Mine patterns from the activity log
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_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.