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.
- π€ 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
# Install AgentInit globally
npm install -g agentinit
# 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
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 toolslibrary
- Libraries and packagesfullstack
- Full-stack applicationsmobile
- Mobile applications
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
Sync agents.md with agent-specific configuration files.
agentinit sync # Sync configurations
agentinit sync --dry-run # Preview changes
agentinit sync --backup # Create backups
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
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.
Apply configurations including MCP server setup.
# 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"
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 standardswrite_docs
- Require comprehensive documentationuse_git_worktrees
- Enable parallel development with worktreesuse_subagents
- Delegate work to specialized subagentsuse_linter
- Enforce code quality and formattingwrite_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.
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)
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...
Agent | Config File | Status |
---|---|---|
Claude | CLAUDE.md |
β |
Cursor | .cursor/rules/*.mdc or AGENTS.md |
β |
Windsurf | .windsurfrules |
β |
Copilot | .github/copilot.yml |
π§ |
Codeium | .codeium/config.json |
π§ |
AgentInit automatically detects your project's technology stack:
Detection Priority:
- Lock files (most reliable):
package-lock.json
,yarn.lock
,Cargo.lock
, etc. - Manifest files:
package.json
,Cargo.toml
,go.mod
, etc. - Config files:
next.config.js
,vite.config.js
,tsconfig.json
, etc. - 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)
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 |
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.
npm install agentinit
# or
yarn add agentinit
# or
bun add agentinit
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}`);
}
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 || ''}`);
});
}
});
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';
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)`);
});
}
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'
}
});
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)`);
});
}
});
import { countTokens } from 'agentinit/utils';
const text = 'Hello, world!';
const tokens = countTokens(text);
console.log(`Token count: ${tokens}`);
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
Constructor
new MCPVerifier(defaultTimeout?: number)
Methods
verifyServer(config: MCPServerConfig, options?: MCPVerificationOptions): Promise<MCPVerificationResult>
- Verify a single MCP serververifyServers(configs: MCPServerConfig[], options?: MCPVerificationOptions): Promise<MCPVerificationResult[]>
- Verify multiple servers in parallelformatResults(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)
}
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.
# 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
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
We welcome contributions! Please see our contributing guidelines for details.
MIT License - see LICENSE file for details.
AgentInit - Unify your AI agent configurations, amplify your development workflow.