Documentation

Kata

Kata is a Hermes Agent plugin. It records the tool calls your agent makes, detects multi-step routines repeated across conversations, and proposes each as a reusable tool. A proposal becomes a tool only after you approve it. The compiled tool replays the routine deterministically, with no model calls between steps.

Install

Kata requires Hermes Agent 0.22.0 or newer and has no third-party Python dependencies.

hermes plugins install kata          # from the catalog, pinned to a reviewed commit
hermes plugins enable kata
hermes plugins validate ~/.hermes/plugins/kata   # optional: same checks as catalog CI

Start a new session. Kata begins recording immediately and stays silent until it has something to show you. Open the Kata tab in hermes dashboard to review proposals visually.

To try it without a model or API key, clone the repository and run python scripts/demo.py. It drives the real plugin through a stand-in host that fires the same hooks Hermes does.

Daily use

Work normally. When a routine has appeared in three separate conversations (configurable), Kata proposes it at the end of the session.

/kata                         # list proposals and active katas
/kata review 2                # steps, data flow, permissions, schemas, side effects, validation
/kata approve 2 as deploy_preview
/kata runs kata_deploy_preview  # traces of recent executions
/kata disable kata_deploy_preview
/kata rollback kata_deploy_preview 1

Once approved, the agent sees a new tool, for example kata_deploy_preview(branch), and calls it once instead of repeating the steps. The same commands are available as hermes kata ... in a shell.

Architecture

Module	Responsibility
`runtime.py`	Hook handlers, tool registration and unregistration, the compiled-tool handler, per-call approval.
`miner.py`	Segmentation, windowed counting, maximality, leave-one-out scoring, baseline measurement.
`templating.py`	Argument inference (constants, parameters, data-flow references), rendering and matching.
`validator.py`	Offline pre-activation checks with a replaying stub dispatcher.
`executor.py`	Deterministic step execution with timeouts, bounded retries and traces.
`service.py`	Lifecycle and state transitions shared by the slash command, CLI and dashboard.
`effects.py`, `redact.py`	Side-effect classification and secret masking.
`store.py`	Events, model requests, katas, versions, runs and audit log in one WAL-mode SQLite file.

Pattern discovery

Segmentation

History is split into runs of successful calls inside a single user turn. Failures, pauses longer than five minutes and calls to conversational tools such as clarify break a run. A routine therefore never stitches together work from different requests.

Counting

Every contiguous window of 2 to 8 calls is keyed by its signature: the tool names plus each call's argument keys. Windows are counted once per turn and must recur in at least min_support distinct conversations, so repeating something many times in one chat proves nothing. A window contained in an equally frequent longer window is dropped, which yields whole routines rather than fragments.

Coherence

Every step after the first must be tied to the routine, either by data flow from an earlier result or by a fixed argument. Sequences of tools that recur by chance, with unrelated arguments, are rejected before scoring.

Generalisation

For each argument across occurrences, Kata infers an expression:

Observed	Becomes	Example
Same value every time	Constant	`path="src"`
Equals a field of an earlier result	Reference	`<step 1.matches.0.path>`
Contains an earlier result	Concatenation with a reference	`"wc -l <step 2.path>"`
Changes, not derivable	Input parameter	`"TODO({pattern})"`

Confidence

For each occurrence, a template is built from all the others and must reproduce the held-out call sequence exactly. The share that pass is the fit rate. Confidence is fit_rate x (1 - 0.6^support): 0.78 at three conversations with perfect fit, 0.87 at four. Candidates below min_confidence (0.75) are reported as seen but not proposed.

Validation

Validation runs before a proposal is stored and again at approval. No real tool is called.

Check	What it proves
replay_matches_recorded	Inputs recovered from each recorded example re-render its exact arguments.
holdout_fit	The template generalises to examples it was not built from (at least 90%).
executor_replay	The executor issues the recorded calls, in order, with identical arguments.
failure_handling	An injected error stops the run and skips every later step.
timeout_handling	A hung step times out, is not re-issued, and stops the run.
input_schema, output_schema	Schemas accept recorded data and reject an incomplete call.
no_secrets	No credential or redacted value appears in the spec.
tools_available	Every tool exists today with the schema it had when recorded.
compilable_tools, recorded_examples, side_effects	Structural requirements and disclosure.

Execution

A compiled tool validates its arguments, then for each step renders arguments from inputs and earlier results and calls ctx.dispatch_tool. A step fails on an error payload, [TOOL_ERROR] text, success: false or a non-zero exit_code. The run stops there and returns a trace with every step's status, so the agent can continue by hand from the exact point of failure.

Read-only steps retry once by default. Steps with side effects are never retried.
Each step has a timeout (60 seconds by default). A timed-out step is never re-issued.
Katas with external or unknown effects return an approve directive from pre_tool_call with a fresh rule key on every call, so a remembered approval cannot repeat side effects silently. Under unattended runs, Hermes's approval policy applies.

Lifecycle

Status	Meaning	Registered
candidate	Proposed, waiting for you	No
active	Approved and healthy	Yes
stale	A tool schema changed or your manual runs no longer fit; a revised version is prepared for review	No
suspended	Three consecutive failed runs	No
disabled	Turned off by you; can be re-enabled after re-validation	No
rejected	Declined by you; never proposed again	No

Every version is kept. Approving creates the active version, rollback switches to any earlier approved version after re-validating it, and every transition is written to the audit log with its actor.

Configuration

Settings live under plugins.entries.kata.settings in config.yaml and appear in the Desktop settings form.

Key	Default	Effect
`min_support`	3	Distinct conversations before proposing
`min_confidence`	0.75	Proposal threshold
`max_steps`	8	Longest routine considered
`step_timeout_s`	60	Per-step timeout
`read_retries`	1	Retries for read-only steps
`retention_days`	30	History kept for mining
`record`	true	Pause or resume observation

Reference

Hermes surfaces used

Hooks: post_tool_call, post_api_request, pre_tool_call, pre_llm_call, on_session_start, on_session_end. Context: register_tool (and the returned handle's dispose), register_command, register_cli_command, dispatch_tool, get_config. Storage: plugins.plugin_storage.plugin_db. Drift detection reads tools.registry.registry.get_schema. All are on Hermes's public plugin API list.

Dashboard API

Mounted at /api/plugins/kata/ behind the dashboard's authentication: GET overview, GET katas, GET katas/{id}, POST katas/{id}/approve|reject|disable|enable|rollback, POST mine, GET audit.

Limitations

Kata compiles linear routines. Branching on a result ("if the test fails, then...") stays with the agent.
References resolve against JSON results. Values buried inside free-form text output become parameters instead.
Whether a newly registered tool appears mid-session depends on when the host rebuilds the tool list. It is always available from the next session.
Shell commands are classified conservatively: anything unrecognised is treated as having external effects.