intent-runtime

    Connect Codex

    The current Codex model generates a candidate; Intent Runtime validates it and returns structured intent. This path needs no additional model API key. See Compatibility for CLI and Desktop loading and verification boundaries.

    1. Save configuration

    In an ESM project, save intent.host.config.js, for example D:\Worker\my-app\intent.host.config.js, with "type":"module" in package.json. Use .mjs for a standalone file without project configuration. Both extensions accept the same content. This configuration imports no package, so it can live outside node_modules projects.

    export default {
  mode: 'host',
  instances: {orders: {language: 'en', schema: {
    type: 'object',
    properties: {orderId: {type: 'string', description: 'An order ID explicitly supplied by the user; preserve leading zeros; applies only to order intents'}},
  }}},
};

    The file is trusted Node.js code. If you add package imports, those dependencies must resolve from its directory. Global installation does not change local ESM resolution.

    2. Install and register

    Complete global installation. Replace the configuration path with its real absolute location. Installation provides commands; setup changes this module's client registration.

    PowerShell:

    intent-runtime setup --host codex --config "D:\Worker\my-app\intent.host.config.js"

    macOS/Linux:

    intent-runtime setup --host codex --config "$PWD/intent.host.config.js"

    setup registers user-level MCP and installs the Skill in host mode. Reload configuration as required by your client; start a new CLI session. You should discover intent_prepare, intent_accept, and intent_cancel. Ordinary npm installation does not change client configuration.

    3. Recognize a request

    Ask Codex explicitly:

    Use intent-runtime to recognize: "Look up order 000123. Do not cancel the order."
Extract the order ID and show the user's goal and prohibition. Do not perform order operations.

    Expect the lookup goal, the prohibition, and string "000123". The installed Skill guides the tool handoff without requiring you to repeat protocol instructions. It does not automatically process all messages.

    Tools, candidates, and final results
    What you seeMeaningFinal recognition result?
    HostTask from prepareinstructions, input, outputSchema, handoff identityNo
    Model-generated candidateTextCandidate understanding submitted to acceptNo
    IntentResult from acceptValidated full structure; inspect field states and issuesYes
    Ordinary chat reply or cancel statusExplanation or end of handoffNo

    Visible tools without prepare/accept prove only registration. Verify the complete chain on first use. Supply relevant material explicitly on subsequent recognition; an MCP connection does not store your business conversation.

    Tools and replies

    Use prepare → current model candidate → accept; cancel if it cannot complete. See Host handoff for parameters, replay, budgets, and record retention. Records support this recognition, not a durable application session.

    Manual MCP form

    FieldValue
    Nameintent-runtime
    TypeSTDIO
    CommandActual intent-runtime-mcp executable path
    Argument 1--config
    Argument 2Absolute configuration path
    Working directoryAccessible local directory; does not change config-module package resolution

    Manual command/args registration does not install the Skill. Use the explicit request above. Logs go to stderr; stdout carries MCP only.

    Diagnose

    intent-runtime doctor --host codex
    SymptomCheck
    Command missingGlobal npm bin on client PATH; use an absolute executable path if needed, including .cmd where supported
    Configuration fails to loadAbsolute .js/.mjs path; type=module for .js; local dependencies in its project
    Only intent_parse appearsCheck executor versus host mode and reload the client
    Model never completes a candidateEnd recognition; do not treat ordinary chat as a final Result
    HOST_REQUEST_NOT_FOUNDSession change/restart; prepare again with complete material

    doctor does not call a model. See Maintenance for update, repair, cleanup, dry-run, flags and exit codes.