Provider harness by day. Temp agency for LLMs by accident.

ModelHitch normalizes chat, streaming, tools, BYOK credentials, model discovery, failover, and usage across OpenAI, Anthropic, OpenRouter, Groq, Together, OpenCode, and local runtimes. It can also expose them through one local multi-wire bridge for coding agents and IDEs.

Install

npm install modelhitch

import { ModelHitch } from 'modelhitch';

const mh = new ModelHitch();
const result = await mh.chat({
  provider: 'opencode-zen',
  model: 'big-pickle',
  messages: [{ role: 'user', content: 'Clock in.' }],
});

console.log(result.message.content);

Chat, streaming, tools, custom providers, and React hooks use the same provider-neutral types. Open the technical guide →

Agent skills + plugins

Give your agent the ModelHitch playbook in one command:

npx modelhitch setup codex    # claude | cursor | vscode | all

Personal installs are the default. Add --project for the current repo, --dry-run to preview, or --force to update an existing install.

| Agent | Skill command | Full package | | --- | --- | --- | | Codex | npx modelhitch setup codex | Plugin guide | | Claude | npx modelhitch setup claude | Two-skill guide | | Cursor | npx modelhitch setup cursor | Plugin guide | | VS Code / Copilot | npx modelhitch setup vscode | Agent Plugin guide |

What you get

| Surface | Included | | --- | --- | | Library | chat, stream, tools, model discovery, typed errors, custom providers | | Web apps | Browser bundler support via modelhitch/browser — no Node polyfills | | Android | Native Kotlin SDK, coroutine streaming, Compose sample, Android Keystore BYOK storage | | Flutter | Dart SDK, SSE streaming, secure BYOK storage, OpenAI-compatible providers and bridges | | BYOK | Request keys, memory storage, browser local storage, environment fallback | | React | useChat, useStream, and a bridge client via modelhitch/react | | Bridge | OpenAI Chat/Responses/Images, Anthropic Messages, and Gemini GenerateContent wires | | Reliability | Automatic 429/5xx/network failover across models and providers | | Usage | Tokens, estimated spend, latency, failovers, dashboard, optional SQLite |

Providers

OpenCode Zen · OpenCode Go · OpenAI · Anthropic · Groq · OpenRouter · Together AI · HuggingFace · Google Gemini · DeepSeek · xAI · Mistral · Moonshot · Z.ai (GLM) · LM Studio · Ollama · vLLM · llama.cpp · KoboldCpp · mock

Android SDK

The android-sdk subtree is a native Kotlin implementation for Android 6.0 and later. It provides provider-neutral chat types, Flow streaming, tool-call events, built-in OpenAI-compatible providers, typed errors, model listing, and AES-GCM credential storage backed by Android Keystore. It does not embed Node.js or a JavaScript runtime.

dependencies {
  implementation("io.github.bobbybacklogs.modelhitch:modelhitch-android:0.1.0")
}

val keys = AndroidKeyStoreCredentialStore(applicationContext)
keys.set(selectedProviderId, userProvidedKey)

val hitch = ModelHitch(
  providers = DefaultProviders.all,
  keyStore = keys,
)

hitch.stream(
  ChatRequest(
    provider = selectedProviderId,
    model = selectedModelId,
    messages = listOf(ModelMessage.User(text("Hello from Android"))),
  ),
).collect { chunk ->
  if (chunk is StreamChunk.TextDelta) append(chunk.text)
}

Android setup, architecture, security, sample, and build guide →

Dart and Flutter SDKs

The flutter-sdk subtree contains a Dart 3.4 core and a Flutter 3.22 adapter. modelhitch_dart owns the provider-neutral types, OpenAI-compatible transport, Stream-based SSE events, typed errors, model listing, and extension contracts. modelhitch_flutter re-exports that core and adds encrypted per-provider credential storage through flutter_secure_storage.

dependencies:
  modelhitch_flutter: ^0.1.0

final hitch = ModelHitch(keyStore: FlutterSecureKeyStore());

hitch.stream(
  ChatRequest(
    provider: 'openai',
    model: 'gpt-4o-mini',
    messages: [ModelMessage.user(MessageContent.text('Hello from Flutter'))],
  ),
).listen((chunk) {
  if (chunk case TextDelta(:final text)) append(text);
});

Store only keys provided by a device user. For an application-owned credential, point an OpenAICompatibleProvider at a backend or ModelHitch bridge instead.

Dart/Flutter setup, security, extension contract, and publishing guide →

Local agent bridge

npx modelhitch bridge --background
npx modelhitch status
npx modelhitch settings

Point compatible clients at http://127.0.0.1:3939/v1, then route models as providerId/modelId. The bridge includes automatic failover and a local usage dashboard at http://127.0.0.1:3939/usage. Its OpenAI-compatible image lane is disabled by default and can be enabled from http://127.0.0.1:3939/settings or with --image-lane.

modelhitch settings opens an OpenTUI editor for routing, image-generation, and reliability settings without requiring the bridge or web UI. It edits the same local config file and preserves policy lanes, catalog choices, and API keys. The TUI currently requires Bun; all other ModelHitch commands retain their existing Node.js runtime support.

The packaged bridge uses SQLite persistence and requires Node.js 22.5+. The application library supports Node.js 18+.

Bridge setup, client configs, routing, security, and operations →

Development

npm install
npm run typecheck
npm test
npm run build

The quickstart and BYOK UI use the deterministic mock provider without an API key. Public contributions are currently closed, but the project is MIT licensed—clone it, inspect it, and remix your own.