From 585325e8f1ae3d0505225e45e72f647ce9ad976a Mon Sep 17 00:00:00 2001 From: Basem Sufan Date: Sat, 6 Jun 2026 18:11:33 +0300 Subject: [PATCH 1/2] chore: rewrite README for clarity and conversion Co-authored-by: Cursor --- README.md | 136 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 80 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index 5f17505..901fb03 100644 --- a/README.md +++ b/README.md @@ -4,23 +4,44 @@ [![CodeQL](https://github.com/xb3sox/omnid/actions/workflows/codeql.yml/badge.svg)](https://github.com/xb3sox/omnid/actions/workflows/codeql.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) -**One config folder. 20+ AI coding agents. MCP, rules, and skills — kept in sync.** +**One folder. 20+ agents. MCP, rules, skills — synced.** -omnid is a Rust CLI that owns `~/.config/omni/` and pushes a non-destructive MCP proxy stub, compiled rules, and linked skills to Cursor, Claude Code, VS Code, Windsurf, Codex, and the rest of your toolchain. +Too many AI tools. Each wants its own MCP config, rules, skills. They drift. You copy-paste forever. + +omnid owns `~/.config/omni/`. One edit. Every agent updated. Your other MCP servers stay alone. + +- Add MCP once, not five times +- Write rules once → `.mdc`, `CLAUDE.md`, `AGENTS.md`, etc. +- Sync when changed. Not every run. ## Quick start ```bash -omnid # scaffold config, sync if drift, show status -omnid add server # add MCP backends when ready -omnid init # optional guided setup +omnid init # first time +omnid # status + sync if drift +omnid add server # add MCP backend ``` -Set `OMNID_NONINTERACTIVE=1` in CI to skip prompts. +No config? `omnid` alone makes `~/.config/omni/` and shows what's on your machine. + +CI: `OMNID_NONINTERACTIVE=1` skips prompts. + +### Example + +``` +omnid — unified agent plane +──────────────────────────────────────── +Matrix ~/.config/omni/matrix.yaml valid +Agents 3 installed · in sync + cursor mcp ok rules ok skills ok hooks n/a + claude_code mcp ok rules ok skills ok hooks n/a + vscode mcp ok rules ok skills n/a hooks n/a +Backends 2 configured +``` ## Install -**Binaries** — [GitHub Releases](https://github.com/xb3sox/omnid/releases) +[GitHub Releases](https://github.com/xb3sox/omnid/releases) ```bash # Linux x86_64 @@ -36,63 +57,79 @@ 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 . +Move-Item omnid.exe "$env:LOCALAPPDATA\Microsoft\WindowsApps\" # or any folder on PATH ``` -**From source** +From source (Rust 1.78+): ```bash cargo install --git https://github.com/xb3sox/omnid # or: cargo install --path . ``` -## What gets synced +## What you get + +**Before:** copy MCP + rules + skills into every agent by hand. + +**After:** edit `matrix.yaml`, `rules/global.md`, `skills/` once. omnid pushes to each agent. | Artifact | Source | Behavior | |----------|--------|----------| -| **MCP** | `matrix.yaml` | Proxy stub per agent — existing servers untouched | -| **Rules** | `rules/global.md` | Compiled to `.mdc`, `CLAUDE.md`, `AGENTS.md`, … | -| **Skills** | `skills/*/SKILL.md` | Symlink or copy into Cursor + Claude Code | -| **Hooks** | `hooks/omnid.json` | Opt-in (`artifacts.hooks.enabled: true`) | +| **MCP** | `matrix.yaml` | Proxy stub per agent. Your servers untouched. | +| **Rules** | `rules/global.md` | → `.mdc`, `CLAUDE.md`, `AGENTS.md`, … | +| **Skills** | `skills/*/SKILL.md` | Symlink/copy into Cursor + Claude Code | +| **Hooks** | `hooks/omnid.json` | Off unless `artifacts.hooks.enabled: true` | ``` ~/.config/omni/ -├── matrix.yaml # MCP backends + targets +├── matrix.yaml ├── rules/global.md ├── skills/*/SKILL.md -├── hooks/omnid.json # optional, off by default -└── .sync-state.json # drift tracking +├── hooks/omnid.json # optional +└── .sync-state.json # drift hashes ``` -## Commands - -| Command | What it does | -|---------|--------------| -| `omnid` | Status dashboard; auto-sync on drift only | -| `omnid init` | First-time guided setup | -| `omnid add server` | Add MCP server (interactive) | -| `omnid add rule` | Append to `rules/global.md` | -| `omnid add skill` | Scaffold a new skill | -| `omnid check` | Validate config + agent health | -| `omnid sync` | Force sync (`--dry-run` for diffs) | -| `omnid sync --force` | Sync even when no drift | -| `omnid daemon` | Watch config and re-sync | -| `omnid proxy --stdio` | MCP multiplexer (spawned by agents) | -| `omnid uninstall` | Remove omnid-owned artifacts | -| `omnid agents list` | Agent paths + compatibility | - -## Supported agents +## Agents | Tier | Agents | MCP | Rules | Skills | Hooks | |------|--------|:---:|:-----:|:------:|:-----:| | Full | Cursor, Claude Code | ✓ | ✓ | ✓ | opt-in | | Rules + MCP | Windsurf, Codex, OpenCode, Cline, Roo, Kilo, VS Code | ✓ | ✓ | — | — | -| MCP only | 11 others (20 total) | ✓ | — | — | — | +| 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. -Run `omnid agents list` for exact config paths on your machine. +## How it works + +``` +matrix.yaml → sync → agent configs + ↓ + omnid proxy → MCP backends +``` + +- **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` -## Configuration +## Commands -Minimal `matrix.yaml`: +| Command | Does | +|---------|------| +| `omnid` | Status. Auto-sync on drift. | +| `omnid init` | Guided setup | +| `omnid add server` | Add MCP (interactive) | +| `omnid add rule` | Append `rules/global.md` | +| `omnid add skill` | New skill scaffold | +| `omnid check` | Validate config + agents | +| `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 uninstall` | Remove omnid artifacts | +| `omnid agents list` | Paths + compatibility | + +## Config ```yaml version: 1 @@ -112,26 +149,13 @@ targets: # enabled: false ``` -`omnid add server` edits via serde — YAML comments are dropped. Edit the file directly to keep comments. - -## How it works - -``` -matrix.yaml → sync engine → agent configs (stub + rules + skills) - ↓ - omnid proxy → MCP backends (server__tool routing) -``` - -- **Non-destructive MCP** — omnid writes its proxy stub; your other MCP entries stay. -- **Drift-aware sync** — `.sync-state.json` tracks hashes; default run syncs only when needed. -- **Daemon** — watches `matrix.yaml`, `rules/`, `skills/`, `hooks/` and re-syncs. -- **Backend reload** — MCP pool refreshes when agents restart their MCP connection. +`omnid add server` drops YAML comments (serde). Edit file by hand to keep them. -## Development +## Dev ```bash -cargo install just cargo-deny # once -just ci # fmt + clippy + test + deny +cargo install just cargo-deny +just ci ``` -Contributing: [CONTRIBUTING.md](CONTRIBUTING.md) · AI agents: [AGENTS.md](AGENTS.md) · Security: [SECURITY.md](.github/SECURITY.md) · [Code of Conduct](CODE_OF_CONDUCT.md) +[CONTRIBUTING.md](CONTRIBUTING.md) · [AGENTS.md](AGENTS.md) · [SECURITY.md](.github/SECURITY.md) · [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) From 1f2ad4438da4c84013051e68af224b1f4d3a8eb1 Mon Sep 17 00:00:00 2001 From: Basem Sufan Date: Sat, 6 Jun 2026 18:27:02 +0300 Subject: [PATCH 2/2] docs: clarify non-destructive MCP wording in README Co-authored-by: Cursor --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 901fb03..49b1c4f 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Too many AI tools. Each wants its own MCP config, rules, skills. They drift. You copy-paste forever. -omnid owns `~/.config/omni/`. One edit. Every agent updated. Your other MCP servers stay alone. +omnid owns `~/.config/omni/`. One edit. Every agent updated. Your other MCP servers stay untouched. - Add MCP once, not five times - Write rules once → `.mdc`, `CLAUDE.md`, `AGENTS.md`, etc.