Write your agents once.
Use them everywhere.

Overview

If you use more than one AI coding tool, you know the friction. Cursor expects subagents under .cursor/agents, Claude expects.claude/, and Copilot splits workspace files under .github/ from global files under ~/.copilot/. None of them talk to each other by default.

Agentloom gives you a single .agents/ directory where you define everything once in plain markdown and JSON. Run agentloom sync and your definitions are written to every tool in its native format. Switch tools, share agents with your team, import from GitHub — all without lock-in.

Getting Started

One command to initialize. Agentloom detects your existing provider configs, migrates them into the canonical format, and syncs everything back out.

After initialization, agentloom sync is one-way: it reads from .agents/ and writes provider-native outputs. Rerun agentloom init only when you want to re-import provider state into canonical config.

$ npx agentloom init

$ npx agentloom add farnoodma/agents

$ npx agentloom sync

$ npm i -g agentloom

Canonical Layout

All definitions live in a .agents/ directory. Version-controlled, diffable, reviewable. Global scope uses ~/.agents with the same structure.

.agents/
  agents/
    reviewer.md           # Agent definitions (markdown + YAML frontmatter)
    debugger.md
  commands/
    review.md             # Command prompts
    ship.md
  rules/
    always-test.md        # Managed instruction rules
    enforce-logs.md
  skills/
    reviewing/
      SKILL.md            # Skill entry point
      references/         # Supporting files
      assets/
    debugging/
      SKILL.md
  mcp.json                # MCP server configurations
  agents.lock.json        # Lock file for synced sources
  settings.local.json     # Local overrides (gitignored)

Source path resolution is additive and priority-ordered, so Agentloom can import repositories that use different directory conventions: for agents it checks .agents/agents then agents/, for commands .agents/commands then commands/ then prompts/, then provider fallbacks from .github/prompts/ and .gemini/commands/, for rules .agents/rules then rules/, for skills .agents/skills then skills/ then a root SKILL.md fallback, then root <name>/SKILL.md directories.

Commands

agentloom agent <add|list|delete|find|update|sync>
agentloom command <add|list|delete|find|update|sync>
agentloom mcp <add|list|delete|find|update|sync>
agentloom rule <add|list|delete|find|update|sync>
agentloom skill <add|list|delete|find|update|sync>

# Add a server by command
$ agentloom mcp server add browser-tools --command npx --arg browser-tools-mcp

# Add a server by URL
$ agentloom mcp server add my-server --url https://example.com/mcp

# List configured servers
$ agentloom mcp server list

# Remove a server
$ agentloom mcp server delete browser-tools

# Import everything from a repo
$ agentloom add farnoodma/agents

# Import only a specific agent
$ agentloom agent add farnoodma/agents --agents issue-creator

# Import a specific command
$ agentloom command add farnoodma/agents --commands review

# Import a specific MCP server
$ agentloom mcp add farnoodma/agents --mcps browser

# Import a specific rule
$ agentloom rule add farnoodma/agents --rules always-test

# Import a specific skill
$ agentloom skill add farnoodma/agents --skills pr-review

# Remove everything from a source
$ agentloom delete farnoodma/agents

# Remove multiple commands by name
$ agentloom command delete review audit

Agent Schema

Agents are markdown files with YAML frontmatter. Use the frontmatter for metadata and provider-specific overrides. The body is your agent's system prompt.

---
name: code-reviewer
description: Review changes and report issues.
claude:
  model: sonnet
codex:
  model: gpt-5-codex
  reasoningEffort: medium
  webSearch: true
---

You are a strict code reviewer. Check for:
- Security vulnerabilities
- Performance issues
- Naming conventions
- Missing error handling

Provider-specific blocks (claude:, codex:, etc.) let you tune model, reasoning effort, and other settings per tool without duplicating the prompt.

Command Schema

Canonical commands are markdown files. Frontmatter is optional. When present, provider-specific command config can be nested per provider.

---
copilot:
  description: Review current changes
  agent: agent
  tools:
    - codebase
  model: gpt-5
  argument-hint: "<scope>"
---

# /review

Review active changes with scope $ARGUMENTS.

• Provider configs follow the same pattern as agents.
• Omit a provider key for default behavior, add provider: { ... } for provider-specific overrides, or set provider: false to disable output for a provider.
• Provider-specific frontmatter keys are passed through as-is to provider outputs.
• Canonical command bodies can use $ARGUMENTS; provider-specific placeholder translation is applied during sync (for example, Copilot receives $${input:args} and Gemini receives {{args}}).

Rule Schema

Canonical rules live in .agents/rules/*.md. Rules require frontmatter.name. Extra frontmatter keys are preserved, but used only for Cursor rule file rendering.

---
name: Always run checks
description: Require checks before shipping
alwaysApply: true
globs:
  - "**/*.ts"
---

Before finishing any change, run project checks and include the result.

• Rule IDs come from canonical filename stems (for example always-run-checks.md).
• Managed instruction blocks use markers like <!-- agentloom:always-run-checks:start -->.
• Cursor receives provider-native files at .cursor/rules/<rule-id>.mdc.

MCP Schema

MCP servers are defined in mcp.json. Each server has a base configuration and optional per-provider overrides. Set a provider to false to exclude a server from that tool.

{
  "version": 1,
  "mcpServers": {
    "browser": {
      "base": {
        "command": "npx",
        "args": ["browser-tools-mcp"]
      },
      "providers": {
        "codex": {
          "args": ["browser-tools-mcp", "--codex"]
        },
        "gemini": false
      }
    }
  }
}

Supported Providers

Agentloom syncs your definitions to every major AI coding tool. Rule sync writes managed instruction blocks plus provider-native Cursor rules.

For Codex, agentloom sync writes role-based multi-agent config following official Codex multi-agent guidance. Codex commands are always written to global prompts under ~/.codex/prompts.

Cursor provider sync writes subagents to .cursor/agents/*.md. Gemini command sync writes TOML commands to .gemini/commands/*.toml. Global Copilot sync writes discovery targets under ~/.copilot/*.

Rule sync behavior: local runs always update managed blocks in AGENTS.md; local Cursor also writes .cursor/rules/*.mdc. Global Copilot also updates VS Code chat.instructionsFilesLocations with ~/.copilot/copilot-instructions.md. Global Claude MCP user scope is not file-synced by Agentloom; only project .mcp.json is managed.

Telemetry

Successful GitHub-based imports send anonymous telemetry to power the public directory and leaderboard. No personal data is collected.

• Only GitHub sources are tracked — local path imports are never sent.
• Tracked entities: agents, skills, commands, rules, and MCP servers.
• Opt out: AGENTLOOM_DISABLE_TELEMETRY=1
• Override endpoint: AGENTLOOM_TELEMETRY_ENDPOINT=https://...

Directory

The Agentloom Directory surfaces the most popular agents, skills, commands, rules, and MCP servers the community is importing. Browse trending setups, discover what other teams are using, and add anything to your project in one command.

Scope Resolution

Agentloom supports both local (project) and global (user) scopes.

• If .agents/ exists in the current directory, you'll be prompted to choose scope.
• In non-interactive mode, local scope is selected when .agents/ exists.
• Otherwise global scope (~/.agents) is used.
• Force scope with --local or --global.

Environment Variables