agents-cli

One CLI for all your AI agent configurations

Sync skills, commands, hooks, and AGENTS.md across Cursor, Claude Code, Gemini CLI, Codex, Windsurf, and more.

🎯 The Problem

You have configurations scattered across different AI tools:

~/.cursor/skills/          ← Cursor skills
~/.claude/skills/          ← Claude skills
~/.gemini/skills/          ← Gemini skills
~/.cursor/commands/        ← Cursor commands
~/.claude/commands/        ← Claude commands
~/.cursor/hooks/           ← Cursor hooks
~/.claude/CLAUDE.md        ← Claude agent file
~/.codex/AGENTS.md         ← Codex agent file

Copying manually? Tedious. Updating? Copy again everywhere.

✨ The Solution

One source of truth. Add once, sync everywhere.

~/.agents/                     ← YOUR SINGLE CONFIG HOME
├── skills/store/              ← All your skills
├── commands/store/            ← All your commands
├── hooks/                     ← Your hooks (hooks.json + file/)
├── AGENTS.md                  ← Your global agent instructions
└── config.json                ← Registry of sources & targets

agents skills target add cursor
agents skills target add claude
agents skills sync           # Done! Skills synced everywhere

📦 Installation

Prerequisites

• Bun runtime
• Git (for remote sources)

Install via Bun

bun install -g agents-cli

Install from Source

git clone https://github.com/dhruvwill/agents-cli.git
cd agents-cli
bun install
bun link

Verify

agents --version
agents --help

🚀 Quick Start

# 1. Add a skill from GitHub
agents skills source add https://github.com/vercel-labs/agent-skills --remote

# 2. Add targets (paths auto-detected)
agents skills target add cursor
agents skills target add claude

# 3. Sync!
agents skills sync

📐 Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         SOURCES                                  │
│        GitHub • GitLab • Bitbucket • Local Folders              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼  agents <module> source add
┌─────────────────────────────────────────────────────────────────┐
│                       ~/.agents/                                 │
│                                                                  │
│  skills/store/    commands/store/    hooks/    AGENTS.md        │
│                                                                  │
│                    ⬆ Single Source of Truth ⬆                   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼  agents <module> sync
      ┌───────────────┬───────────────┬───────────────┐
      ▼               ▼               ▼               ▼
┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
│  Cursor  │   │  Claude  │   │  Gemini  │   │  Codex   │
│ ~/.cursor│   │ ~/.claude│   │ ~/.gemini│   │ ~/.codex │
└──────────┘   └──────────┘   └──────────┘   └──────────┘

📚 Modules

🧠 Skills

Sync AI skills (prompt files, tool definitions) across tools.

| Command | Description | |---------|-------------| | agents skills status | Overview of skills & targets | | agents skills source add <url> --remote | Add from Git repo | | agents skills source add <path> --local | Add from local folder | | agents skills source list | List all sources | | agents skills target add <name> | Add a target | | agents skills target list | List targets | | agents skills sync | Sync to all targets | | agents skills update | Pull latest from remotes |

Supported targets: cursor, claude, gemini, vscode, opencode, windsurf, antigravity

📝 Commands

Sync command files (.md slash commands) across tools.

| Command | Description | |---------|-------------| | agents commands status | Overview | | agents commands source add <path> --local | Add local folder | | agents commands target add <name> | Add target | | agents commands sync | Rebuild store & sync |

Supported targets: claude, cursor, gemini, factory, codex, opencode, windsurf, antigravity

🪝 Hooks

Sync hooks (hooks.json + scripts) to Claude and Factory.

| Command | Description | |---------|-------------| | agents hooks status | Show status | | agents hooks target add <name> | Add target | | agents hooks sync | Sync to targets |

Supported targets: claude, factory, cursor

Note: Cursor gets special handling (symlinks hooks.json and hooks/ separately to avoid touching other .cursor files)

📄 AGENTS.md

Sync your global agent instructions (~/.agents/AGENTS.md) to each tool's expected location.

| Command | Description | |---------|-------------| | agents agents-md status | Show status | | agents agents-md target add <name> | Add target | | agents agents-md target available | Show all targets | | agents agents-md sync | Sync to targets |

Target mappings: | Tool | Target Path | |------|-------------| | Claude | ~/.claude/CLAUDE.md | | Codex | ~/.codex/AGENTS.md | | Gemini | ~/.gemini/GEMINI.md | | Cursor | ~/.cursor/rules/global--agents.mdc | | Windsurf | ~/.windsurf/AGENTS.md | | Factory | ~/.factory/AGENTS.md |

🔗 How Syncing Works

Symlinks (not copies)

All modules use symlinks instead of file copies:

~/.agents/skills/store/my-skill/  →  ~/.cursor/skills/my-skill/
                                  →  ~/.claude/skills/my-skill/
                                  →  ~/.gemini/skills/my-skill/

Benefits:

• ✅ Edit once, reflected everywhere
• ✅ No sync needed after local edits
• ✅ Minimal disk usage

On Windows, we use junctions for directories (no admin required)

🛡️ Safety Guarantees

All sync operations are additive only:

| Module | What it touches | What it NEVER touches | |--------|-----------------|----------------------| | Skills | ~/.cursor/skills/ | Other .cursor files | | Commands | ~/.cursor/commands/ | Other .cursor files | | Hooks | ~/.cursor/hooks.json, ~/.cursor/hooks/ | Other .cursor files | | AGENTS.md | Specific file only | Other files |

🗂️ Directory Structure

~/.agents/
├── config.json                    # All sources & targets
├── AGENTS.md                      # Your global agent file
├── skills/
│   └── store/
│       ├── react-best-practices/  # Skill folders
│       └── my-custom-skill/
├── commands/
│   ├── sources/                   # Raw command sources
│   ├── store/                     # Flattened symlinks
│   └── aliases.json               # Conflict renames
└── hooks/
    ├── hooks.json                 # Hook definitions
    └── file/                      # Hook scripts

🎮 Interactive Mode

Run any module without arguments for interactive prompts:

agents skills        # Interactive skills menu
agents commands      # Interactive commands menu
agents hooks         # Interactive hooks menu
agents agents-md     # Interactive AGENTS.md menu

🧪 Examples

Add Skills from GitHub

# Full repo
agents skills source add https://github.com/vercel-labs/agent-skills --remote

# Specific subdirectory
agents skills source add https://github.com/owner/repo/tree/main/skills/react --remote

# With custom name
agents skills source add https://github.com/owner/repo --remote --name my-skill

Add Local Commands

agents commands source add ./my-commands --local
agents commands target add cursor
agents commands sync

Setup AGENTS.md

# Create your agent file
echo "# My Global Rules\n- Use TypeScript\n- Write tests" > ~/.agents/AGENTS.md

# Sync to all tools
agents agents-md target add claude
agents agents-md target add codex
agents agents-md sync

❓ FAQ

How is this different from dot-agents?

agents-cli is inspired by dot-agents but focused on simplicity:

• Single binary, no complex dependencies
• Symlinks instead of hard links where possible
• Unified management for skills, commands, hooks, and AGENTS.md

Do I need admin rights on Windows?

No! We use junctions for directory symlinks, which don't require elevation.

Can I add custom targets?

Yes! Specify the path manually:

agents skills target add mytool ~/path/to/mytool/skills

🔧 Development

git clone https://github.com/dhruvwill/agents-cli.git
cd agents-cli
bun install
bun run src/cli.ts --help

📄 License

MIT