@howells/envelope

envelope

Thin wrapper around the claude (Claude Code), codex (Codex CLI), and gemini (Gemini CLI) for strict Zod-validated input/output.

This is designed for local Node apps where you want "model calls" to look like a normal API:

• validate inputs with Zod
• request structured JSON output via --json-schema / --output-schema
• validate outputs with Zod again (defense in depth)

Install

npm install @howells/envelope

Requirements

• Node 20+
• claude CLI installed and authenticated (Claude Code), or
• codex CLI installed and authenticated (Codex), or
• gemini CLI installed and authenticated (Gemini CLI)

Claude Code Options

createClaudeCodeClient()

Option	Type	Default	Description
model	string	"opus"	Model name passed to --model
maxBudgetUsd	number	5	Spend cap per call via --max-budget-usd
timeoutMs	number	120_000	Kill the process after this many ms
options.claudePath	string	"claude"	Path to the claude binary
options.cwd	string	process.cwd()	Working directory for the subprocess
options.env	NodeJS.ProcessEnv	process.env	Environment variables for the subprocess
options.permissionMode	string	"dontAsk"	One of "default", "plan", "dontAsk", "acceptEdits", "bypassPermissions", "auto"
options.tools	string	""	Tools flag; "" (default) omits the flag entirely, "default" enables built-ins
options.systemPrompt	string	—	Full system prompt via --system-prompt
options.appendSystemPrompt	string	—	Appended system prompt via --append-system-prompt
options.allowedTools	string[]	[]	Repeated --allowedTools per entry
options.disallowedTools	string[]	[]	Repeated --disallowedTools per entry
options.fallbackModel	string	—	Fallback model via --fallback-model
options.betas	string[]	[]	Repeated --betas per entry
options.agent	string	—	Agent name via --agent
options.agents	string	—	JSON object string for custom agents via --agents
options.retries	number	1	Retries after timeout kill (total attempts = 1 + retries)
options.retryDelayMs	number	800	Base delay between retries (linear backoff)

Note: total_cost_usd is reported by the Claude Code CLI. If you're using a subscription plan, this may be an estimate and not necessarily an incremental billed amount.

Codex Options

createCodexClient()

Option	Type	Default	Description
model	string	"gpt-5.3-codex"	Model name passed to --model
timeoutMs	number	180_000	Kill the process after this many ms
options.codexPath	string	"codex"	Path to the codex binary
options.cwd	string	process.cwd()	Working directory for the subprocess
options.env	NodeJS.ProcessEnv	process.env	Environment variables for the subprocess
options.skipGitRepoCheck	boolean	true	Skip git repo validation via --skip-git-repo-check
options.sandbox	string	"workspace-write"	One of "read-only", "workspace-write", "danger-full-access"
options.profile	string	—	Profile name via --profile
options.config	string[]	[]	Repeated --config key=value per entry
options.jsonlEvents	boolean	false	Enable JSONL event output via --json
options.image	string[]	[]	Repeated --image path per entry

Gemini Options

createGeminiClient()

Option	Type	Default	Description
model	string	"gemini-3-flash-preview"	Model name passed to --model
timeoutMs	number	180_000	Kill the process after this many ms
options.geminiPath	string	"gemini"	Path to the gemini binary
options.cwd	string	process.cwd()	Working directory for the subprocess
options.env	NodeJS.ProcessEnv	process.env	Environment variables for the subprocess
options.approvalMode	string	"plan"	One of "default", "auto_edit", "yolo", "plan"
options.sandbox	boolean	false	Enable Gemini sandbox mode
options.debug	boolean	false	Enable Gemini debug mode
options.policy	string[]	[]	Repeated --policy path per entry
options.adminPolicy	string[]	[]	Repeated --admin-policy path per entry
options.extensions	string[]	[]	Repeated --extensions name per entry
options.includeDirectories	string[]	[]	Repeated --include-directories path per entry

Note: Gemini does not currently expose a native JSON-schema flag in its CLI. Envelope's Gemini structured mode embeds the JSON Schema into the prompt, parses the returned JSON strictly, and then validates it again with Zod.

Tracking native schema support upstream:

• https://github.com/google-gemini/gemini-cli/issues/13388
• https://github.com/google-gemini/gemini-cli/issues/5021

Usage (Zod envelope)

import { z } from "zod";
import {
  createEnvelope,
  createClaudeCodeClient,
  createCodexClient,
  createGeminiClient,
} from "@howells/envelope";

const summarizeClaude = createEnvelope({
  client: createClaudeCodeClient({ model: "opus", maxBudgetUsd: 2 }),
  input: z.object({ text: z.string().min(1) }),
  output: z.object({ summary: z.string().min(1) }),
  prompt: ({ text }) =>
    `Summarize this in 1 sentence. Return JSON only: ${JSON.stringify({ text })}`,
});

const summarizeCodex = createEnvelope({
  client: createCodexClient({ model: "gpt-5.3-codex" }),
  input: z.object({ text: z.string().min(1) }),
  output: z.object({ summary: z.string().min(1) }),
  prompt: ({ text }) =>
    `Summarize this in 1 sentence. Return JSON only: ${JSON.stringify({ text })}`,
});

const summarizeGemini = createEnvelope({
  client: createGeminiClient({ model: "gemini-3-flash-preview" }),
  input: z.object({ text: z.string().min(1) }),
  output: z.object({ summary: z.string().min(1) }),
  prompt: ({ text }) =>
    `Summarize this in 1 sentence. Return JSON only: ${JSON.stringify({ text })}`,
});

const out = await summarizeClaude({ text: "..." });
console.log(out.summary);

Usage (AI SDK 6)

import { generateText } from "ai";
import { claudeCode, codex, gemini } from "@howells/envelope/ai-sdk";

const { text } = await generateText({
  model: claudeCode("opus"),
  prompt: "Write a haiku about camellias.",
});

const r2 = await generateText({
  model: codex("gpt-5.3-codex"),
  prompt: "Write a haiku about camellias.",
});

const r3 = await generateText({
  model: gemini("gemini-3-flash-preview"),
  prompt: "Write a haiku about camellias.",
});

Structured JSON output is also supported via Output.object():

import { generateText, Output, jsonSchema } from "ai";
import { claudeCode } from "@howells/envelope/ai-sdk";

const { output } = await generateText({
  model: claudeCode("sonnet"),
  prompt: "List three colours and their hex codes.",
  output: Output.object({
    schema: jsonSchema({
      type: "object",
      properties: {
        colours: {
          type: "array",
          items: {
            type: "object",
            properties: {
              name: { type: "string" },
              hex: { type: "string" },
            },
            required: ["name", "hex"],
          },
        },
      },
      required: ["colours"],
    }),
  }),
});

Notes:

• The adapter uses single-shot calls under the hood (streaming is simulated).
• If we want true streaming, we can extend it to use claude --output-format stream-json.
• Codex defaults to workspace-write; opt into danger-full-access explicitly when you really need it.
• Gemini defaults to approvalMode: "plan" so the CLI stays in a read-only posture unless you opt into a more permissive mode.
• Gemini structured output is prompt-guided rather than CLI-schema-native, so strict Zod validation after parsing matters even more there.