omniagent

One source of truth for agent config across Claude, Codex, Gemini, and Copilot (and any other agent)

Define canonical agent files once in agents/, then run sync to compile target-specific outputs.

• Teams can keep one shared agent configuration while each teammate uses their preferred CLI.
• Agent enthusiasts can try out the newest agents, and switch back, without manually porting all their config.

Quickstart

Author once in agents/, sync everywhere.

Subagents example:

# ./agents/agents/release-helper.md

---

name: release-helper
description: "Help draft release plans and checklists."

---

Draft a release plan with milestones and owners.

Codex does not support subagents. Omniagent converts the canonical file into Codex's skill format (and the equivalent format for other supported CLIs).

After sync, outputs include:

.claude/
  agents/
    release-helper.md
.codex/
  skills/
    release-helper/
      SKILL.md

How It Works

1. Author canonical sources in agents/ (and optional repo AGENTS.md).
2. Run omniagent sync.
3. Omniagent writes target-specific files, converting unsupported surfaces when needed.

Common Commands

# Sync all supported agent CLIs installed on your system
npx omniagent@latest sync

# Sync specific targets
npx omniagent@latest sync --only claude,codex

# Skip a target for this run
npx omniagent@latest sync --skip codex

# Use a non-default agents directory
npx omniagent@latest sync --agentsDir ./my-custom-agents

# Show local-only overrides and exit
npx omniagent@latest sync --list-local

# Apply a sync profile (see docs/profiles.md)
npx omniagent@latest sync --profile code-reviewer

# Show usage limits for installed usage-capable agents
omniagent usage
omniagent usage codex
omniagent usage --only claude,codex
omniagent usage --window=weekly
omniagent usage --sort=reset
omniagent usage --sort=left
omniagent usage codex --window=5h
omniagent usage --timeout=45
omniagent usage --agentsDir ./my-custom-agents
omniagent usage codex --json
omniagent usage codex --debug

# Shim mode (no subcommand)
omniagent --agent codex
omniagent -p "Summarize this repo" --agent codex --output json

usage supports Codex, Claude, and Gemini in v1. Copilot is not supported for usage extraction yet. Usage extraction may launch agent TUIs and may incur cost if an agent reads repo context or instructions on startup; omniagent uses cheap/minimal launch settings where possible. Usage extraction times out after 30 seconds unless the target config defines a target-specific timeout; built-in TUI probes may use longer defaults. Some CLIs require session-scoped setup flags to inspect usage, such as Gemini's --skip-trust; omniagent does not complete auth or onboarding prompts for you. Pass --timeout=<seconds> to override the per-agent timeout for the current run.

Local Overrides (.local)

Use .local files for personal variants that should not become team defaults.

agents/
  AGENTS.local.md    # opinionated personal override
  commands/
    deploy.md        # committed to git
    deploy.local.md  # opinionated personal override
  skills/
    ppt/
      SKILL.md       # committed to git
      SKILL.local.md # opinionated personal override

./agents/.local/ is also supported. This can be used for libraries for your personal tooling, that should not be shared with the team:

agents/
  .local/
    commands/my-personal-command.md
    skills/my-personal-skill/SKILL.md

If a .local item matches a shared item name, the local item wins for your sync run. Generated outputs do not keep the .local suffix.

Use --list-local to see active local items, or --exclude-local to ignore them for a run.

Example .gitignore entries:

agents/.local/
agents/**/*.local*

Sync Profiles

Profiles let each dev pick a named, checked-in filter that sync applies to the shared agents/ directory — so a ten-person team can share one source of truth while each member opts in to exactly the skills, subagents, commands, and targets they want.

// agents/profiles/code-reviewer.json
{
  "description": "Focused setup for PR reviews",
  "extends": "base",
  "targets": { "claude": { "enabled": true }, "codex": { "enabled": true } },
  "enable": {
    "skills":    ["code-review", "security-review"],
    "subagents": ["reviewer"],
    "commands":  ["review", "diff-summary"]
  },
  "variables": { "REVIEW_STYLE": "terse" }
}

omniagent sync                                   # uses agents/profiles/default.json when present
omniagent sync --profile code-reviewer
omniagent sync --profile base,code-reviewer     # merge multiple (later wins)
omniagent sync --var REVIEW_STYLE=thorough      # override a variable from the CLI

Profiles support extends chains, .local overrides (personal, gitignored), glob-based enable/disable lists, per-target toggles, and template variables. Individual skills, subagents, and commands can also set frontmatter enabled: false to stay hidden by default until a profile opts them in. Discover and validate profiles with omniagent profiles, omniagent profiles init <name>, omniagent profiles show <name>, and omniagent profiles validate. Use omniagent profiles init <name>.local to create a personal local profile override.

See docs/profiles.md for the full schema, resolution order, and examples.

Basic Templating

Use <agents ...> blocks when some text should render only for specific targets.

Shared guidance for all targets.

<agents claude,codex>
Extra instructions only for Claude and Codex.
</agents>

For advanced templating and dynamic scripts (<nodejs>, <shell>), see docs/templating.md.

Agent CLI Shim

Omniagent provides a CLI shim (omniagent without a subcommand) for working with agent CLIs via a unified interface.

This can be useful for CI/CD and shell scripts, while maintaining full portability between agents:

# code-review.sh
#!/usr/bin/env bash
set -euo pipefail
agent="${1:-claude}"

omniagent -p "Perform comprehensive code review for this branch against main" --agent "$agent"

Example usage:

./code-review.sh
./code-review.sh codex

Documentation

• Docs index: docs/README.md
• Getting started: docs/getting-started.md
• Sync basics: docs/sync-basics.md
• CLI shim details: docs/cli-shim.md
• Custom targets (custom agents): docs/custom-targets.md
• Local overrides: docs/local-overrides.md
• Sync profiles: docs/profiles.md
• Templating and dynamic scripts: docs/templating.md
• Command reference: docs/reference.md
• Troubleshooting: docs/troubleshooting.md

Requirements

• Node.js 18+

Contributing

Development and test workflows are documented in CONTRIBUTING.md.