Activity tracing
A PostToolUse hook records every Bash, Edit, Write, and Read tool call.
Events land in ~/.keyoku/activity.jsonl (size-capped ~10k events). Successful connector calls are recorded too.
Keyoku / Overview
The harness with muscle memory.
Keyoku watches how you work in Claude Code, learns the patterns you repeat, and turns them into one-command workflows. A TypeScript MCP server and CLI in a single npm package.
Local-first. No cloud, no telemetry. Zero API keys required.
Features
What the harness does.
Keyoku covers the full loop: trace what you do, mine what repeats, and run what you approve — with connectors, goals, and an audit trail around it.
Pattern mining
Heuristic detection of 2–6 step sequences that repeat at least 3 times.
Mined within each session, counted across sessions, with non-overlapping occurrence counting. Sequences need at least one ACTION step, so pure looking-around chains never qualify.
One-command workflows
Approve a suggestion and it becomes a template you can run anywhere.
Templates support bash, mcp_call, agent_prompt, and human_review steps. Executions persist step-by-step and resume in order.
Connectors
Register external MCP servers — stdio, HTTP, or synthesized from an OpenAPI spec.
Each connector gets an autonomy level: observe, suggest, approve, or autonomous. Approval-gated calls queue for your sign-off.
Goals
Convergence mode: define machine-checkable criteria and let the harness keep checking.
Probes are command, http, or mcp calls with assertions. Re-assess on demand or run a CLI watch loop.
Audit trail
Every action lands in an append-only audit log.
Inspect it with the audit_list tool or `keyoku audit` from the CLI.
Fact sheet
The essentials.
| Item | Detail |
|---|---|
Package | keyoku on npm — MCP server + CLI in one |
Language | TypeScript |
License | MIT |
Repository | github.com/Keyoku-ai/keyoku |
State | ~/.keyoku (directory mode 0700, files 0600) |
Agents | Claude Code first-class; Cursor and Codex via MCP |
Keyoku vs Keyoku Engine
Two pieces, clearly split.
keyoku (TypeScript, MIT) is the workflow harness on this page. keyoku-engine (Go, BSL 1.1) is the separate backend for the knowledge graph, semantic search, and team sync — see the Engine docs.
Quick start
One command.
# Registers the MCP server and the activity hook
npx keyoku init
# Restart Claude Code, then check
keyoku statusDive deeper.
Follow the quickstart, see the full pipeline, or jump straight to the tool reference.