Skip to content

Write your own host adapter

CADENCE has one engine and three categories of surfaces: the host-agnostic cadence CLI, host adapters that wire a coding agent’s lifecycle into that engine, and the MCP server for MCP-capable hosts. The shipped host adapters today are @thomas-powers-jr/cadence-host-claude-code and @thomas-powers-jr/cadence-host-codex. This guide documents the host-adapter contract so the adapter shape is explicit, versioned, and reproducible.

Scope note. For most new hosts, the supported path is the MCP server (cadence mcp serve), not a fleet of bespoke adapters. Claude Code remains the reference adapter for ambient edit-time gates; Codex is the second shipped conformance consumer. The engine stays host-unaware; an adapter only translates.

The contract lives in @thomas-powers-jr/cadence-types as the HostAdapter interface. An adapter provides six things:

Member Purpose
contractVersion The contract version it targets — must equal ADAPTER_CONTRACT_VERSION.
capabilities A HostCapabilities descriptor of what the host environment can do.
mapEvent Translate a host lifecycle event name into a cadence AbstractEvent.
extractPayload Pull the normalized ExtractedPayload (files, skill, agent identity, compaction trigger) out of a raw host event.
installHooks Wire the host’s lifecycle hooks to the cadence shim, under a project root.
installCommands Install the host’s slash-command (or equivalent) surface, under a project root.
import type { HostAdapter } from '@thomas-powers-jr/cadence-types';
// Install option shapes are host-specific, so they are type parameters —
// the contract never couples to any one host's installer.
export interface HostAdapter<HookOpts = unknown, CommandOpts = unknown> {
readonly contractVersion: number;
readonly capabilities: HostCapabilities;
mapEvent(hostEvent: string, toolName?: string): AbstractEvent | null;
extractPayload(raw: unknown): ExtractedPayload | undefined;
installHooks(root: string, options?: HookOpts): Promise<unknown> | unknown;
installCommands(root: string, options?: CommandOpts): Promise<unknown> | unknown;
}

The engine never sees host-specific event names. It speaks these abstract events (AbstractEvent, validated by AbstractEventZ; a doc-content test keeps this list equal to it):

  • session-start — a session begins
  • user-prompt — the user submits a prompt
  • pre-tool-edit — about to edit a file (blocking-capable)
  • post-tool-edit — a file edit completed
  • session-stop — the session ends (blocking-capable)
  • subagent-result — a spawned subagent returned (blocking-capable)
  • subagent-start — a subagent was spawned
  • skill-invoke — a skill/command was invoked
  • pre-compact — the host is about to compact the session (record-only, never blocking)

pre-compact (phase 345) is hooked by the Claude Code adapter only: its PreCompact hook maps to it, and core writes a machine-facts record under the gitignored .cadence/local/precompact/, one file per compaction named PRECOMPACT-<YYYYMMDDTHHMMSS.mmmZ>.md (a -N suffix on a same-millisecond collision; newest five kept). Each record holds generated_at, the JSON-quoted trigger, the loop position, the active phase, draft and spec, local git facts (no fetch), and the payload’s field names only, never their values. The hook never blocks: core always exits 0 for it, and the Claude Code shim clamps any failure on this event to exit 0. The Codex adapter leaves PreCompact unmapped. The full description and limits are in the cadence hook reference.

Your adapter’s whole job on the read path is to turn your host’s lifecycle into these. Anything your host can’t express, it simply never emits.

HostCapabilities tells the engine what your environment supports. It has a Zod schema (HostCapabilitiesZ) — validate your descriptor against it in a test.

import type { HostCapabilities } from '@thomas-powers-jr/cadence-types';
export const myHostCapabilities: HostCapabilities = {
hooks: ['session-start', 'user-prompt', 'pre-tool-edit', 'post-tool-edit', 'session-stop'],
slashCommands: true,
skillSystem: 'native', // 'native' | 'prompted' | 'none'
blockingHooks: ['pre-tool-edit', 'session-stop'],
subagentSpawn: 'native', // 'native' | 'shell-out' | 'none'
streamingOutput: true,
};

Declare only what the host actually does. The contract is the leaner successor to an earlier over-built capability layer — resist speculative flags.

Dispatched-agent prompts are not orchestrator-visible. A host reporting subagentSpawn: 'native' may let a dispatched background agent’s interactive prompt (e.g. Claude Code’s AskUserQuestion) get answered on a surface the orchestrating session never sees — the orchestrator can end up carrying a confidently wrong account of what happened until an independent transcript read corrects it (rec-20260718-005). The dispatch packet already forbids a dispatched agent from invoking AskUserQuestion, or any equivalent interactive prompt, at runtime; any human approval for a scope change during dispatch must flow back through the orchestrating session, never a side channel the orchestrator can’t see.

mapEvent turns a host event name (plus an optional tool name, to disambiguate) into an AbstractEvent or null. extractPayload normalizes the raw event into the ExtractedPayload the dispatcher consumes:

export interface ExtractedPayload {
files?: string[]; // edit-tool events
skill?: string; // skill-invoke events
agentId?: string; // events fired inside a subagent
agentType?: string;
compactTrigger?: string; // pre-compact: the host's trigger, unchanged
}

In the reference adapter these are mapEvent / extractPayload in packages/host-claude-code/src/event-map.ts. Keep them pure — no I/O.

Installation writes into the consumer’s project so the host calls back into cadence. The reference adapter:

  • installHooks(root, opts) writes a shim invocation into the host’s config (packages/host-claude-code/src/install.ts). The host runs the shim for every lifecycle event.
  • installCommands(root, opts) writes the slash-command surface (packages/host-claude-code/src/install-commands.ts).
  • The shim (packages/host-claude-code/src/shim.ts) reads a raw event on stdin, calls mapEvent + extractPayload, and dispatches into the core CLI.
  • locate-self (packages/host-claude-code/src/locate-self.ts) resolves the local workspace build paths for monorepo dogfood installs.

The two shipped adapters share this plumbing through @thomas-powers-jr/cadence-host-toolkit (adapters depend on it; core never does). Its main entry exports the hook-routing algorithm (routeHookEvent, mapEvent, extractPayload), the managed-hook lists (CLAUDE_CODE_EXPECTED_HOOKS, CODEX_EXPECTED_HOOKS), the shared slash- command catalog, planCoreSpawn (how the shim spawns core; on Windows it passes one joined command string through the shell instead of an args array, which is the same command line but avoids Node 24+’s DEP0190 warning on every hook), and resolveHookShimExit, the shim’s pure exit-code policy. That policy relays core’s exit code for every event except pre-compact (a spawn failure or shim error on any other event still exits 1); for pre-compact any non-zero core exit, signal, spawn failure or shim error resolves to exit 0 with one stderr line naming the cause. A shim that uses it cannot block a compaction even when it runs against an older core that rejects the event (phase 345). Its ./locate-self and ./install-merge subpaths hold the self- locating and managed-marker merge helpers.

The shim and locate-self are host-internal plumbing — the contract does not pin their shapes, because how a host hands you a raw event and how you find your own binary are intrinsically host-specific. The guide describes the responsibility; you implement it however your host requires.

Install portability. Never commit machine-absolute paths into a consumer’s config. The reference adapter’s --local mode embeds absolute paths for dogfood only and warns loudly; the committed form is the portable default. See the Claude Code adapter guide.

Set contractVersion to the ADAPTER_CONTRACT_VERSION your adapter targets. It’s a single integer, bumped only on a breaking change to the contract — so an adapter can assert at runtime that it still matches the engine it ships against.

Prove conformance two ways, exactly as the reference adapter does:

import {
ADAPTER_CONTRACT_VERSION,
HostCapabilitiesZ,
type HostAdapter,
} from '@thomas-powers-jr/cadence-types';
// Compile-time: `satisfies` is the conformance proof.
export const myAdapter = {
contractVersion: ADAPTER_CONTRACT_VERSION,
capabilities: myHostCapabilities,
mapEvent,
extractPayload,
installHooks,
installCommands,
} satisfies HostAdapter<MyHookOpts, MyCommandOpts>;
// Runtime: a test asserts the descriptor validates and the version matches.
HostCapabilitiesZ.parse(myAdapter.capabilities);

The reference assembly is claudeCodeAdapter in packages/host-claude-code/src/index.ts, with the conformance test in packages/host-claude-code/tests/adapter-conformance.test.ts. Use it as the end-to-end worked example.

codexAdapter (packages/host-codex/src/index.ts) is the contract’s second consumer, for the OpenAI Codex CLI. It was built specifically to prove the contract is not Claude-Code-shaped — and it conforms at the same ADAPTER_CONTRACT_VERSION with no bump. Three places it genuinely diverges from the reference are the instructive ones:

  1. extractPayload over a multi-file patch. Claude’s edit tools hand the adapter a single tool_input.file_path. Codex has one edit tool, apply_patch, whose tool_input carries a patch envelope spanning many files (*** Add File: / *** Update File: / *** Delete File: / *** Move to:). The Codex adapter parses those markers into ExtractedPayload.files — a differently-shaped host input normalizing to the same core-facing payload. This is the portability proof in miniature.

  2. Global command install. The Claude adapter writes project-scoped .claude/commands/*.md. Codex custom prompts have no project-level directory yet, so installCommands writes global ~/.codex/prompts/cadence-*.md (honoring $CODEX_HOME) and the CLI warns that the prompts apply to every project. installHooks, by contrast, stays project-scoped (.codex/hooks.json). One adapter, two install scopes — the contract leaves install-option shapes to the adapter for exactly this reason.

    For first-run onboarding, run cadence init --host codex before opening Codex in the repo. That writes the project .codex/hooks.json, installs the global prompt commands, and creates the managed AGENTS.md block Codex reads for project instructions. After approving hooks, start a new Codex session so prompt commands are loaded. If the prompt surface is not loaded yet, ask Codex to run the cadence CLI directly, for example cadence progress.

  3. A near-1:1 event map. Codex’s hook lifecycle (SessionStart/PreToolUse/PostToolUse/Stop/SubagentStop/UserPromptSubmit) maps almost directly onto the same AbstractEvents, and its stdin-JSON shape and JSON decision blocking (permissionDecision: "deny" for PreToolUse, top-level decision: "block" for Stop/SubagentStop, exit 0) mirror Claude’s — so the shim’s parsing and blocking logic carried over with little change. Core emits those decisions and the shim relays core’s stdout and exit code unchanged (phase 317).

Conformance test: packages/host-codex/tests/adapter-conformance.test.ts.

An adapter is the only host-aware code in the system. Everything past mapEvent — the DRAFT→BUILD→SETTLE loop, the gates, the state machine — is the shared engine, described in the loop & gates. Translate the lifecycle, declare honest capabilities, install portably, and the engine does the rest.