agents unify

agents unify centralizes agent configuration into .agents. By default it uses global mode and consolidates your home-level skills and agents into ~/.agents.

aiblueprint agents unify
aiblueprint agents unify -i
aiblueprint agents unify global
aiblueprint agents unify projects
aiblueprint agents unify projects --agents-md --skills --rules
aiblueprint agents unify repository
npx aiblueprint-cli@latest agents config unify sessions

Modes

Mode	Default folder	What it does
global	$HOME	Imports global instruction files, skills, and agents from Claude, Codex, Cursor, OpenCode, and Factory paths into ~/.agents, then links tool paths back to the shared source.
projects	Current working directory	Alias for repository mode. Imports project-local instruction files, skills, agents, rules, and memories into .agents, creates only the needed category folders, links .claude/rules back to .agents/rules, creates AGENTS.md, and symlinks CLAUDE.md to it.
repository	Current working directory	Same behavior as projects. Kept as the explicit technical name for repo-local configuration.

Use --folder <path> with any mode to target a specific root.

Category Selection

By default, agents unify runs every category supported by the selected mode. Use -i or --interactive to choose categories from a prompt:

npx aiblueprint-cli@latest agents unify projects -i

Use flags for non-interactive runs:

Flag	Category
--agents-md	Instruction files like .claude/CLAUDE.md, .codex/AGENTS.md, and .cursor/AGENTS.md
--skills	Skills folders
--agents	Markdown agents
--rules	Repository rules and memories

When one or more category flags are provided, only those categories run. The --rules category applies to projects and repository mode.

Projects Mode

Projects mode is designed for repositories that already have tool-specific configuration in .claude, .codex, .cursor, or .agents.

npx aiblueprint-cli@latest agents unify projects

It will:

1. Move .claude/CLAUDE.md, .codex/AGENTS.md, and .cursor/AGENTS.md into .agents/AGENTS.md, preserving conflicts with a suffixed copy.
2. Move reusable skills into .agents/skills.
3. Move Markdown agents into .agents/agents.
4. Move rules and memory notes into .agents/rules.
5. Rewrite copied text references from tool-specific paths like .claude/rules or .cursor/agents to .agents/rules and .agents/agents.
6. Create compatibility symlinks so existing tools keep reading the shared folders.
7. Generate an AGENTS.md rules index and make CLAUDE.md point to it.

If a project has no skills, agents, or rules, the command does not create empty .agents/skills, .agents/agents, or .agents/rules folders. Project mode also does not create .codex from scratch; Codex reads the shared .agents project context.

Global Mode

Global mode preserves the original behavior.

npx aiblueprint-cli@latest agents unify global

It will:

1. Import .claude/CLAUDE.md, .codex/AGENTS.md, .cursor/AGENTS.md, skills, and agents into ~/.agents.
2. Skip duplicates and rename files when there is a conflict.
3. Create symlinks back so existing tools keep working.
4. Back up the source before moving anything.
5. Render shared agents into Codex TOML format.

Output summary

After running, the CLI reports per category:

• Imported count
• Duplicates skipped
• Renamed files
• Symlinks created
• Already linked (skipped)
• Source backups created
• Project rules indexed, when projects mode is used

Project-mode source backups are stored in the global AIBlueprint backup root, not inside the repository. The backup folder name includes the project path with slashes replaced, so a project backup is easy to identify and restore later.

Session Unify

agents config unify sessions scans saved configs and backups, then imports Claude, Codex, and shared agent session roots into the current folders. It keeps current files, skips identical duplicates, and preserves conflicts with a source suffix instead of overwriting session history.

Why centralize

A single .agents source of truth means your skills, agents, and project rules work consistently across Claude Code, Codex, Cursor, and other linked tools. To render only the Codex agents without a full unify, use agents codex-agents.