Skip to content
OEOSGitHub

The Operating System
for AI Software Teams.

Stop explaining your architecture to every new AI chat.

OEOS turns project knowledge into versioned, deterministic files that every AI assistant starts with.

$ npm install -g oeos-cli
GitHub
  • Local-first
  • MIT
  • Zero telemetry
  • Zero network calls
  • 126 tests passing
oeos — the full loop

Demo terminal running the full OEOS loop: oeos inspect detects the stack (Next.js, TypeScript, PostgreSQL, Docker, GitHub Actions) with an AI readiness score of 92/100; oeos architect generates architecture docs and a diagram; oeos handoff writes shared context files; oeos review passes all deterministic checks and reports READY — every AI starts with the same context.

01 / Why OEOS

Context disappears.
Architecture drifts.
AI forgets.
OEOS doesn't.

Project knowledge becomes files. Files get versioned. Everyone — human or AI — reads the same truth.

  • Local-first

    Runs on your machine. Your code never leaves your disk.

  • Deterministic

    Same input, same output. Diff it, commit it, trust it in CI.

  • Open source

    MIT. RFCs, public roadmap, documented releases.

  • Framework agnostic

    Next.js, Rails, Go, monorepos. OEOS reads what you actually have.

  • AI-friendly

    Claude, Cursor, Copilot, your own agents — same context for all.

  • Safe by default

    Read-only analysis. Dry-run plans. Nothing written without confirmation.

02 / Before / After

Same project. Different operating system.

Before OEOS

  • Docs are outdated the week they're written
  • Onboarding depends on who's available
  • Every AI chat starts from zero
  • Architecture lives in chat history

After OEOS

  • Architecture generated from the code
  • Context versioned in the repo
  • Deterministic, diffable reports
  • Every AI starts with the same knowledge

03 / Commands

One binary. Eight verbs.

Deterministic. Offline. Exit codes your CI can rely on.

  • oeos inspect

    Detect stack, tooling, architecture and AI readiness — scored out of 100.

    oeos inspect → 92/100

  • oeos architect

    Generate architecture documentation and a Mermaid diagram from the real code.

    oeos architect → diagram.mmd

  • oeos review

    Deterministic, read-only pre-PR review. Exits 0 only when the branch is READY.

    oeos review → READY

  • oeos workflow

    Plan and run built-in workflows — bootstrap, fix, review, release — step by step.

    oeos workflow run release

  • oeos handoff

    Generate handoff files any human or AI assistant can pick up cold.

    oeos handoff → .oeos/handoff/

  • oeos doctor

    Health report with OK, WARNING and ERROR statuses. CI-friendly exit codes.

    oeos doctor → 0 errors

  • oeos repair

    Print a dry-run repair plan. Nothing is touched — you read before you act.

    oeos repair → 3 actions planned

  • oeos apply

    Apply deterministic repair actions — only after explicit confirmation.

    oeos apply → ✔ applied

04 / How it works

A loop, not a tool. Repeat.

  1. Understand

    oeos inspect · oeos context

    OEOS reads the project as it is. Writes context your team and your AIs share.

  2. Architect

    oeos architect

    Docs and diagrams generated from the code, not from memory. They stay current.

  3. Review

    oeos review · oeos doctor

    Same verdict on your laptop and in CI. No vibes — exit codes.

  4. Handoff

    oeos handoff

    A new teammate — human or AI — picks up the project cold. Everything is written down.

05 / Architecture

The CLI is just the interface. The product is the shared knowledge system.

No server. No daemon. No lock-in. OEOS writes Markdown your repo owns — which is exactly why every AI can work with it.

Runtime dependencies
0 network calls
State
Plain files in your repo
API surface
Exit codes + Markdown
Requires
Node.js ≥ 18

The v2 horizon adds an agent runtime and an MCP layer on top of the same core — the file contract never changes. See the roadmap.

06 / Trust

Why developers trust OEOS.

Nothing to take on faith. Everything below is in the repository.

  • 126

    tests passing

  • 0

    network calls

  • MIT

    licensed

  • 100%

    deterministic outputs

  • local

    first, always

  • none

    telemetry

  • none

    daemon

  • md

    Markdown only

Your code never leaves your machine. Verify it: read the source.

07 / Installation

Thirty seconds from here to your first report.

terminal

$ npm install -g oeos-cli
$ oeos inspect

No account. No API key. No config. Works offline.

08 / Open source

Built in the open. Built with OEOS.

The OEOS repo is itself an OEOS project. The docs you'll read were generated by the CLI you'll install.

# inside the oeos-cli repository itself

❯ ls docs/

RFC-0001.md ARCHITECTURE.md ROADMAP.md

VISION.md COMMANDS.md WORKFLOWS.md

✔ generated and reviewed with oeos

Every release passes the documented release process — and oeos review itself.

09 / Roadmap

Where this is going.

Direction is public, not promised. It evolves through RFCs, in the repo.

  1. v0.1

    Shipped

    Foundations

    • 12 deterministic commands
    • Context, repair & handoff generation
    • RFC-0001 and public docs

  2. v0.2

    In progress

    Guarded execution

    • Workflow execution with guardrails
    • Richer reports for humans and agents
    • Formal command contracts

  3. v1.0

    Planned

    Stable

    • Frozen file structure & command behavior
    • Versioned project metadata + migrations
    • Compatibility guarantees

  4. v2.0

    Horizon

    Agents & MCP

    • Agent runtime concepts
    • MCP layer integration
    • Multi-agent workflows with governance

10 / Get started

Your project deserves an operating system.

The CLI takes thirty seconds. The shared context lasts the life of the project.

$ npm install -g oeos-cli
Contribute

Software deserves memory.

Code changes. Context stays.