llm-cli-gateway

Unified MCP server providing access to Claude Code, Codex, and Gemini CLIs through a single gateway. Features multi-LLM orchestration, persistent session management, async job execution with polling, approval gates, retry with circuit breakers, and token optimization. Install: npx -y llm-cli-gateway

"Without consultation, plans are frustrated, but with many counselors they succeed."— Proverbs 15:22 (LSB)

Secure local control plane for AI coding agents.

llm-cli-gatewaylets supported MCP clients operate Claude Code, Codex, Gemini/Antigravity, Grok Build, Mistral Vibe, Cognition Devin, Cursor Agent, and configured HTTP API providers through one user-owned gateway while preserving native CLI sessions, local credentials, durable async jobs, validation receipts, and review workflows.

Why developers try it:use the client you are already in to delegate work to local coding agents, scope remote execution to registered workspaces, gate risky actions, survive disconnects, and collect auditable review evidence without turning those agents into a generic chat proxy.

Current signals:CI and security workflows pass onmain, OpenSSF Scorecard is published, OpenSSF Best Practices is passing, releases use Sigstore signing, and the package is MIT licensed.

Or use directly withnpxfrom an MCP client:

{ "mcpServers": { "llm-gateway": { "command": "npx", "args": ["-y", "llm-cli-gateway"] } } }

llm-cli-gatewayis a single-user MCP control plane for operating AI coding agents from supported local or remote clients. It is more than a thin CLI wrapper:

- Runs registered provider CLIs and configured HTTP API providers through consistent sync and async MCP tools.
- Persists long-running jobs, supports restart-safe result collection, deduplication, cancellation, and sync-to-async deferral.
- Tracks sessions, real CLI resume paths, structured response metadata, and cache telemetry.
- Supports cache-awarepromptParts, including explicit Claudecache_controlwhen opted in.
- Can run supported provider requests inside gateway-managed git worktrees for isolated multi-agent review and implementation loops when using the local file-backed session manager. PostgreSQL-backed sessions reject this filesystem-local feature before creation. Grok, Devin, and Mistral require an explicit provider-nativesessionIdfor a gateway worktree; fresh,createNewSession, andresumeLatest-only worktree requests fail closed because they cannot durably reselect it. Materialization suppresses repository, system, and global Git hooks, configured clean, smudge, and process checkout filters, sparse checkout, and lazy object fetching. Filter-dependent content such as Git LFS remains in its repository representation instead of executing host commands.
- Ships personal-appliance setup surfaces: HTTP transport with bearer-token auth,doctor --json, setup UI artifacts, provider setup snippets, Docker fallback, and checked release bundles.
- Remote web connectors use MCP OAuth discovery and authorization-code setup with static client or shared-secret gates. Client secrets are generated locally, stored only as hashes, and printed only by explicit copy-once commands.
- Provider CLI requests can select registered workspaces by alias viaworkspace; every HTTP/tunnel request must use a registered alias, session workspace, or[workspaces].defaultbefore provider execution. Local unrestricted filesystem access is the stdio transport.

The repo ships agent-ready workflow skills under.agents/skillsfor async orchestration, session continuity, multi-LLM review, implement-review-fix loops, retrospective evidence walks, secure approval-gated dispatch, and Personal Agent Config Kit operations. Nine caller-facing skills are bundled in the published npm package:async-job-orchestration,multi-llm-review,session-workflow,secure-orchestration,implement-review-fix,retrospective-walk,public-demo-session,least-cost-routing, andpersonal-agent-config-kit. Machine-readable DAG-TOML plans live underdocs/plansandsetup/install-plan.dag.tomlfor workflows that need deterministic sequencing and verification gates.

Skill packs can be updated outside the core npm release by placing skill directories in local, operator-controlled paths. The gateway loads bundled skills first, then[skills].paths, thenLLM_GATEWAY_SKILLS_PATH, then~/.llm-cli-gateway/skillswhen it exists; later roots override earlier skills by name. Each skill is a directory containingSKILL.md. A root may also carryskill-pack.jsonto pin expectedSKILL.mdhashes:

[skills] paths = ["/opt/llm-cli-gateway/skills"]

export LLM_GATEWAY_SKILLS_PATH="/opt/team-skill-pack:/opt/incident-skill-pack"

{ "name": "team-pack", "version": "1.0.0", "skills": [ { "name": "incident-retrospective", "sha256": "<sha256 of incident-retrospective/SKILL.md>" } ] }

The loader is intentionally local-only: it never fetches remote Markdown at startup. To update a pack, install or replace files through your package manager or deployment system, then restart the gateway so the advertisedskills://...resources refresh.

The next documentation focus is provider-specific skill and DAG-TOML pairs for each outbound CLI and API-provider family: Claude, Codex, Gemini/Antigravity, Grok, Mistral Vibe, Devin, Cursor Agent, OpenAI-compatible endpoints, Anthropic Messages, and xAI Responses. The implementation plan is tracked indocs/plans/provider-workflow-assets.dag.toml, with each provider asset expected to cover install/login checks or token-env checks, session behavior, approval modes, cache/telemetry surfaces, failure modes, and a smoke-test gate.

- CI runs build, lint, format, tests, package checks, and npm audit.
- Security CI runs actionlint, zizmor, shellcheck, typos, osv-scanner, gitleaks, and lychee.
- GitHub release installer artifacts are checksummed and signed with Sigstore keyless signing.
- npm releases use a generated prod-only shrinkwrap and release security audit; GitHub Actions Trusted Publishing exchanges the job's OIDC identity for short-lived npm publish credentials.
- The npm package intentionally ships a generated, prod-onlynpm-shrinkwrap.jsonso registry installs resolve the audited release tree. Release gates regenerate it frompackage-lock.json, compare for parity, and run a registry-fidelity consumer install before publishing.
- Socket behavioural alerts are documented insocket.ymland under "Security Considerations" below.shellAccessandshrinkwrapare reviewed package capabilities/configuration for this CLI appliance, not hidden install behaviour.

The product contract is documented in[docs/personal-mcp/PRODUCT_CONTRACT.md. It defines the single-user scope, security posture, target support matrix, and provider-support verification gates. Public setup guides must not claim ChatGPT, Claude web, Claude Desktop, Codex, Gemini CLI, Gemini web, or Grok inbound support until the corresponding provider/client path has been verified.

This project does not provide hosted multi-tenant credential custody. Provider credentials stay on the user's machine or user-owned deployment volume.

…