climode

A CLI provider registry and policy gateway that discovers commands from installed CLI tools and exposes them to AI agents through the Model Context Protocol.

climode auto-discovers command trees from any installed binary, enforces per-command access policies, and stores the full provider manifest as a versioned JSON config so teams share identical tool surfaces across environments.

Packages

Package	Description
@lightfastai/climode	CLI entry point, provider discovery, config management, policy engine, and command execution
@lightfastai/climode-mcp	MCP server that exposes providers and commands as tools for AI agents

Quick Start

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Add a CLI tool as a provider
climode add gh

# List registered providers
climode list

# View commands for a provider
climode commands gh

# Disable a dangerous command
climode disable gh repo delete

# Execute a command (for testing)
climode exec gh issue list -- --repo owner/repo

How It Works

Discovery

When you run climode add <binary>, the discovery engine probes the binary to detect the best parsing strategy:

1. Cobra — Go CLIs using __complete introspection
2. Clap — Rust CLIs using completions bash script parsing
3. Generic — Falls back to --help text parsing for everything else

The full command tree (commands, subcommands, flags, arguments) is persisted to climode.json.

Policy

Every discovered command defaults to Enabled. Use climode enable / climode disable to control access per-command. The policy engine checks every invocation before execution — disabled commands are blocked and hidden from agents.

MCP Server

The MCP server (climode-mcp) exposes three tools over stdio:

Tool	Description
list_providers	Returns all registered providers with metadata
get_commands	Returns enabled commands for a provider
execute_command	Runs an enabled command and returns stdout, stderr, and exit code

Claude Desktop / Claude Code Configuration

Add to your MCP settings:

{
  "mcpServers": {
    "climode": {
      "command": "climode-mcp"
    }
  }
}

CLI Reference

Command	Description
climode add <binary>	Register a new CLI tool as a provider
climode remove <provider>	Remove a provider from the manifest
climode list	List all registered providers
climode commands <provider>	Show commands and policies for a provider
climode enable <provider> <command...>	Enable a command
climode disable <provider> <command...>	Disable a command
climode refresh <provider>	Re-discover commands, preserving existing policies
climode exec <provider> <command...> [-- args]	Execute a command after policy check

Manifest

Provider state lives in climode.json:

{
  "version": 1,
  "providers": [
    {
      "name": "gh",
      "binary_path": "/opt/homebrew/bin/gh",
      "version": "2.81.0",
      "strategy": "cobra",
      "registered_at": "2026-03-31T12:00:00Z",
      "commands": [
        {
          "path": ["gh", "issue", "list"],
          "description": "List issues in a repository",
          "args": [],
          "flags": [
            { "name": "repo", "short": "R", "description": "Select another repository", "takes_value": true }
          ],
          "policy": "Enabled"
        }
      ]
    }
  ]
}

Development

# Watch mode (all packages)
pnpm dev

# Run tests
pnpm test

# Type check
pnpm typecheck