Artifact-driven, spec-first multi-agent orchestration for GitHub Copilot CLI.
Pure Python stdlib. Zero compiled binaries. Zero pip dependencies. Corporate-safe by design.

Quickstart  ·  Why  ·  What ships  ·  Architecture  ·  Docs  ·  Migrate v1 → v2

---

copilot-omni turns GitHub Copilot CLI into a spec-first engineering co-worker. Every request flows through a concreteness-scored front-door router, gets a named plan, runs on a typed pipeline of specialist agents, and leaves behind a durable audit trail under .omni/runs/. You keep Copilot; you get planning, parallelism, policy, and proof.

# Register the marketplace, then install the plugin by name — the
# forward-compatible flow (direct `owner/repo` installs are being deprecated).
copilot plugin marketplace add https://github.com/Jurel89/copilot-omni
copilot plugin install copilot-omni@copilot-omni

⚡ 60-second quickstart

# 1. Prerequisites: GitHub Copilot CLI + Python ≥ 3.9
npm install -g @github/copilot                # skip if already installed
python3 --version                             # POSIX
py -3 --version                               # Windows — either works

# 2. Register the marketplace and install the plugin by name
copilot plugin marketplace add https://github.com/Jurel89/copilot-omni
copilot plugin install copilot-omni@copilot-omni

# 3. Windows corporate only — calibrate the Python interpreter so the MCP
#    server + hooks spawn correctly. No-op on POSIX where `python3` is on PATH.
scripts/omni.cmd doctor --fix-python --fix-python-apply

# 4. Sanity-check the environment (policies, MCP, hooks, Python)
python3 scripts/omni.py doctor          # or: scripts/omni.cmd doctor on Windows

# 5. Scaffold a project — creates .omni/ state directory
python3 scripts/omni.py init

# 6. Let the router decide — vague prompts are auto-refined by deep-interview
copilot -p "autopilot build a habit-tracker CLI with streaks" --allow-all

# 7. Already know what you want? Bypass the interview gate.
copilot -p "autopilot refactor scripts/router.py to use dataclasses --skip-interview" --allow-all

# 8. Run the team orchestrator (tmux on POSIX, subprocess fallback elsewhere)
copilot -p "team run wave-3 plan" --allow-all

Trial-mode, no install: copilot --plugin-dir ./copilot-omni -p "list all skills" --allow-all

Deprecated direct install (still works but warns): copilot plugin install Jurel89/copilot-omni — use the marketplace flow above.

🎯 Why copilot-omni?

You want to…	copilot-omni gives you…
Ship production code with Copilot CLI, not just prototypes	An artifact trail — plans, specs, run states — under .omni/runs/
Stop Copilot from diving into vague prompts	A scored front-door router that redirects ambiguity to deep-interview
Parallelise long builds safely	team orchestrator with tmux + git worktrees, back-pressured subagents, cancel-cascade
Pass corporate EDR / security review	Pure Python stdlib. No binaries. No pip installs. file mcp/server.py → ASCII text
Mix fast/deep/ultrabrain reasoning	Semantic model categories resolved per Copilot subscription at runtime
Prove the plugin is sound in CI	19-check contract validator gates every merge
Roll back cleanly	scripts/omni_migrate_v1_to_v2.py --rollback + idempotent forward migration

📦 What's in the box

27 skills 27 skills — ai-slop-cleaner, autopilot, cancel, configure-notifications, debug, deep-dive, deep-interview, deepinit, external-context, mcp-setup, omni-doctor, omni-reference, omni-setup, plan, ralph, ralplan, release, remember, setup, skill, skillify, team, trace, ultraqa, ultrawork, verify, wiki. Run omni list skills for the live catalogue. 19 specialist agents analyst · architect · planner · critic · executor · explore · debugger · tracer · verifier · qa-tester · test-engineer · code-reviewer · security-reviewer · code-simplifier · document-specialist · writer · git-master · designer · scientist Routing cheatsheet in AGENTS.md.

0 slash commands Slash commands were removed in v2.1.0. Use skills directly via Copilot CLI prompts. 30 MCP tools Over stdio JSON-RPC 2.0, schema-validated on every call: memory · wiki · codebase · notepad · state · shared-memory · trace · policy · health · doctor · lsp · ast-grep. Storage: WAL-mode SQLite with UNIQUE(mode, session_id). 1 lifecycle hook session_start — banner, policy permission checks, metrics. See docs/HOOK_CONTRACT.md.

Inspect persistent stores from the main CLI

You can inspect the plugin's persisted SQLite-backed stores without calling MCP tools directly. Default output is human-readable; add --json for automation.

python3 scripts/omni.py memory list
python3 scripts/omni.py wiki list
python3 scripts/omni.py wiki graph
python3 scripts/omni.py wiki validate
python3 scripts/omni.py state list
python3 scripts/omni.py trace timeline

Inspect the repository knowledge graph

The plugin now exposes a real codebase graph for repository files, local import/reference edges, and immediate refactor impact.

python3 scripts/omni.py codebase graph --json
python3 scripts/omni.py codebase impact scripts/omni.py --json

The graphical explorer was intentionally deferred. The current priority is a corporate-safe JSON/CLI surface that agents and users can query reliably without adding dependencies or UI infrastructure.

🏗️ Architecture

GitHub Copilot CLI
 ├─ reads plugin.json                        ← plugin manifest (root)
 ├─ discovers skills/ (27), agents/ (19)
 ├─ wires hooks/hooks.json  → python hooks/session_start.py
 │    └─ session_start.py       banner, policy checks, metrics
 └─ wires .mcp.json         → python mcp/server.py
                                 └─ SQLite store at $OMNI_HOME/omni.db
                                     WAL mode · UNIQUE(mode, session_id)

Model selection is owned by the Copilot CLI host via the `/model` slash
command. The plugin keeps a lightweight category-to-config passthrough, but it
does not auto-probe or auto-select provider-specific models on its own.

Dive deeper: ARCHITECTURE · TEAM · STATE_MODES

🛡️ Corporate-safe by design

• Runtime footprint — every executed byte is Python 3.9 stdlib or Markdown. No third-party imports (CI-enforced).
• MCP server — one Python file, stdio JSON-RPC 2.0, schema-validated. file mcp/server.py → ASCII text.
• No binaries — nothing to compile, nothing to sign, nothing for EDRs to flag.
• Audit trail — every tool invocation + hook event appended atomically (fcntl.flock / msvcrt.locking) under .omni/audit/.
• Three kill-switches — OMNI_SKIP_HOOKS=1, DISABLE_OMNI=1, OMNI_SKIP_SESSION_START=1 (per-hook overrides for removed hooks are inert). See deprecated aliases in AGENTS.md.
• Policy engine — policies/{strict,standard,permissive}.json permission-checked on session start.
• ~520 tests — unit · integration · MCP-smoke · discovery-smoke · per-module coverage gates (mcp/ ≥ 80 %, hooks/ ≥ 70 %, scripts/ ≥ 60 %).
• Local integration test (never runs in CI) — ./scripts/itest installs the copilot CLI if missing, runs omni doctor, the MCP stdio roundtrip, the discovery probe, and the full verify_plugin_contract.py --all gate (which includes --check-external-cli to block reintroduction of Claude/Codex/Gemini CLI calls and hud statusline residue). If a copilot auth session exists, it adds a trial-mode plugin load and a trivial slash-command invocation. Results go to .omni/integration-test/last-run.log. Corporate auth flows and npm install paths vary between laptops, so this test is intentionally excluded from ci.yml, full-suite.yml, and copilot-nightly.yml — it runs on your machine, against the copilot you actually use, to catch bugs CI cannot reproduce.

📚 Documentation

Topic	Document
Install paths (RHEL, macOS, Windows, air-gapped)	docs/INSTALL.md
Plugin internals + data flow	docs/ARCHITECTURE.md
Front-door router + scoring rubric	docs/ROUTER.md
Semantic model categories	docs/MODELS.md
Team orchestration (tmux + worktrees)	docs/TEAM.md
team on Windows	docs/TEAM-WINDOWS.md
Hook contract & kill switches	docs/HOOK_CONTRACT.md
State-mode registry (MCP)	docs/STATE_MODES.md
State-store ownership matrix	docs/STATE_CONTRACT.md
Four-gate state machine	docs/STATE-MACHINE.md
Environment variables	docs/ENV.md
Skills catalogue	docs/SKILLS.md
Internationalisation scaffolding	docs/I18N.md
Test strategy & coverage gates	docs/TEST_STRATEGY.md
v1 → v2 migration guide	docs/MIGRATION.md
v1 → v2 rollback	docs/MIGRATION-ROLLBACK.md
Architecture Decision Records	docs/ADR/ (ADR-0000 – ADR-0010)
Agent routing cheatsheet	AGENTS.md
Changelog	CHANGELOG.md
Security policy	SECURITY.md

🛠️ Install options

# Marketplace install (recommended, forward-compatible)
npm install -g @github/copilot                # if needed
copilot plugin marketplace add https://github.com/Jurel89/copilot-omni
copilot plugin install copilot-omni@copilot-omni

# Clone + install from local path (useful with mirrored repos / air-gapped)
git clone https://github.com/Jurel89/copilot-omni.git
copilot plugin install ./copilot-omni

# Trial without installing (no side effects)
copilot --plugin-dir ./copilot-omni -p "list all skills" --allow-all

# Legacy direct install — DEPRECATED in current Copilot CLI releases
copilot plugin install Jurel89/copilot-omni

No go build. No pip install. Only Python ≥ 3.9 and the copilot CLI on PATH.

Windows — one post-install calibration

Corporate Windows boxes frequently ship py or python but not python3. Run this once after installing the plugin so the MCP server + hooks spawn against the interpreter you actually have:

:: from the plugin directory (one-time)
scripts\omni.cmd doctor --fix-python --fix-python-apply

The command rewrites .mcp.json and hooks\hooks.json in place with the absolute path to your Python interpreter. Idempotent — re-run after a plugin upgrade if MCP starts failing with -32000 connection closed.

🔁 Migrating from v1.x

v1.x used .omc/ as its state directory and the /oh-my-claudecode:* slash-command namespace. v2.0.0 renames both. Run the migrator once per project:

python3 scripts/omni_migrate_v1_to_v2.py --dry-run   # preview
python3 scripts/omni_migrate_v1_to_v2.py --apply     # execute (idempotent)

Full guide: docs/MIGRATION.md. Rollback path: docs/MIGRATION-ROLLBACK.md.

🤝 Contributing

Pull requests welcome. Before you open one:

1. Run the 19-check contract validator — it is the merge gate.

   python3 scripts/verify_plugin_contract.py --all

2. Run the test suite.

   python3 -m pytest

3. Keep runtime code to Python 3.9 stdlib only. Third-party imports are rejected by CI.
4. Don't add compiled binaries. Don't add npm dependencies. Model selection is owned by the Copilot CLI host via /model — do not add category: frontmatter to agents.

Report vulnerabilities via SECURITY.md.

📜 License

MIT © Copilot Omni contributors.

🙏 Acknowledgements

copilot-omni began as a Copilot-CLI rebuild of the excellent oh-my-claudecode — without it, none of the ergonomics would exist. Everything Copilot-specific — the MCP server, the team orchestrator, the contract validator, and the artifact pipeline — were rebuilt from scratch in pure Python stdlib so the plugin runs anywhere Copilot CLI does and nowhere it doesn't.