llm-cli-gateway: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This repository contains the llm-cli-gateway (npm llm-cli-gateway, MCP name io.github.verivus-oss/llm-cli-gateway), a production-ready Model Context Protocol (MCP) server that provides unified access to multiple LLM CLI tools (Claude Code, Codex, Gemini, Grok, Mistral Vibe, Devin, and Cursor). The canonical provider list is CLI_TYPES in src/provider-types.ts. The gateway enables multi-LLM orchestration, session management, async job orchestration with durable results, cross-LLM validation, token optimization, and retry logic with circuit breakers. Requires Node >=24.4.0 (uses the built-in node:sqlite module).

The package is developed in this internal repo and released via a public GitHub mirror (verivus-oss/llm-cli-gateway) that publishes to npm. See the memory notes on the release flow before touching anything release related.

Development Commands

Build and Test

The test runner is vitest (npm test == vitest run). The default suite spans src/__tests__/**/*.test.ts and scripts/**/*.test.mjs.

# Build TypeScript to JavaScript (tsconfig.build.json excludes tests)
npm run build

# Run all tests
npm test

# Run a single test file (any path)
npx vitest run src/__tests__/executor.test.ts
# ...or a single test by name
npx vitest run -t "circuit breaker opens"

# Named suite shortcuts
npm run test:unit          # executor.test.ts
npm run test:session       # session-manager.test.ts
npm run test:integration   # real CLI calls (INTEGRATION_TESTS=1)
npm run test:fuzz          # fast-check property/fuzz tests
npm run test:pg            # Postgres-backed suites (spins up PG via scripts/test-pg.sh)
npm run test:all           # npm test + test:pg
npm run test:coverage      # v8 coverage (70% lines/functions/statements, 60% branches)

# Watch mode for development
npm run test:watch

# The full gate. `node scripts/check.mjs --list` prints the steps; they are
# declared in scripts/check-steps.mjs, not chained in package.json.
#
# EVERY step runs and every result is reported, which the previous 22-step
# `&&` chain could not do: one failure hid every step after it, and that is not
# hypothetical, `security:audit` sat at 21 of 22 failing on every developer tree
# so `verify:no-internal-mcp:check` never ran at all. A step blocked by a failed
# dependency is reported SKIPPED and fails the gate; not run is not the same as
# fine. `--fail-fast` restores the old stop-at-first behaviour when you want it.
npm run check
npm run check -- --only lint --only format:check   # one or more steps
npm run check -- --list                            # what the gate contains