omnid

Every AI developer struggles to sync, move, and trace agent configuration across machines and tools. MCP in five JSON files. Rules duplicated in CLAUDE.md, .cursor/rules, and AGENTS.md. New laptop = copy-paste with no idea what's stale.

One folder to sync, move, and trace your whole AI agent setup — MCP, rules, instructions, and skills.

omnid owns ~/.config/omni/. One source of truth → compiled, linked, and pushed where each agent expects it. Non-destructive MCP stub — your other servers stay. Drift tracked in .sync-state.json.

• Add MCP once, not five times
• Write rules once → .mdc, CLAUDE.md, AGENTS.md, etc.
• Sync when changed. Not every run.

Contents

• Quick start
• Install
• The problem
• Your whole setup, one folder
• Move your setup
• Trace drift
• Why omnid
• Supported agents
• Commands
• Config
• How it works
• Troubleshooting
• Development
• License

Start here

npx omnid

Open your coding app. Done.

Want a tool inside your agent? Run omnid add server.

Install for good: npm install -g omnid

Example (first run)

omnid
─────
Made ~/.config/omni/
Synced  cursor, claude_code

Next: open Cursor. omnid is ready.
      (no tools yet — run: omnid add server)

OMNID_NONINTERACTIVE=1 skips prompts on omnid add server when you pass --preset or --name + --command.

Install

npm (easiest if you have Node.js):

npx omnid                  # try without installing
npm install -g omnid       # install globally

See omnid on npm.

Binaries — GitHub Releases (SHA256 checksum sidecars included)

# Linux x86_64
curl -fsSL https://github.com/xb3sox/omnid/releases/latest/download/omnid-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv omnid /usr/local/bin/

# macOS Apple Silicon
curl -fsSL https://github.com/xb3sox/omnid/releases/latest/download/omnid-aarch64-apple-darwin.tar.gz | tar xz
sudo mv omnid /usr/local/bin/

# Windows x86_64
irm https://github.com/xb3sox/omnid/releases/latest/download/omnid-x86_64-pc-windows-msvc.zip -OutFile omnid.zip
Expand-Archive omnid.zip -DestinationPath .
New-Item -ItemType Directory -Force -Path "$env:LOCALAPPDATA\Programs\omnid" | Out-Null
Move-Item omnid.exe "$env:LOCALAPPDATA\Programs\omnid\omnid.exe"
$env:Path += ";$env:LOCALAPPDATA\Programs\omnid"
# Persist: add that directory to your user PATH in System Settings

From source (Rust 1.78+):

cargo install --git https://github.com/xb3sox/omnid
# or: cargo install --path .

The problem

• MCP servers live in five different JSON/TOML files across Cursor, Claude Code, VS Code, and the rest
• Rules and instructions duplicated or diverging (CLAUDE.md, .cursor/rules, AGENTS.md, …)
• Moving to a new machine means manual copy-paste — no drift visibility

omnid centralizes sources in one folder, syncs them per agent, and tracks what's landed on disk.

Your whole setup, one folder

Before: copy MCP + rules + skills into every agent by hand.

After: edit matrix.yaml, rules/global.md, skills/ once. omnid pushes to each agent.

What	Source	omnid does
MCP	matrix.yaml	Non-destructive proxy stub
Rules & instructions	rules/global.md	Compile per agent format
Skills	skills/*/SKILL.md	Link (Cursor, Claude Code, Windsurf, VS Code)
Hooks	hooks/omnid.json	Opt-in (Cursor + Claude Code)
Drift tracking	.sync-state.json	Hash-based sync/trace

~/.config/omni/
├── matrix.yaml
├── rules/global.md
├── skills/*/SKILL.md
├── hooks/omnid.json     # optional
└── .sync-state.json     # drift hashes

Move your setup

# On a new machine — copy or clone your config dir, then sync
git clone <your-dotfiles-repo-with-omni> ~/.config/omni
omnid sync --force
omnid credential set my_key <secret> --keychain   # keyring secrets are not in the repo

Use OMNID_MATRIX or --matrix if your config lives outside the default path. After moving the folder, run omnid sync --force so agent stubs pick up the new OMNID_MATRIX path.

Trace drift

• omnid — status dashboard; auto-syncs when drift is detected
• omnid sync --dry-run — preview changes without writing
• .sync-state.json — source and target hashes for synced artifacts
• omnid check — summary health check (not a full drift report)
• omnid doctor — deep health checks with fix hints and drift reasons

Why omnid

• One folder to move — git or copy ~/.config/omni/; one sync command
• Trace what's synced — hash drift in .sync-state.json
• Non-destructive MCP — omnid stub only; other servers untouched
• Tier-aware — full sync for Cursor and Claude Code; rules + skills + MCP for Windsurf and VS Code; see table

Supported agents

Tier	Agents	MCP	Rules	Skills	Hooks
Full	Cursor, Claude Code	✓	✓	✓	opt-in
Rules + Skills + MCP	Windsurf, VS Code	✓	✓	✓	—
Rules + MCP	Codex, OpenCode, Cline, Roo, Kilo	✓	✓	—	—
MCP only	Claude Desktop, Copilot CLI, Gemini CLI, Antigravity, Amazon Q, Junie, Kiro, Zed, Augment CLI/IDE, Goose	✓	—	—	—

omnid agents list → paths on your machine.

Commands

Command	Does
omnid	Setup on first run. Status after that. Auto-sync on drift.
omnid init	Same as first omnid, plus optional --install-daemon
omnid add server	Add a tool (pick a preset or type your own)
omnid add server --preset everything --write	Add demo tool, no prompts
omnid add rule	Append rules/global.md
omnid add skill	New skill scaffold
omnid check	Summary health check (doctor --summary)
omnid doctor	Deep health checks with fix hints
omnid credential list	List credentials and resolution status
omnid sync	Force sync (--dry-run = preview)
omnid sync --force	Sync even if no drift
omnid daemon	Watch + re-sync
omnid proxy --stdio	MCP multiplexer (agents spawn this)
omnid proxy --transport http	MCP multiplexer over HTTP JSON-RPC
omnid uninstall	Remove omnid artifacts
omnid agents list	Paths + compatibility

Config

version: 1
config_dir: ~/.config/omni

servers:
  my_tool:
    transport: stdio
    command: npx
    args: ["-y", "some-mcp-server"]

targets:
  auto_detect: true

# artifacts:
#   hooks:
#     enabled: false

Credentials — declare named credentials in matrix.yaml, reference them with ${credential:name} placeholders, and store values in the OS keyring:

credentials:
  my_key:
    source: keychain
    service: omnid
    account: my_key

servers:
  my_tool:
    transport: http
    url: https://api.example.com
    headers:
      Authorization: "Bearer ${credential:my_key}"

omnid credential set my_key <secret> --keychain

Default keychain entry: service omnid, account my_key (override with --service / --account).

omnid add server appends a YAML snippet (preserves comments). Use --print for snippet only.

See examples/matrix.yaml for a full example config.

How it works

flowchart TB
  subgraph omni ["~/.config/omni/"]
    matrix[matrix.yaml]
    rules[rules/global.md]
    skills[skills/]
    state[.sync-state.json]
  end
  sync[sync_engine]
  agents[AgentConfigs]
  matrix --> sync
  rules --> sync
  skills --> sync
  sync --> agents
  state -.->|"drift trace"| sync
  matrix --> proxy[omnid_proxy] --> backends[MCP_backends]

Loading

• Non-destructive — only omnid stub written. Rest stays.
• Drift-aware — .sync-state.json hashes. Sync when needed.
• Daemon — watch config. Re-sync.
• Multiplexer — server__tool → backend via omnid proxy --stdio
• Backend reload — with daemon running, proxy reloads backends when matrix.yaml changes.

Troubleshooting

Symptom	Fix
Sync pending but nothing changes	Run omnid and read drift reasons, or omnid doctor
MCP tools missing in agent	omnid doctor → stub check; then omnid sync --force
Credential errors	omnid credential list then omnid credential set --keychain NAME secret
Broken skill symlinks	omnid doctor skills check; on Windows ensure Developer Mode for symlinks
Stale MCP backends	Restart agent MCP, or run omnid daemon for auto proxy reload

Development

Requires Rust 1.78+ (MSRV).

cargo install just cargo-deny
just ci

Contributing: CONTRIBUTING.md · AI agents: AGENTS.md · Security: SECURITY.md · Code of Conduct

License

MIT — see LICENSE.