Planner transports

Prose flows compile to IR via a pluggable LLM transport. There are four of them — pick whichever matches the credentials you already have.

Transport	When to use
`api`	You have an `ANTHROPIC_API_KEY` and want the most direct route
`via-cli`	You already pay for `claude` / `codex` / `gemini` on the CLI
`manual`	Air-gapped CI, paste-once, or quick experiments with any chat LLM
`via-mcp`	An MCP server exposes `plan_flow` (klera’s own, or a third party)

All four produce a bit-identical SemanticPlan — same Zod gate, same cache shape, same _meta envelope (only the model tag differs). ANTHROPIC_API_KEY is gated only on the api transport.

Pick a transport

klera init writes the chosen transport into .klera/config.yaml. Adopters edit the file to switch later:


planner:
  transport: via-cli   # api | via-cli | manual | via-mcp
  cli: claude          # for via-cli only

Per-invocation overrides:

--planner-cli <name> — override planner.cli for one run.
--via-cli <name> — explicit via-cli transport on klera plan or klera compile.
--manual — explicit manual transport.
--via-mcp <command> — explicit via-mcp transport, spawn the given MCP server and route plan_flow through it.

klera doctor reports the active transport with a “subscription-paid” hint when via-cli is active — useful confirmation that you are not about to burn API credit unnecessarily.

Auto-detection rules

When you run klera plan or klera compile and no transport is explicitly configured, the resolver walks this order:

Explicit per-invocation flag

--via-cli, --manual, --via-mcp win unconditionally.

`.klera/config.yaml` `planner.transport`

Whatever the file says, with planner.cli honoured for via-cli.

`ANTHROPIC_API_KEY` set

The api transport activates. No CLI probe runs.

`PATH` probe for adapter CLIs

The detector walks every PATH directory and probes for executables named claude, then codex, then gemini, in that order. The first hit wins; the resolved absolute path is recorded for the spawn. On Windows, .exe / .cmd / .bat suffixes are tried in turn.

Failure

No transport — klera plan / klera compile errors out with the list of options and tells you which env var or file edit unlocks each.

The four transports

api

Direct call to the Anthropic API. The most straightforward path when you have a key.


export ANTHROPIC_API_KEY=sk-ant-...
klera plan flows/login.flow.md --snapshot snapshots/login.json

The CLI compiles the prose against the snapshot, validates the SemanticPlan, and writes the cache to flows/login.flow.json.

_meta.model records the model tag — claude-sonnet-4-6 or whichever model the planner version pinned.

Token usage is whatever your account is metered on. Adopters who care about CI cost typically pair api with klera compile --all --check so CI never compiles — it only verifies the local cache is up to date.

via-cli

Spawns your local coding-agent CLI as a subprocess. The prompt goes in via stdin, JSON comes out on stdout. No API key required — auth is whatever the CLI already has.


klera plan flows/login.flow.md \
  --snapshot snapshots/login.json \
  --via-cli claude

Adapters in priority order:

name	command	display name
`claude`	`claude`	Claude Code
`codex`	`codex`	OpenAI Codex
`gemini`	`gemini`	Gemini CLI

If --via-cli is passed without a name, the first detected adapter on PATH wins. Adopters who want a non-default preference set planner.cli in .klera/config.yaml once.

On parse failure (the CLI returned prose around the JSON, or the JSON did not match the Zod schema), the planner retries with progressively stricter prompts — strict-JSON preamble first, then Zod errors injected as feedback. Default budget: 3 retries.

Adding a new CLI is a single entry in the adapter table plus a contract test; the planner code path does not change.

manual

Writes the planner prompt to disk. Paste into any chat LLM, paste the response back. Useful for air-gapped environments or one-off experiments.


# Step 1: write the prompt
klera plan flows/login.flow.md \
  --snapshot snapshots/login.json \
  --manual
# → wrote flows/login.plan-prompt.md
 
# Step 2: paste flows/login.plan-prompt.md into any chat LLM,
# save the JSON response to flows/login.plan-response.json
 
# Step 3: validate and cache
klera plan flows/login.flow.md \
  --snapshot snapshots/login.json \
  --apply-response flows/login.plan-response.json
# → wrote flows/login.flow.json

The prompt is self-contained: instructions, schema description, prose body (with {{.dotted.path}} references already substituted), and the compacted element snapshot. It tells the LLM to respond with valid JSON only.

applyManualResponse strips a leading ```json fence if the LLM includes one, so a stray fence does not force you to clean the file by hand. Validation is the same Zod schema the api path uses; ill-formed responses produce an InvalidManualResponseError listing every issue.

via-mcp

Spawns an MCP server and routes plan_flow through it. Pair this with klera’s own MCP server when your editor agent already has LLM credits, or with a third-party MCP server that exposes a compatible tool.


klera plan flows/login.flow.md \
  --snapshot snapshots/login.json \
  --via-mcp 'node ./node_modules/@klera/mcp/dist/stdio.js'

The CLI spawns the command, sends an MCP tools/call for plan_flow with the prose + snapshot + fixtures, and writes the cache from the response. The server-side plan_flow tool either plans directly (if it has its own LLM configured) or returns the prompt body for a host LLM — the CLI handles both response shapes.

See MCP server for klera’s own server.

Same plan, four routes

Whichever transport you pick, the resulting .flow.json cache validates against the same SemanticPlan Zod schema. The _meta envelope tags which transport produced it:


{
  "name": "Login smoke",
  "steps": [ /* identical IR */ ],
  "_meta": {
    "schemaVersion": 1,
    "promptHash": "…",
    "snapshotHash": "…",
    "model": "claude-sonnet-4-6",   // api
    // "model": "via-cli:claude",    // via-cli
    // "model": "manual",            // manual
    // "model": "mcp:host",          // via-mcp
    "plannerVersion": "0.1.0",
    "generatedAt": "2026-05-01T10:30:00.000Z"
  }
}

The cache hash combines prose body + element-graph snapshot + planner version. Switching transports does not invalidate the cache — same inputs, same hash. Bumping the planner version does invalidate it, which is what you want when the prompt itself has been refined.

Hallucination resilience

The planner does not blindly trust the LLM. After the response parses, a semantic check walks the IR against the snapshot using a light matcher ladder. If a target does not resolve, the check returns nearestCandidates and the planner retries with that feedback injected into the next prompt.

Default retry budget is 3. Each retry escalates: strict-JSON preamble, then Zod errors, then semantic-check errors with candidate suggestions. On the final failure, the CLI raises a PlannerHallucinationError carrying every attempt’s response — no half-baked cache writes hit disk.