Skip to content

Universal CLI for managing AI coding agent configurations. Unify Claude Code, Cursor, Windsurf agents configs with MCP management

License

Notifications You must be signed in to change notification settings

agentinit/agentinit

Repository files navigation

AgentInit

A CLI tool for managing and configuring AI coding agents

AgentInit transforms AI agent configuration from a fragmented, manual process into a unified, automated workflow that ensures every developer gets consistent, context-aware AI assistance tailored to their project's specific needs.

✨ Features

  • πŸ€– Universal Agent Configuration: Unified agents.md file that syncs with all major AI coding agents
  • πŸ” Smart Stack Detection: Automatically detects project language, framework, and tools
  • πŸ”„ Bidirectional Sync: Keep agent configurations in sync across Claude, Cursor, Windsurf, and more
  • πŸ“¦ MCP Management: Interactive installation and management of Model Context Protocol tools
  • πŸ“‹ Rules Templates: Apply coding best practices with predefined rule templates (Git, testing, docs, linting)
  • βš™οΈ Project Templates: Pre-built templates for web apps, CLI tools, libraries, and more
  • 🎯 Stack-Aware Guidance: Customized instructions based on your technology stack

πŸš€ Quick Start

Installation

# Install AgentInit globally
npm install -g agentinit

Basic Usage

# Initialize agent configuration for your project
agentinit init

# Detect current project stack and existing configurations
agentinit detect

# Sync agents.md with agent-specific files
agentinit sync

# Install MCPs interactively
agentinit mcp --interactive

πŸ“‹ Commands

agentinit init

Initialize agents.md configuration for your project.

agentinit init                    # Interactive project setup
agentinit init --template web     # Use web app template
agentinit init --force            # Overwrite existing configuration

Available Templates:

  • web - Web applications (React, Vue, Angular)
  • cli - Command line tools
  • library - Libraries and packages
  • fullstack - Full-stack applications
  • mobile - Mobile applications

agentinit detect

Detect current project stack and existing agent configurations.

agentinit detect           # Basic detection (only shows found agents)
agentinit detect --verbose # Detailed information
DEBUG=1 agentinit detect   # Show all supported agents (found and not found)

Environment Variables:

  • DEBUG=1 - Shows all supported agents, including those not found in the project

agentinit sync

Sync agents.md with agent-specific configuration files.

agentinit sync                # Sync configurations
agentinit sync --dry-run      # Preview changes
agentinit sync --backup       # Create backups

agentinit mcp

Manage Model Context Protocol installations.

agentinit mcp                      # Show top MCPs
agentinit mcp --interactive        # Interactive selection
agentinit mcp --search <query>     # Search MCPs
agentinit mcp --install <name>     # Install specific MCP

agentinit verify_mcp

Verify MCP server installations and get their tools with token usage.

Examples:

# Verify all MCPs in project
agentinit verify_mcp --all
# Verify STDIO server
agentinit verify_mcp --mcp-stdio everything "npx -y @modelcontextprotocol/server-everything"
# Verify HTTP server
agentinit verify_mcp --mcp-http notion_api "https://mcp.notion.com/mcp"  --timeout 30000

Shows connection status, response time, and available tools/resources/prompts for each MCP server.

agentinit apply

Apply configurations including MCP server setup.

MCP Configuration

# Configure STDIO MCP with everything server (recommended example)
npx agentinit apply \
  --mcp-stdio everything "npx -y @modelcontextprotocol/server-everything"

# Configure multiple MCPs in one command
npx agentinit apply \
  --mcp-stdio everything "npx -y @modelcontextprotocol/server-everything" \
  --mcp-stdio supabase "npx -y @supabase/mcp-server-supabase@latest" \
    --args "--read-only --project-ref=<project-ref>" \
    --env "SUPABASE_ACCESS_TOKEN=<personal-access-token>" \
  --mcp-http notion_api "https://mcp.notion.com/mcp" \
  --mcp-sse notion_events "https://mcp.notion.com/sse"

# Configure HTTP MCP with authentication
npx agentinit apply \
  --mcp-http github "https://api.githubcopilot.com/mcp/" --auth "Bearer YOUR_GITHUB_PAT"

# Configure HTTP MCP with custom headers
npx agentinit apply \
  --mcp-http context7 "https://mcp.context7.com/mcp" \
  --header "CONTEXT7_API_KEY:YOUR_API_KEY"

# Multiple custom headers
npx agentinit apply \
  --mcp-http api_server "https://api.example.com/mcp" \
  --header "X-API-Key:YOUR_API_KEY" \
  --header "X-Client-ID:YOUR_CLIENT_ID"

# Combine Bearer auth with custom headers
npx agentinit apply \
  --mcp-http advanced_api "https://api.example.com/mcp" \
  --auth "Bearer YOUR_TOKEN" \
  --header "X-Custom-Header:custom_value"

# Configure Docker-based MCP with environment
npx agentinit apply \
  --mcp-stdio browserbase "docker run -i --rm ghcr.io/metorial/mcp-container--browserbase--mcp-server-browserbase--browserbase node cli.js" \
  --env "BROWSERBASE_API_KEY=browserbase-api-key"

# Global configuration with custom headers
npx agentinit apply --global --client claude \
  --mcp-http context7 "https://mcp.context7.com/mcp" \
  --header "CONTEXT7_API_KEY:YOUR_API_KEY"

# Verify MCPs immediately after configuration
npx agentinit apply --verify-mcp \
  --mcp-stdio everything "npx -y @modelcontextprotocol/server-everything"

This generates .agentinit/agentinit.toml with your MCP configurations.

MCP Authentication Options:

  • --auth "Bearer TOKEN" - Adds Authorization header for Bearer token authentication
  • --header "KEY:VALUE" - Adds custom headers in KEY:VALUE format (can be used multiple times)
  • Both flags can be combined for APIs requiring multiple authentication methods

MCP Verification: Use the --verify-mcp flag to test MCP servers immediately after configuration. This ensures servers are reachable and shows their available tools, resources, and prompts. Use --timeout <ms> to set a custom connection timeout (default: 30000ms).

# Verify with custom timeout
npx agentinit apply --verify-mcp --timeout 30000 \
  --mcp-stdio chrome-mcp "bunx -y chrome-devtools-mcp@latest"

Rules Configuration

Apply coding rules and best practices to your AI agents using predefined templates or custom rules.

# Apply rule templates (recommended combinations)
agentinit apply --rules git,write_tests,use_linter

# Mix templates with custom rules
agentinit apply --rules git,write_docs --rule-raw "Use TypeScript strict mode"

# Load rules from a file
agentinit apply --rules-file ./project-rules.md

# Apply globally to all projects using Claude
agentinit apply --global --agent claude --rules git,write_tests

# Combine with MCP configuration
agentinit apply --rules git,use_linter --mcp-stdio context7 "npx @context7/mcp"

Available Rule Templates:

  • git - Enforce Git workflows and commit standards
  • write_docs - Require comprehensive documentation
  • use_git_worktrees - Enable parallel development with worktrees
  • use_subagents - Delegate work to specialized subagents
  • use_linter - Enforce code quality and formatting
  • write_tests - Implement test-driven development practices

Token Tracking: The apply command automatically tracks and displays token usage with color-coded output (🟒 Green ≀5k, 🟑 Yellow 5k-15k, πŸ”΄ Red >15k) and git-style diffs to help manage AI context size. Example: Rules: 101 tokens (-296) shows rule tokens with change tracking.

πŸ—οΈ Project Structure

AgentInit creates and manages these key files:

your-project/
β”œβ”€β”€ agents.md                 # Universal agent configuration
β”œβ”€β”€ CLAUDE.md                 # Claude-specific config (synced)
β”œβ”€β”€ .cursor/rules/            # Cursor rules (MDC files)
β”‚   β”œβ”€β”€ 001_workspace.mdc
β”‚   └── 002_frontend.mdc
β”œβ”€β”€ AGENTS.md                 # Simple agent instructions (alternative)
└── .windsurfrules           # Windsurf-specific config (synced)

πŸ“– Configuration

agents.md Structure

The agents.md file is the single source of truth for all agent configurations:

# Agent Configuration for MyProject

**Stack**: typescript with next.js
**Generated**: 2025-08-15
**Package Manager**: npm

## Project Context
This is a TypeScript project using Next.js...

## Development Guidelines
### Code Quality
- Write clean, maintainable code...

### Testing Strategy
- Write unit tests using Jest...

## Agent Instructions
### General Behavior
- Always analyze existing codebase...

## Sub-Agents
### Code Reviewer
**Role**: Review code for quality and security...

Supported Agents

Agent Config File Status
Claude CLAUDE.md βœ…
Cursor .cursor/rules/*.mdc or AGENTS.md βœ…
Windsurf .windsurfrules βœ…
Copilot .github/copilot.yml 🚧
Codeium .codeium/config.json 🚧

πŸ”§ Stack Detection

AgentInit automatically detects your project's technology stack:

Detection Priority:

  1. Lock files (most reliable): package-lock.json, yarn.lock, Cargo.lock, etc.
  2. Manifest files: package.json, Cargo.toml, go.mod, etc.
  3. Config files: next.config.js, vite.config.js, tsconfig.json, etc.
  4. File patterns: *.py, *.rs, *.go, etc.

Supported Stacks:

  • JavaScript/TypeScript (React, Vue, Angular, Next.js, Express)
  • Python (Django, Flask, FastAPI)
  • Rust (Cargo projects)
  • Go (Go modules)
  • Java (Maven, Gradle)

πŸ“¦ MCP Registry

AgentInit includes a curated registry of popular MCPs:

MCP Category Description
playwright testing E2E testing and browser automation
context7 documentation Fetch and analyze documentation
sequential-thinking quality Enhanced AI reasoning
agent-warden quality Prevent common AI mistakes
supabase-mcp database Supabase integration
git-mcp version-control Enhanced Git operations

πŸ“š Library API

AgentInit can be used as a library in your Node.js/TypeScript applications for programmatic MCP server verification and management.

πŸ“– Full Documentation: See src/lib/verifier/README.md for complete API reference, examples, and advanced usage.

Installation

npm install agentinit
# or
yarn add agentinit
# or
bun add agentinit

Basic Usage

import { MCPVerifier } from 'agentinit/verifier';
import { MCPServerType } from 'agentinit/types';

const verifier = new MCPVerifier();

const result = await verifier.verifyServer({
  name: 'everything',
  type: MCPServerType.STDIO,
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-everything']
});

if (result.status === 'success') {
  console.log(`βœ… Connected to ${result.server.name}`);
  console.log(`Tools: ${result.capabilities?.tools.length}`);
  console.log(`Total tokens: ${result.capabilities?.totalToolTokens}`);
}

Advanced Features

The verifier supports additional options for detailed inspection:

// Fetch resource contents and prompt templates
const result = await verifier.verifyServer(
  serverConfig,
  {
    timeout: 15000,
    includeResourceContents: true,  // Fetch actual resource data
    includePromptDetails: true,     // Fetch prompt templates
    includeTokenCounts: true        // Calculate token usage (default)
  }
);

// Access detailed tool parameters
result.capabilities?.tools.forEach(tool => {
  console.log(`\nTool: ${tool.name}`);

  if (tool.inputSchema?.properties) {
    Object.entries(tool.inputSchema.properties).forEach(([name, schema]) => {
      console.log(`  - ${name}: ${schema.type} ${schema.description || ''}`);
    });
  }
});

Submodule Imports

For better tree-shaking, import from specific submodules:

// Import specific modules
import { MCPVerifier } from 'agentinit/verifier';
import { MCPServerType } from 'agentinit/types';
import type {
  MCPServerConfig,
  MCPVerificationResult,
  MCPVerificationOptions
} from 'agentinit/types';
import { countTokens, MCPParser } from 'agentinit/utils';

Examples

Verify STDIO MCP Server

import { MCPVerifier, MCPServerType } from 'agentinit';

const verifier = new MCPVerifier(10000); // 10 second timeout

const result = await verifier.verifyServer({
  name: 'filesystem',
  type: MCPServerType.STDIO,
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem', '/workspace'],
  env: {
    NODE_ENV: 'production'
  }
});

if (result.status === 'success') {
  result.capabilities?.tools.forEach(tool => {
    const tokens = result.capabilities?.toolTokenCounts?.get(tool.name) || 0;
    console.log(`  β€’ ${tool.name} (${tokens} tokens)`);
  });
}

Verify HTTP MCP Server

import { MCPVerifier, MCPServerType } from 'agentinit';

const result = await verifier.verifyServer({
  name: 'github-api',
  type: MCPServerType.HTTP,
  url: 'https://api.example.com/mcp',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
});

Verify Multiple Servers

import { MCPVerifier, MCPServerType } from 'agentinit/verifier';

const servers = [
  {
    name: 'everything',
    type: MCPServerType.STDIO,
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-everything']
  },
  {
    name: 'api-server',
    type: MCPServerType.HTTP,
    url: 'https://api.example.com/mcp'
  }
];

const verifier = new MCPVerifier();
const results = await verifier.verifyServers(servers);

// Display formatted results
console.log(verifier.formatResults(results));

// Or process results programmatically
const successful = results.filter(r => r.status === 'success').length;
console.log(`${successful}/${results.length} servers verified`);

// Inspect tool parameters and token usage
results.forEach(result => {
  if (result.status === 'success' && result.capabilities) {
    console.log(`\n${result.server.name}:`);
    result.capabilities.tools.forEach(tool => {
      const tokens = result.capabilities?.toolTokenCounts?.get(tool.name) || 0;
      console.log(`  β€’ ${tool.name} (${tokens} tokens)`);
    });
  }
});

Count Tokens

import { countTokens } from 'agentinit/utils';

const text = 'Hello, world!';
const tokens = countTokens(text);
console.log(`Token count: ${tokens}`);

Parse MCP Configuration

import { MCPParser } from 'agentinit/utils';

const args = ['--mcp-stdio', 'test', 'node', 'server.js', '--args', 'arg1 arg2'];
const parsed = MCPParser.parseArguments(args);

console.log(parsed.servers); // Array of MCPServerConfig

API Reference

MCPVerifier

Constructor

new MCPVerifier(defaultTimeout?: number)

Methods

  • verifyServer(config: MCPServerConfig, options?: MCPVerificationOptions): Promise<MCPVerificationResult> - Verify a single MCP server
  • verifyServers(configs: MCPServerConfig[], options?: MCPVerificationOptions): Promise<MCPVerificationResult[]> - Verify multiple servers in parallel
  • formatResults(results: MCPVerificationResult[]): string - Format verification results for display

MCPVerificationOptions

interface MCPVerificationOptions {
  timeout?: number;                    // Connection timeout (ms)
  includeResourceContents?: boolean;   // Fetch resource data
  includePromptDetails?: boolean;      // Fetch prompt templates
  includeTokenCounts?: boolean;        // Calculate tokens (default: true)
}

Types

MCPServerType

enum MCPServerType {
  STDIO = 'stdio',
  HTTP = 'http',
  SSE = 'sse'
}

MCPServerConfig

interface MCPServerConfig {
  name: string;
  type: MCPServerType;

  // For STDIO servers
  command?: string;
  args?: string[];
  env?: Record<string, string>;

  // For HTTP/SSE servers
  url?: string;
  headers?: Record<string, string>;
}

MCPVerificationResult

interface MCPVerificationResult {
  server: MCPServerConfig;
  status: 'success' | 'error' | 'timeout';
  capabilities?: MCPCapabilities;
  error?: string;
  connectionTime?: number;
}

MCPCapabilities

interface MCPCapabilities {
  tools: MCPTool[];           // Available tools with input schemas
  resources: MCPResource[];   // Available resources (with optional contents)
  prompts: MCPPrompt[];       // Available prompts (with optional templates)
  serverInfo?: {
    name: string;
    version: string;
  };
  totalToolTokens?: number;         // Total token usage for all tools
  toolTokenCounts?: Map<string, number>;  // Token count per tool
}

interface MCPTool {
  name: string;
  description?: string;
  inputSchema?: any;  // JSON Schema defining parameters
}

interface MCPResource {
  uri: string;
  name?: string;
  description?: string;
  mimeType?: string;
  contents?: string | Uint8Array;  // Only if includeResourceContents is true
}

interface MCPPrompt {
  name: string;
  description?: string;
  arguments?: Array<{
    name: string;
    description?: string;
    required?: boolean;
  }>;
  template?: string;  // Only if includePromptDetails is true
}

πŸ“ Note: For detailed examples on working with tool parameters, resource contents, and prompt templates, see the full library documentation.

πŸ› οΈ Development

Building from Source

# Clone the repository
git clone <repository-url>
cd agentinit

# Install dependencies
bun install

# Build the project
bun run build

# Run locally
node dist/index.js --help

Project Structure

src/
β”œβ”€β”€ commands/          # CLI commands
β”‚   β”œβ”€β”€ init.ts       # Project initialization
β”‚   β”œβ”€β”€ detect.ts     # Stack detection
β”‚   β”œβ”€β”€ sync.ts       # Configuration sync
β”‚   └── mcp.ts        # MCP management
β”œβ”€β”€ core/             # Core functionality
β”‚   β”œβ”€β”€ agentDetector.ts    # Agent detection
β”‚   β”œβ”€β”€ stackDetector.ts    # Stack analysis
β”‚   β”œβ”€β”€ templateEngine.ts   # Template processing
β”‚   └── propagator.ts       # Config sync engine
β”œβ”€β”€ registry/         # MCP registry
β”œβ”€β”€ utils/            # Utilities
└── types/            # TypeScript definitions

🀝 Contributing

We welcome contributions! Please see our contributing guidelines for details.

πŸ“„ License

MIT License - see LICENSE file for details.

πŸ”— Links


AgentInit - Unify your AI agent configurations, amplify your development workflow.

About

Universal CLI for managing AI coding agent configurations. Unify Claude Code, Cursor, Windsurf agents configs with MCP management

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Contributors 3

  •  
  •  
  •