https://github.com/ahmet-cetinkaya/agent-ctrl
A CLI tool for managing AI agent configurations using a standard directory-based pattern. Supports rules, skills, agents, and MCP servers.
https://github.com/ahmet-cetinkaya/agent-ctrl
ai-agents bun cli mcp npm typescript
Last synced: 2 months ago
JSON representation
A CLI tool for managing AI agent configurations using a standard directory-based pattern. Supports rules, skills, agents, and MCP servers.
- Host: GitHub
- URL: https://github.com/ahmet-cetinkaya/agent-ctrl
- Owner: ahmet-cetinkaya
- License: gpl-3.0
- Created: 2026-02-10T10:37:54.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-05T16:19:27.000Z (3 months ago)
- Last Synced: 2026-04-05T18:22:11.722Z (3 months ago)
- Topics: ai-agents, bun, cli, mcp, npm, typescript
- Language: TypeScript
- Homepage:
- Size: 642 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# agent-ctrl
[](./LICENSE)
[](https://www.npmjs.com/package/agent-ctrl-cli)
[](https://github.com/ahmet-cetinkaya/agent-ctrl/stargazers)
[](https://github.com/ahmet-cetinkaya/agent-ctrl/network/members)
[](https://github.com/ahmet-cetinkaya/agent-ctrl/graphs/contributors)
[](https://github.com/ahmet-cetinkaya/agent-ctrl/issues)
[](https://ahmetcetinkaya.me/donate)
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:**
[](https://www.npmjs.com/package/agent-ctrl-cli)
[](https://github.com/ahmet-cetinkaya/agent-ctrl/releases)
**Supported platforms:**
**Core Techs:**
[](https://bun.sh)
[](https://www.typescriptlang.org)
---
## 🚀 Quick Start
### Installation
```bash
# Install from npm (global)
npm install -g agent-ctrl-cli
# Run CLI
agent-ctrl --help
```
### Basic Usage
```bash
# 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
```
---
## 🛠Usage & Commands
`agent-ctrl` provides a comprehensive suite of commands to manage your AI agent's artifacts.
### Global Configuration
- `init [path]` - Initialize the global configuration structure (default: `~/.agent-ctrl`).
- `apply ` - Sync local artifacts to a platform's native configuration.
### Artifact Management
#### Rules (`rules/`)
Modular behavioral guidelines in Markdown.
- `agent-ctrl rule ls` - List all rules.
#### Skills (`skills/`)
Capabilities following the `SKILL.md` standard.
- `agent-ctrl skill ls` - List installed skills.
- `agent-ctrl skill add ` - Install a skill (supports `skillsmp:`).
- `agent-ctrl skill search ` - Search for skills on SkillsMP.
- `agent-ctrl skill sync` - Synchronize skills catalog.
- `agent-ctrl skill update ` - Update an installed skill.
- `agent-ctrl skill rm ` - Remove a skill.
#### Commands (`commands/`)
Grouped command prompts or scripts (mapped to skills for Codex).
- `agent-ctrl command ls` - List available commands.
#### Agents (`agents/`)
Agent personas and identity definitions.
- `agent-ctrl agent ls` - List agent personas.
#### MCP Configuration (`mcps/`)
- `agent-ctrl mcp ls` - List configured MCP servers.
- `agent-ctrl mcp add ` - Add an MCP server (supports `smithery:`).
- `agent-ctrl mcp search ` - Search for MCP servers on Smithery.
- `agent-ctrl mcp sync` - Synchronize MCP servers catalog.
- `agent-ctrl mcp update ` - Update a configured MCP server.
- `agent-ctrl mcp rm ` - Remove an MCP server.
---
## 📂 Project Structure
`agent-ctrl` enforces a **Convention over Configuration** pattern. The directory structure IS your agent's configuration.
```text
~/.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
├── mcps/ # MCP server configurations
│ └── filesystem/
│ └── MCP.json
└── .env # Optional API credentials for catalog access
```
**Note:** You can also use project-scoped configuration by placing `.agent-ctrl/` in your project directory.
---
## 🛠Development
**Prerequisites:** [Bun](https://bun.sh) (latest LTS), TypeScript 5.0+
```bash
# 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](./docs/DEVELOPMENT.md)**.
---
## 📚 Documentation
For detailed documentation, see **[docs/README.md](./docs/README.md)**.
---
## 📄 License
This project is licensed under the **GNU General Public License v3.0** - see the [LICENSE](LICENSE) file for details.