ModelHitch 0.1.0

<p align="center"> <img src="https://raw.githubusercontent.com/genoventures-labs/ModelHitch/main/repo_assets/repo_banner.png" alt="ModelHitch — LLM temp agency" width="100%"/> </p>

<p align="center"> <strong>Hitch any model to your app.</strong><br/> One TypeScript API. Your keys. Hosted or local models. No runtime dependencies. </p>

<p align="center"> <a href="https://www.npmjs.com/package/modelhitch"><img alt="npm version" src="https://img.shields.io/npm/v/modelhitch?style=for-the-badge&color=8bd600"/></a> <a href="https://www.npmjs.com/package/modelhitch"><img alt="npm downloads" src="https://img.shields.io/npm/dm/modelhitch?style=for-the-badge&color=cc3f88"/></a> <a href="./LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-17b8d4?style=for-the-badge"/></a> <img alt="Node 18 or later" src="https://img.shields.io/badge/node-%E2%89%A518-8bd600?style=for-the-badge&logo=node.js&logoColor=white"/> <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-ready-3178c6?style=for-the-badge&logo=typescript&logoColor=white"/> </p>

<p align="center"> <a href="#install">Install</a> · <a href="#agent-skills--plugins">Agent skills</a> · <a href="#what-you-get">Features</a> · <a href="./docs/guide.md">Guide</a> · <a href="./examples">Examples</a> </p>

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

<p align="center"> <img src="https://raw.githubusercontent.com/genoventures-labs/ModelHitch/main/repo_assets/All4.png" alt="ModelHitch plugins and skills for Codex, Cursor, VS Code, and Claude" width="100%"/> </p>

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.

What you get

<p align="center"> <img src="https://raw.githubusercontent.com/genoventures-labs/ModelHitch/main/repo_assets/own_section.png" alt="One interface. BYOK. Any model, any time." width="85%"/> </p>

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.

<p align="center"> <img src="https://raw.githubusercontent.com/genoventures-labs/ModelHitch/main/repo_assets/footer_repo.png" alt="ModelHitch — We route. You build." width="90%"/> </p>