agent-ctrl

A centralized CLI tool for managing AI agent configurations using a standard directory-based configuration pattern. Define agent behavior through rules, skills, agents, commands, and MCP servers in a structured, shareable way that works across multiple AI platforms.

Download:

Supported platforms:

Core Techs:

# Install from npm (global)
npm install -g agent-ctrl-cli

# Run CLI
agent-ctrl --help

# 1. Initialize the global configuration structure (default: ~/.agent-ctrl)
agent-ctrl init

# 2. Search and add a skill from SkillsMP marketplace
agent-ctrl skill search code-review
agent-ctrl skill add skillsmp:code-review

# 3. Apply your configuration to a supported platform
agent-ctrl apply claude

agent-ctrl provides a comprehensive suite of commands to manage your AI agent's artifacts.

• init [path] - Initialize the global configuration structure (default: ~/.agent-ctrl).
• apply <platform> - Sync local artifacts to a platform's native configuration.

Modular behavioral guidelines in Markdown.

• agent-ctrl rule ls - List all rules.

Capabilities following the SKILL.md standard.

• agent-ctrl skill ls - List installed skills.
• agent-ctrl skill add <id> - Install a skill (supports skillsmp:<id>).
• agent-ctrl skill search <query> - Search for skills on SkillsMP.
• agent-ctrl skill sync - Synchronize skills catalog.
• agent-ctrl skill update <id> - Update an installed skill.
• agent-ctrl skill rm <id> - Remove a skill.

Grouped command prompts or scripts (mapped to skills for Codex).

• agent-ctrl command ls - List available commands.

Agent personas and identity definitions.

• agent-ctrl agent ls - List agent personas.

• agent-ctrl mcp ls - List configured MCP servers.
• agent-ctrl mcp add <id> - Add an MCP server (supports smithery:<id>).
• agent-ctrl mcp search <query> - Search for MCP servers on Smithery.
• agent-ctrl mcp sync - Synchronize MCP servers catalog.
• agent-ctrl mcp update <id> - Update a configured MCP server.
• agent-ctrl mcp rm <id> - Remove an MCP server.

Named bundles of artifacts applied together to a platform.

• agent-ctrl profile new <name> - Create a new profile directory with optional display metadata.
• agent-ctrl profile list - List profiles, grouped by category with description and tags.
• agent-ctrl profile apply [platform] [profiles...] - Apply one or more profiles to a platform.

Add an optional profile.yaml at the root of a profile directory to give it display metadata. The first tag is treated as its category — profiles are grouped by category when listed or picked interactively (profiles without a profile.yaml, or without tags, are grouped under Uncategorized):

name: Machine Learning
description: "Machine learning / AI — agents and skills for model training, MLOps, and applied ML."
tags:
  - ai
  - training
  - mlops
  - pytorch

Place a settings/<platform>/ directory in your project to apply files that only one platform should receive. During agent-ctrl apply <platform>, the contents of the matching settings/<platform>/ directory are copied into that platform's native configuration directory after the standard artifacts are synced.

settings/
├── claude/          # Applied only when running: agent-ctrl apply claude
│   └── config.json
└── gemini/          # Applied only when running: agent-ctrl apply gemini
    └── settings.json

Key behavior:

• Opt-in: Projects without a settings/ directory are unaffected.
• Platform-scoped: Only the directory matching the applied platform is copied; others are ignored.
• Override semantics: Platform-specific files completely replace existing files (no merge, no backups — Git provides history).
• Validation: Directory names must match a supported platform (claude, gemini, cursor, codex, qwen, windsurf, opencode, kilo, forgecode, antigravity). Invalid names are skipped with a warning.
• Verbose mode: agent-ctrl apply <platform> --verbose prints a settings discovery summary.

agent-ctrl enforces a Convention over Configuration pattern. The directory structure IS your agent's configuration.

~/.agent-ctrl/              # Global configuration root (default)
├── rules/                  # Modular behavioral rules (Markdown)
│   ├── coding-style.md
│   └── security.md
├── skills/                 # Capabilities (SKILL.md standard)
│   └── git-workflow/
│       └── SKILL.md
├── commands/               # Command prompts (Markdown/Scripts)
│   ├── dev/
│   │   └── fix-lint.md
│   └── explain.md
├── agents/                 # Agent personas
│   └── architect.md
├── profiles/               # Named bundles applied via `apply --profile <name>`
│   └── backend/
│       └── profile.yaml   # Optional: display metadata (name, description, tags)
├── mcps/                   # MCP server configurations
│   └── filesystem/
│       └── MCP.json
├── settings/               # Platform-specific files, copied as-is (see below)
│   └── claude/
└── .env                    # Optional API credentials for catalog access

Note: You can also use project-scoped configuration by placing .agent-ctrl/ in your project directory. To ship files that only a specific platform should receive, add a project-level settings/<platform>/ directory (see Platform-Specific Settings).

Prerequisites: Bun (latest LTS), TypeScript 5.0+

# Clone and install
git clone https://github.com/ahmet-cetinkaya/agent-ctrl.git
cd agent-ctrl
bun install

# Common tasks
bun run dev          # Run in development mode
bun run build        # Build to dist/
bun test             # Run tests

For detailed development workflows, see Development.

For detailed documentation, see docs/README.md.

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.