cmd-ipc

Why cmd-ipc?

Building applications that span multiple processes, workers, or services often means dealing with complex message passing, type mismatches, and boilerplate code. cmd-ipc solves this by providing a unified, type-safe command system that works across any boundary.

Type-Safe Commands

Define commands with Valibot schemas and get full TypeScript inference across process boundaries. No more runtime type errors.

Universal Channels

Works with Web Workers, Electron IPC, HTTP APIs, WebSockets, and more. Same API everywhere.

Decorator-Based

Use @Command decorators to define handlers. Clean, readable code with zero boilerplate.

Event Broadcasting

Broadcast events across all connected processes with automatic routing and deduplication.

Quick Example

import { CommandRegistry, Command, registerCommands } from '@coralstack/cmd-ipc'
import * as v from 'valibot'

// Define your command schema
const CommandSchema = {
  'math.add': {
    request: v.object({ a: v.number(), b: v.number() }),
    response: v.number(),
  },
} as const

// Create a command handler
class MathService {
  @Command('math.add')
  add({ a, b }: { a: number; b: number }): number {
    return a + b
  }
}

// Set up the registry
const registry = new CommandRegistry({
  id: 'main',
  schemas: { commands: CommandSchema },
})

registerCommands([new MathService()], registry)

// Execute with full type safety
const result = await registry.executeCommand('math.add', { a: 5, b: 3 })
// result is typed as number = 8

Use Cases

Electron Apps

Communicate between main and renderer processes with type safety. No more IPC message mismatches.

Web Workers

Offload heavy computation to workers while maintaining a clean, typed API.

Microservices

Build type-safe HTTP APIs with automatic schema validation via HTTPChannel.

AI Agents

Expose commands as MCP tools for AI agents with automatic schema generation.

Features at a Glance

• Hybrid Tree-Mesh Architecture - Commands route intelligently across connected registries
• Schema Validation - Runtime validation with Valibot, compile-time types with TypeScript
• CLI Tools - Generate schemas from remote services, validate configurations
• Event System - Broadcast events with automatic deduplication
• Private Commands - Keep internal commands hidden from other processes
• Flexible Channels - MessagePort, HTTP, WebSocket, or build your own

---

Ready to get started? Check out the installation guide or explore the examples.