OmniAgent-OS
GitHub ↗
v0.3.0-beta.1 · MIT · local-first

One source of truth for all your AI coding agents.

A local-first control layer that keeps a single canonical skill library for Claude Code, OpenAI Codex CLI and Antigravity (Gemini) on the same machine — audited, planned, reversible.

View on GitHub ↗ Quick start

Python · no third-party dependencies · Windows / macOS / Linux

Claude Code Codex CLI Antigravity SSOT ssot/skills .claude/skills .agents/skills .gemini/ config/skills AGENTS CANONICAL RENDERED
01 — THE PROBLEM

Siloed agents.

Each agent keeps its own skills folder and its own memory. Skills get copied three or four times, drift apart, and what one agent learns never reaches the others.

Beforeillustrative · 3 copies per skill
.claude/skills/ pdf-tools/ copy code-review/ path≠ release-notes/ v1 node_modules/ ×n
.agents/skills/ pdf-tools/ copy code-review/ path≠ release-notes/ v1 node_modules/ ×n
.gemini/config/skills/ pdf-tools/ copy code-review/ path≠ release-notes/ v2 drift node_modules/ ×n

Same skill, three folders. Hardcoded paths make identical files look different; real edits land in only one place.

After1 canonical copy · rendered per agent
ssot/skills/ pdf-tools/ code-review/ release-notes/ v2 no vendored deps
ADAPTER→
.claude/skills
.agents/skills
.gemini/config/skills

Edit once. Each agent gets a tracked copy with its own paths filled in, and every copy is hash-verified.

02 — WHAT AN AUDIT FOUND

Most of the “drift” wasn’t drift.

CASE STUDY

One-machine case study: an audit of a single developer workstation. These are not industry statistics — run the audit on your own machine to get yours.

60,000+ files (~1.1 GB) across agent skill folders
Over 85% were nested node_modules. Actual instructions and source: ~3,200 files (~55–75 MB).
81.6% fake drift
Of 38 skills that looked different between agents, 31 were logically identical. Only hardcoded paths differed.
3 skills with genuine version drift
The rest were copies. Three real differences are a reconciliation task, not a reason to keep three libraries.
03 — HOW IT WORKS

Look first. Write only when you say so.

Three Python scripts: audit_skills.py, the omniagent.py Skill Manager, and the experimental path_adapter.py.

  1. 01 · read-only audit SHA-256 and line-level diff across every agent skill store. audit_skills.py --output .local/reports
  2. 02 · read-only discover Show which standard agent stores exist on this machine. omniagent.py discover
  3. 03 · read-only plan Compute what would change per target. No files are touched. omniagent.py plan --source … --target …
  4. 04 · needs --yes adopt Track existing skills that match the SSOT byte-for-byte. Skill files stay unchanged. omniagent.py adopt … --yes
  5. 05 · needs --yes apply Install missing skills and update managed copies, with backup and journal. omniagent.py apply … --yes --skip-blocked
  6. 06 · undo rollback / recover Undo a transaction by ID, or finish cleanly after a crash. omniagent.py rollback --transaction ID --yes
ARCHITECTURE
SSOTssot/skills/ · normalized library
→
Path & Template Adapter experimentalrenders {{SKILLS_DIR}} per agent, verifies hashes
→
.claude/skills
.gemini/config/skills
.agents/skills
Codex’s internal .codex/skills/.system runtime is left untouched.
04 — SAFETY BY DEFAULT

Your agent folders are someone’s work. It acts like it.

R/O Read-only by default Every write needs --yes after a plan. Without it, nothing changes.
≠ Never overwrites your edits Skills it doesn’t manage, and skills edited by hand, are blocked — not replaced.
cp Tracked copies, not symlinks No admin rights needed on Windows. Each copy is checksummed.
↺ Backup, journal, rollback Two-phase commit and recover after a crash — tested by killing the real process mid-write.
≡ Byte-identical, by test Adopt and rollback are proven byte-identical in the test suite.
∅ Refuses what it shouldn’t touch Credential files and source symlinks are refused. node_modules, .git and caches are skipped.
CI green on Windows and Ubuntu · python -m unittest discover -s tests
05 — QUICK START

Three commands. None of them write.

Audit, discover, plan. Review the table, then decide whether to apply. Test against disposable --target directories first.

Read the USAGE runbook ↗
PowerShell — sample output
PS> python audit_skills.py --output .local/reports
wrote audit.json, audit_report.md → .local/reports/
 
PS> python omniagent.py discover
claude ~\.claude\skills present
agents ~\.agents\skills present
gemini ~\.gemini\config\skills present
 
PS> python omniagent.py plan --source .\ssot\skills --target "claude=$HOME\.claude\skills"
TARGET SKILL ACTION
claude pdf-tools install
claude code-review unchanged
claude release-notes blocked_unmanaged
plan only — no files changed.
Illustrative output. Skill names and paths are examples.
06 — ROADMAP

What exists, and what doesn’t yet.

Released Beta Planned — not built
  1. v0.2Released
    Skill Manager discover, plan, adopt, apply, rollback.
  2. v0.3Beta
    Path Adapter Per-agent rendering, adapter-aware adopt, crash recovery.
  3. v0.3.xPlanned
    Drift reconciliation + dependency hydration
  4. v0.4Planned
    Shared Second Brain over MCP Design draft: agents propose notes; only evidence-backed notes become verified.
  5. v0.5Planned
    Multi-agent coordination
  6. v1.0Planned
    Windows Local Agent OS
07 — THE BIGGER VISION

An Agent OS, built from the bottom up.

Three layers. Only the first one ships today; the others wait until it’s solid.

LAYER 3CoordinationSafe handoff, review and git worktrees between agents.
Planned · v0.5
LAYER 2Second BrainA shared, verified memory that every agent can read.
Planned · v0.4
LAYER 1SkillsShared skills from one canonical source, installed as tracked copies per agent.
Available now
08 — FAQ

Questions people ask first.

What is OmniAgent-OS?

OmniAgent-OS is an open-source, local-first Python tool that keeps one canonical skill library for Claude Code, OpenAI Codex CLI and Antigravity (Gemini). It audits the skill folders each agent already has, plans changes without writing, then installs tracked, hash-verified copies that you can roll back.

How is it different from symlinking one skills folder into every agent?

Symlinks make every agent read and write the same files, and on Windows they need Developer Mode or admin rights. OmniAgent-OS installs a separate tracked copy per agent instead, records its checksum, and only updates a copy when it still matches what it installed.

Will it overwrite skills I already have?

No. Skills it does not manage and skills you edited by hand are reported as blocked, not replaced. The adopt command only takes over an existing skill when it matches the canonical copy byte for byte, and even then it records state without changing any skill files.

Does it work on Windows without admin rights?

Yes. The default mode copies files rather than creating symlinks, so it runs from a normal user PowerShell session. CI runs the test suite on Windows and Ubuntu. Test against disposable target folders before pointing it at your real agent skill stores.

Which agents and folders does it support?

It manages .claude/skills for Claude Code, .agents/skills for Codex and other agents, and .gemini/config/skills for Antigravity (Gemini). It never touches Codex's internal .codex/skills/.system runtime. Files are verified on disk; running every skill inside Codex and Antigravity is not fully tested yet.

How do I undo a change?

Every apply or adopt prints a transaction ID. Run omniagent.py rollback --transaction ID --yes to undo it. Backups and a journal are kept under .local/manager/. If a run is interrupted, for example by a crash, the recover command finishes or reverses it using the two-phase journal.

Does OmniAgent-OS share memory between agents?

Not yet. Today it manages skills only. A shared, verified second brain over MCP is planned for v0.4 and exists only as a design draft: agents would propose notes, and only evidence-backed notes would become trusted. Multi-agent coordination is planned for v0.5.

Is it ready for production use?

It is a beta (v0.3.0-beta.1). Plan and audit are read-only and safe to try. Writes are guarded by --yes, backups and rollback, but the project recommends testing on disposable target folders first and keeping a backup of .local/manager/ if you want rollback to stay available.