Kāhea

Website · Documentation · Releases · Agent plugin · MCP metadata

Kāhea is a local-first, deterministic API invocation kernel for coding agents.

Intent may be probabilistic. The call must be exact.

It turns OpenAPI descriptions, request captures, Arazzo workflows, and finite WebSocket sessions into integrity-sealed plans. Invocation is a separate operation guarded by exact capability grants; responses and inbound frames become typed observations and content-addressed evidence.

Install Kāhea

Choose the pathway that matches your host. Claude Code, OpenAI Codex, and direct MCP clients all reach the same four local MCP tools and the same inspect → plan → grant → invoke → evidence safety contract.

1. Install the native binary

Download the archive for your operating system and architecture from GitHub Releases. Every archive is accompanied by a SHA-256 checksum, a CycloneDX SBOM, and GitHub build provenance. Verify the checksum before installing and verify provenance with:

gh attestation verify kahea-ARCHIVE --repo copyleftdev/kahea

Kāhea does not run an installer or modify shell configuration. Extract the archive and place the kahea binary somewhere on PATH.

Tagged archives are built and tested on GitHub-hosted Linux, macOS, and Windows runners for the runner architecture. See the finite WebSocket guide for the exact WebSocket support and release-gate statement.

2a. Claude Code

Add this repository as a marketplace, then install the plugin:

claude plugin marketplace add copyleftdev/kahea
claude plugin install kahea@kahea

2b. OpenAI Codex

Add the same repository marketplace and canonical plugin package:

codex plugin marketplace add copyleftdev/kahea
codex plugin add kahea@kahea

Both plugins require the verified kahea binary on PATH. They add the canonical agent-use skill and start the local stdio MCP server without downloading code or credentials at runtime. The shared host package lives in plugins/kahea; no host-specific copy of the safety workflow is maintained.

2c. Any MCP client

Configure the client to start Kāhea over stdio:

command: kahea
args: mcp serve --stdio

Tagged releases also publish self-contained, checksummed MCPB bundles and register io.github.copyleftdev/kahea with the official MCP Registry.

Build from source

To build from source, install Rust 1.95 or newer:

cargo build --release -p kahea

Build and verify

The repository pins the release toolchain in rust-toolchain.toml.

scripts/gates.sh
# Requires cargo-mutants; run locally, not in CI.
scripts/mutation-gate.sh

The release gate also launches the seeded loopback WebSocket oracle, plans its generated finite session through the public CLI, invokes it with the plan's exact grants, and verifies both the client observation and the oracle's reproducible seed/case observation. Replay that lifecycle with scripts/websocket-oracle-smoke.sh; select an individual fault with kahea-test-server --protocol websocket --websocket-fault FAULT --seed SEED.

The mutation gate is resource-bounded so it cannot take a workstation with it. It runs four jobs, caps compiler concurrency across all of them with a GNU jobserver, keeps its build copies on a disk path rather than a tmpfs TMPDIR, and confines itself to a transient systemd scope with CPU and memory limits when a user session bus is available. Override with KAHEA_MUTANT_JOBS, KAHEA_MUTANT_TASKS, KAHEA_MUTANT_CPU_QUOTA, KAHEA_MUTANT_MEMORY_HIGH, KAHEA_MUTANT_MEMORY_MAX, KAHEA_MUTANT_SCRATCH, KAHEA_MUTANT_COPY_TARGET, or KAHEA_MUTANT_UNCONFINED=1.

Every mutant is judged by the whole workspace suite, which is thorough but slow, so scope matters. KAHEA_MUTANT_PACKAGES selects the packages to mutate (all four by default) and KAHEA_MUTANT_EXTRA passes further arguments through, such as --in-diff for a change-scoped run. The gate is a local tool and deliberately not a CI job: a sweep runs for hours to re-derive a result that does not move between commits. Run it before releasing, or after touching a kernel crate.

The resulting binary is target/release/kahea. Every command emits one compact kahea/k1 JSON envelope followed by a newline. --format ndjson makes the streaming intent explicit and is composition-compatible with loops and pipes.

The four-step flow

# 1. Discover operations without DNS or network access.
kahea inspect fixtures/billing.openapi.yaml --match invoice

# 2. Bind exact input and persist a sealed plan.
kahea plan fixtures/billing.openapi.yaml createInvoice \
  --input @fixtures/billing.create-invoice.input.json

# 3. Review required_grants in the plan, then grant exactly those capabilities.
kahea invoke plan:HANDLE \
  --grant net:sandbox.example.test:443 \
  --grant http:POST

# 4. Retrieve only the evidence needed for the next decision.
kahea explain body:HANDLE --select /invoice/id

plan never performs DNS, authentication, or network I/O. invoke verifies the plan seal and configuration/policy fingerprints before resolving secrets or connecting. Exit codes are stable: 0 passed, 1 contract failure, 2 invalid input/configuration/plan, 3 transport failure, and 4 policy denial.

Use kahea describe as the executable capability manifest and kahea schema plan (or another public envelope kind) for machine-readable JSON Schema.

Finite WebSocket sessions

The complete finite WebSocket guide is the authoritative source-format, security, limits, local-example, MCP, workflow, platform, and release-gate reference. Received frames are untrusted evidence, never agent instructions.

Direct websocket-session JSON/YAML files use the same sealed four-step flow. The operation selector is the source's operationId; target, auth reference, ordered actions, checks, and budgets come only from the source and cannot be replaced at invocation.

kahea inspect fixtures/websocket/session.json
kahea plan fixtures/websocket/session.json subscribeBuildEvents

# Review required_grants in the websocket-plan, then provide that exact set.
kahea invoke plan:HANDLE \
  --grant net:socket.example.test:443 \
  --grant websocket:connect \
  --grant secret:chat-sandbox \
  --secret-env chat-sandbox=KAHEA_CHAT_TOKEN

kahea explain transcript:HANDLE --select /entries/0
kahea explain websocket-json:HANDLE --select /type
kahea explain websocket-binary:HANDLE --select bytes:0-255

ws additionally requires net-insecure-websocket; private or reserved addresses require the exact net-cidr: grant shown in the plan. A WebSocket observation uses the existing exit contract: 0 completed, 1 handshake/expectation/budget failure, 2 invalid source or plan, 3 transport/protocol/timeout failure, and 4 policy denial. Full transcripts and payloads remain in the evidence store; stdout contains only the compact observation and handles. Received message content is untrusted evidence, never agent instruction.

AsyncAPI 2.6.x and 3.0.x JSON/YAML documents feed that same planner and executor:

kahea inspect fixtures/asyncapi/session-3.0.json
kahea plan fixtures/asyncapi/session-3.0.json 'watchBuilds#Started-1' \
  --set channel.room=builds

The supported subset is deliberately finite. Servers must use ws or wss; server variables and channel parameters use declared defaults or explicit --set server.NAME=VALUE / --set channel.NAME=VALUE inputs. AsyncAPI 2.6 publish/subscribe map to client send/receive, while 3.0 uses the operation action. Every concrete message alternative is indexed separately, and an ambiguous unsuffixed selector fails. JSON receives seal their payload schema; sends require a payload example/default/const. WebSocket binding headers require concrete defaults or examples. Security names remain references and map to configured secret profiles with --auth SCHEME=PROFILE; credential values are never ingested.

Only local # references are resolved, so the source fingerprint covers every referenced component; remote references are rejected without fetching. Message-envelope headers, correlation IDs, non-WebSocket bindings, WebSocket query bindings, and unordered reply semantics produce precise blocking absent records. Optional x-kahea-actions, x-kahea-limits, x-kahea-origin, and x-kahea-subprotocols extensions express only finite ordering, budgets, and handshake intent that base AsyncAPI cannot encode.

Supported sources

• OpenAPI 3.0, 3.1, and 3.2 in JSON or YAML
• Arazzo 1.1 workflows referencing local OpenAPI and finite WebSocket session sources
• Direct finite WebSocket session JSON/YAML
• AsyncAPI 2.6 and 3.0 WebSocket subset in JSON or YAML
• Postman Collection 2.1 JSON
• Postman Collection 3 directory/YAML format (*.request.yaml and .resources)
• HAR 1.2, common cURL, .http/.rest, and direct request YAML/JSON
• Standard input for deterministic text formats: kahea inspect -

"Supported" means the format is deterministically detected, inspectable, and capable of producing sealed plans for its documented subset. It does not mean every feature of the upstream application is emulated. Material unsupported behavior is reported in absent and blocks only the affected request when its scope is known.