c4ai

c4ai

The package manager for AI CLI tools.

c4ai add -g github
c4ai run github notifs

Why c4ai?

AI agents need tools. MCP servers are complex to set up. c4ai makes it simple:

• Install tools in seconds - c4ai add github just works
• Run from anywhere - c4ai run <tool> <command>
• No MCP boilerplate - c4ai wraps CLI tools as MCP servers automatically
• Local-first - Tools are just scripts, no cloud required

Installation

# With bun (recommended)
bun install -g c4ai

# With npm
npm install -g c4ai

Quick Start

# Add a local registry (directory containing tools)
c4ai config --add-registry ~/my-tools

# Search for tools
c4ai search github

# Install globally (available everywhere)
c4ai add -g github

# Install locally (project-scoped)
cd ~/my-project
c4ai add mongodb

# Run tools
c4ai run github notifs
c4ai run mongodb databases

Commands

Package Management

Command	Description
c4ai add <pkg>	Install package locally
c4ai add -g <pkg>	Install package globally
c4ai remove <pkg>	Uninstall package
c4ai remove -g <pkg>	Uninstall global package
c4ai list	List local packages
c4ai list -g	List global packages

Discovery

Command	Description
c4ai search <query>	Search for packages
c4ai info <pkg>	Show package details

Execution

Command	Description
c4ai run <pkg> <cmd> [args]	Run a tool command
c4ai start <pkg>	Start package as MCP server

Notes:

• Tool flags are supported: c4ai run chrome screenshot https://example.com --full-page
• If a flag conflicts with c4ai run options, use -- to pass-through: c4ai run <pkg> <cmd> -- --help

Configuration

Command	Description
c4ai config	Show current config
c4ai config --add-registry <path>	Add local registry
c4ai config --remove-registry <path>	Remove registry

Project Setup

Command	Description
c4ai init [name]	Create a new tool project
c4ai mcp-config	Generate Claude Code MCP config

Package Format

Tools are defined by a c4ai.json manifest:

{
  "name": "github",
  "version": "1.0.0",
  "description": "GitHub CLI wrapper",
  "entry": "run.ts",
  "runtime": "bun",
  "commands": {
    "notifs": {
      "description": "Your notifications"
    },
    "repos": {
      "description": "List repositories",
      "args": [
        { "name": "user", "required": false }
      ]
    }
  },
  "env": {
    "GITHUB_TOKEN": {
      "required": false,
      "description": "Personal access token"
    }
  },
  "mcp": {
    "enabled": true
  }
}

Manifest Fields

Field	Required	Description
name	Yes	Package name (lowercase, hyphens ok)
version	Yes	Semver version
entry	Yes	Entry point script
description	No	Package description
runtime	No	Runtime: bun (default), node, deno
commands	No	Command definitions for MCP
env	No	Environment variable requirements
mcp.enabled	No	Enable MCP server mode

Storage Locations

~/.c4ai/
├── config.json          # Global configuration
├── packages/            # Globally installed packages
│   └── github/
└── bin/                 # PATH-linked executables (optional)

./
├── c4ai.json            # Project manifest (if a tool)
├── c4ai.lock            # Lock file (reproducible installs)
└── .c4ai/
    └── packages/        # Locally installed packages

MCP Integration

c4ai can generate configuration for Claude Code:

# Generate config for all installed packages
c4ai mcp-config

# Generate for specific packages
c4ai mcp-config --packages github,slack

# Get snippet for a single package
c4ai mcp-config --package github --snippet

Output:

{
  "mcpServers": {
    "c4ai-github": {
      "command": "c4ai",
      "args": ["start", "github"]
    }
  }
}

Add this to your Claude Code MCP settings.

Local Registries

c4ai discovers packages from local directories:

# Add a registry
c4ai config --add-registry ~/agent-tools

# Now packages in ~/agent-tools are discoverable
c4ai search github  # Finds ~/agent-tools/github/

A registry is just a directory containing tool folders, each with a c4ai.json.

Creating Tools

# Create a new tool
c4ai init my-tool
cd my-tool

# Edit `run.ts` and `c4ai.json`

# Test locally
bun run run.ts hello world

# Install for testing
cd ~/some-project
c4ai add --local ~/path/to/my-tool -y
c4ai run my-tool hello world

Tool Entry Point

Tools are simple CLI scripts that output JSON:

#!/usr/bin/env bun

import { cli, output } from '@cli4ai/lib/cli.ts';

const program = cli('my-tool', '1.0.0', 'Example tool');

program
  .command('hello [name]')
  .description('Say hello')
  .action((name?: string) => {
    output({ message: `Hello, ${name || 'world'}!` });
  });

program.parse();

When run via c4ai run, these env vars are set for convenience:

• C4AI_CWD: directory where you invoked c4ai
• C4AI_PACKAGE_DIR: installed package directory
• C4AI_PACKAGE_NAME: resolved package name
• C4AI_ENTRY: absolute path to the tool entry file

Global vs Local Install

Aspect	Global (-g)	Local (default)
Location	~/.c4ai/packages/	./.c4ai/packages/
Scope	Available everywhere	Project only
Lock file	No	Yes (c4ai.lock)
Use case	Utilities (github, slack)	Project-specific (mongodb)

Environment Variables

Tools can require environment variables:

{
  "env": {
    "API_KEY": { "required": true },
    "DEBUG": { "required": false, "default": "false" }
  }
}

Set them in your shell or .env file.

License

MIT