What Is the Purpose of the Registry and Runtime Metadata in OpenClaude Integrations?

The registry stores static provider blueprints while runtime metadata tracks dynamic capabilities, together enabling OpenClaude to validate configurations at build time and adapt behavior during execution.

The Gitlawb/openclaude repository separates provider definitions from live session data to support a modular, extensible integration architecture. Understanding how the Integration Registry and runtime metadata interact clarifies how the CLI discovers providers, validates models, and selects features like vision or tool support without hard-coding provider-specific logic.

The Static Integration Registry

The registry serves as the compile-time source of truth for all supported AI providers, models, and integration tools.

Registry Structure in src/utils/registry.ts

Located at src/utils/registry.ts, the registry imports Zod schemas from src/integrations/types.ts to enforce type safety across provider descriptors. Each entry maps a provider name to its static configuration, including environment variable names for authentication, default API endpoints, and base capability flags. This structure allows OpenClaude to import provider definitions by name rather than embedding URLs or secrets directly in command logic.

According to the source analysis, the registry holds these descriptors as immutable objects that the CLI consults during initialization to validate that a requested provider exists and that all required secrets are present in the environment.

Type Safety and Provider Secrets

The src/utils/providerSecrets.ts file leverages the registry to resolve provider-specific environment variables. By referencing the registry’s static mappings, the secrets utility can prompt users for missing credentials without knowing the specific provider’s auth scheme ahead of time. This decoupling demonstrates how the registry abstracts provider implementation details from the core CLI workflow.

Runtime Metadata and Dynamic Discovery

While the registry defines what could exist, runtime metadata captures what actually exists in the current execution context.

Capturing Live Capabilities

When OpenClaude initializes a provider session, it populates runtime metadata structures with data fetched from the provider’s API. This includes the list of currently available models, per-model token limits, and dynamic capability flags such as vision or toolUse. The src/utils/providerProfiles.ts module caches this per-session information, ensuring that subsequent calls within the same process reuse the discovered state without redundant network requests.

Runtime Metadata Retrieval Functions

The src/utils/registry.ts file exports getProviderRuntimeMetadata(), an async function that accepts a provider name string and returns a metadata object. This function bridges the static registry entry with live API calls, enriching the base descriptor with real-time capacity information. For example, calling await getProviderRuntimeMetadata('openai') returns an object containing the tokenLimit and a capabilities array indicating whether image inputs or function calling are supported at that moment.

Source Code Implementation Patterns

OpenClaude consumes these two layers through specific utility functions that insulate business logic from provider-specific internals.

Listing Registered Providers

To enumerate all available integrations without hard-coding provider names, the CLI calls getAllProviders() from src/utils/registry.ts. This function returns an array of strings representing every provider defined in the static catalog, enabling UI auto-completion and configuration validation.

import { getAllProviders } from '../utils/registry.js';

const providers = getAllProviders();
// Returns: ['openai', 'gemini', 'ollama', ...]
console.log('Installed providers:', providers);

Selecting Models Based on Runtime Constraints

When routing a request that requires tool support, OpenClaude queries the runtime metadata to identify which models actually advertise the toolUse capability. The pickModelWithToolSupport() helper (exposed from src/utils/registry.ts) filters the static model list against live capability flags returned by getProviderRuntimeMetadata(), ensuring the CLI never attempts to invoke tools on an incompatible endpoint.

import { pickModelWithToolSupport } from '../utils/registry.js';

const model = await pickModelWithToolSupport('openai');
console.log('Selected model for tool use:', model);

Summary

• The Integration Registry in src/utils/registry.ts provides a type-safe, static catalog of providers and their configurations using Zod schemas defined in src/integrations/types.ts.
• Runtime metadata captures dynamic, per-session information such as available models, token limits, and capability flags (vision, tool use) via getProviderRuntimeMetadata().
• The registry enables compile-time validation and secret mapping through src/utils/providerSecrets.ts, while runtime metadata enables adaptive behavior selection through src/utils/providerProfiles.ts.
• Together, these layers allow OpenClaude to remain provider-agnostic, building provider interfaces from static descriptors and adjusting execution strategies based on live API responses.

Frequently Asked Questions

What is the difference between the registry and runtime metadata in OpenClaude?

The registry contains static definitions—provider names, required environment variables, and default endpoints—stored in src/utils/registry.ts. Runtime metadata represents dynamic data discovered at session start, such as which models are currently online and their specific token limits.

Where does OpenClaude store provider type definitions?

The TypeScript interfaces and Zod schemas that enforce registry entries are defined in src/integrations/types.ts and consumed throughout the codebase, including src/utils/providerSecrets.ts and src/utils/registry.ts.

How does OpenClaude detect if a provider supports vision or tool use?

During initialization, getProviderRuntimeMetadata() queries the provider’s API and populates a capabilities array. The CLI checks this array for strings like vision or toolUse before enabling corresponding features in the UI or routing engine.

Can runtime metadata change between OpenClaude sessions?

Yes, runtime metadata is session-specific. If a provider adds a new model or updates token limits between CLI invocations, the next call to getProviderRuntimeMetadata() reflects those changes immediately without requiring a code update or registry modification.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}