{"id":43295534,"url":"https://github.com/imran-siddique/agent-os","last_synced_at":"2026-02-21T21:09:30.463Z","repository":{"id":334788831,"uuid":"1142729208","full_name":"imran-siddique/agent-os","owner":"imran-siddique","description":"A Safety-First Kernel for Autonomous AI Agents - POSIX-inspired primitives with 0% policy violation guarantee","archived":false,"fork":false,"pushed_at":"2026-02-16T03:52:47.000Z","size":19066,"stargazers_count":49,"open_issues_count":166,"forks_count":16,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-02-16T10:29:58.936Z","etag":null,"topics":["agent-framework","ai-agents","ai-governance","ai-safety","autogen","crewai","governance","guardrails","langchain","llm","mcp","mcp-server","openai","policy-engine","python","semantic-kernel"],"latest_commit_sha":null,"homepage":"https://agentos-copilot.vercel.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/imran-siddique.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":"GOVERNANCE.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"imran-siddique","ko_fi":"imransiddique","custom":["https://buymeacoffee.com/imransiddique"]}},"created_at":"2026-01-26T19:32:50.000Z","updated_at":"2026-02-16T04:02:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/imran-siddique/agent-os","commit_stats":null,"previous_names":["imran-siddique/agent-os"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/imran-siddique/agent-os","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imran-siddique%2Fagent-os","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imran-siddique%2Fagent-os/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imran-siddique%2Fagent-os/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imran-siddique%2Fagent-os/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/imran-siddique","download_url":"https://codeload.github.com/imran-siddique/agent-os/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imran-siddique%2Fagent-os/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29694198,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T18:18:25.093Z","status":"ssl_error","status_checked_at":"2026-02-21T18:18:22.435Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-framework","ai-agents","ai-governance","ai-safety","autogen","crewai","governance","guardrails","langchain","llm","mcp","mcp-server","openai","policy-engine","python","semantic-kernel"],"created_at":"2026-02-01T19:04:50.011Z","updated_at":"2026-02-21T21:09:30.457Z","avatar_url":"https://github.com/imran-siddique.png","language":"Python","readme":"\u003cdiv align=\"center\"\u003e\n\n# Agent OS\n\n**A kernel architecture for governing autonomous AI agents**\n\n[![GitHub Stars](https://img.shields.io/github/stars/imran-siddique/agent-os?style=social)](https://github.com/imran-siddique/agent-os/stargazers)\n[![Sponsor](https://img.shields.io/badge/sponsor-❤️-ff69b4)](https://github.com/sponsors/imran-siddique)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://python.org)\n[![CI](https://github.com/imran-siddique/agent-os/actions/workflows/ci.yml/badge.svg)](https://github.com/imran-siddique/agent-os/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/agent-os-kernel)](https://pypi.org/project/agent-os-kernel/)\n[![Downloads](https://img.shields.io/pypi/dm/agent-os-kernel)](https://pypi.org/project/agent-os-kernel/)\n[![VS Code Extension](https://img.shields.io/badge/VS%20Code-Extension-007ACC?logo=visual-studio-code)](https://marketplace.visualstudio.com/items?itemName=agent-os.agent-os-vscode)\n[![Documentation](https://img.shields.io/badge/docs-imran--siddique.github.io-blue)](https://imran-siddique.github.io/agent-os-docs/)\n[![Featured in awesome-llm-apps](https://img.shields.io/badge/Featured%20in-awesome--llm--apps-orange)](https://github.com/Shubhamsaboo/awesome-llm-apps)\n[![awesome-mcp-servers](https://img.shields.io/badge/awesome--mcp--servers-listed-blue)](https://github.com/punkpeye/awesome-mcp-servers)\n[![Integrated in agent-lightning](https://img.shields.io/badge/Microsoft-agent--lightning-purple?logo=microsoft)](https://github.com/microsoft/agent-lightning/tree/main/contrib/recipes/agentos)\n[![Integrated in LlamaIndex](https://img.shields.io/badge/LlamaIndex-integrated-purple)](https://github.com/run-llama/llama_index/pull/20644)\n[![Downloads](https://static.pepy.tech/badge/agent-os-kernel)](https://pepy.tech/project/agent-os-kernel)\n[![Discussions](https://img.shields.io/github/discussions/imran-siddique/agent-os)](https://github.com/imran-siddique/agent-os/discussions)\n\n\u003e ⭐ **If this project helps you, please star it!** It helps others discover Agent OS.\n\n\u003e 📦 **Install the full stack:** `pip install ai-agent-governance[full]` — [PyPI](https://pypi.org/project/ai-agent-governance/) | [GitHub](https://github.com/imran-siddique/agent-governance)\n\n[Quick Start](#quick-example) • [Documentation](https://imran-siddique.github.io/agent-os-docs/) • [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=agent-os.agent-os-vscode) • [Examples](examples/) • [Agent Hypervisor](https://github.com/imran-siddique/agent-hypervisor) • [AgentMesh](https://github.com/imran-siddique/agent-mesh) • [Agent SRE](https://github.com/imran-siddique/agent-sre)\n\n\u003cbr/\u003e\n\n[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/imran-siddique/agent-os)\n\n*Try Agent OS instantly in your browser - no installation required*\n\n\u003c/div\u003e\n\n### Integrated With\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/langgenius/dify-plugins/pull/2060\"\u003e\u003cimg src=\"https://img.shields.io/badge/Dify-Merged-success?style=flat-square\" alt=\"Dify\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/run-llama/llama_index/pull/20644\"\u003e\u003cimg src=\"https://img.shields.io/badge/LlamaIndex-Merged-success?style=flat-square\" alt=\"LlamaIndex\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/microsoft/agent-lightning/pull/478\"\u003e\u003cimg src=\"https://img.shields.io/badge/Agent--Lightning-Merged-success?style=flat-square\" alt=\"Agent-Lightning\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/langgraph-trust/\"\u003e\u003cimg src=\"https://img.shields.io/badge/LangGraph-PyPI-blue?style=flat-square\" alt=\"LangGraph\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/openai-agents-trust/\"\u003e\u003cimg src=\"https://img.shields.io/badge/OpenAI_Agents-PyPI-blue?style=flat-square\" alt=\"OpenAI Agents\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://clawhub.ai/imran-siddique/agentmesh-governance\"\u003e\u003cimg src=\"https://img.shields.io/badge/OpenClaw-ClawHub-purple?style=flat-square\" alt=\"OpenClaw\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003e **6 framework integrations** across 170K+ GitHub stars. Governance for [Dify](https://github.com/langgenius/dify-plugins/pull/2060) (65K ⭐), [LlamaIndex](https://github.com/run-llama/llama_index/pull/20644) (47K ⭐), [LangGraph](https://pypi.org/project/langgraph-trust/), [OpenAI Agents](https://pypi.org/project/openai-agents-trust/), [Agent-Lightning](https://github.com/microsoft/agent-lightning/pull/478), and [OpenClaw](https://clawhub.ai/imran-siddique/agentmesh-governance).\n\n## 📊 By The Numbers\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\u003ch3\u003e1,577+\u003c/h3\u003e\u003csub\u003eTests Passing\u003c/sub\u003e\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003ch3\u003e6\u003c/h3\u003e\u003csub\u003eFramework Integrations\u003c/sub\u003e\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003ch3\u003e170K+\u003c/h3\u003e\u003csub\u003eCombined Stars of\u003cbr/\u003eIntegrated Projects\u003c/sub\u003e\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003ch3\u003e\u0026lt;0.1ms p99\u003c/h3\u003e\u003csub\u003eGovernance Latency\u003cbr/\u003e\u003ca href=\"benchmarks/results/BENCHMARKS.md\"\u003eBenchmarks\u003c/a\u003e\u003c/sub\u003e\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003ch3\u003e10+\u003c/h3\u003e\u003csub\u003eFramework Proposals\u003cbr/\u003eUnder Review\u003c/sub\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n### 🏢 Adopted By Leading AI Frameworks\n\n| Framework | Stars | Status | Link |\n|-----------|-------|--------|------|\n| **Dify** | 65K ⭐ | ✅ Merged | [dify-plugins#2060](https://github.com/langgenius/dify-plugins/pull/2060) |\n| **LlamaIndex** | 47K ⭐ | ✅ Merged | [llama_index#20644](https://github.com/run-llama/llama_index/pull/20644) |\n| **Microsoft Agent-Lightning** | 15K ⭐ | ✅ Merged | [agent-lightning#478](https://github.com/microsoft/agent-lightning/pull/478) |\n| **LangGraph** | 24K ⭐ | 📦 Published on PyPI | [langgraph-trust](https://pypi.org/project/langgraph-trust/) |\n| **OpenAI Agents SDK** | — | 📦 Published on PyPI | [openai-agents-trust](https://pypi.org/project/openai-agents-trust/) |\n| **OpenClaw** | — | 📦 Published on ClawHub | [agentmesh-governance](https://clawhub.ai/imran-siddique/agentmesh-governance) |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📋 Proposals under review at 10+ frameworks (click to expand)\u003c/b\u003e\u003c/summary\u003e\n\n| Framework | Stars | Proposal |\n|-----------|-------|----------|\n| AutoGen | 54K ⭐ | [microsoft/autogen#7242](https://github.com/microsoft/autogen/issues/7242) |\n| CrewAI | 44K ⭐ | [crewAIInc/crewAI#4502](https://github.com/crewAIInc/crewAI/issues/4502) |\n| Haystack | 22K ⭐ | [deepset-ai/haystack#10615](https://github.com/deepset-ai/haystack/issues/10615) |\n| Semantic Kernel | 27K ⭐ | [microsoft/semantic-kernel#13556](https://github.com/microsoft/semantic-kernel/issues/13556) |\n| smolagents | 25K ⭐ | [huggingface/smolagents#1989](https://github.com/huggingface/smolagents/issues/1989) |\n| LangGraph | 24K ⭐ | [langchain-ai/langgraph#6824](https://github.com/langchain-ai/langgraph/issues/6824) |\n| Google ADK | 18K ⭐ | [google/adk-python#4517](https://github.com/google/adk-python/issues/4517) |\n| PydanticAI | 15K ⭐ | [pydantic/pydantic-ai#4335](https://github.com/pydantic/pydantic-ai/issues/4335) |\n| OpenAI Agents SDK | — | [openai/openai-agents-python#2515](https://github.com/openai/openai-agents-python/issues/2515) |\n| A2A Protocol | 21K ⭐ | [a2aproject/A2A#1501](https://github.com/a2aproject/A2A/issues/1501) |\n| Oracle Agent Spec | — | [oracle/agent-spec#105](https://github.com/oracle/agent-spec/issues/105) |\n| AI Card Spec | — | [agent-card/ai-card#16](https://github.com/Agent-Card/ai-card/issues/16) |\n\n\u003c/details\u003e\n\n### 💡 Why Agent OS?\n\n\u003e **The AI agent market is projected to reach $47B by 2030.** As enterprises deploy autonomous agents at scale, governance becomes the critical infrastructure layer. Agent OS is the kernel that ensures every agent action is policy-enforced, auditable, and compliant — making AI agents enterprise-ready.\n\n**The problem:** AI agents can execute arbitrary tools, access sensitive data, and make autonomous decisions — with no built-in governance, audit trails, or policy enforcement.\n\n**Our solution:** A governance kernel that sits between agents and their actions, providing deterministic policy enforcement in \u003c1ms with zero agent code changes.\n\n### How Agent OS Compares\n\n| Tool | Focus | When it acts |\n|------|-------|--------------|\n| LangChain/CrewAI | Building agents | N/A (framework) |\n| NeMo Guardrails | Input/output filtering | Before/after LLM call |\n| LlamaGuard | Content classification | Before/after LLM call |\n| **Agent OS** | **Action interception** | **During execution** |\n\n\u003e **Agent frameworks** build agents. **Safety tools** filter I/O. **Agent OS** intercepts actions mid-execution — the only kernel-level governance layer.\n\n---\n\n## ⚡ Quick Start in 30 Seconds\n\n```bash\npip install agent-os-kernel\n```\n\n```python\nfrom agent_os import StatelessKernel, ExecutionContext\n\n# Create a governed agent in 3 lines\nkernel = StatelessKernel()\n\n# Define execution context with governance policies\nctx = ExecutionContext(agent_id=\"demo-agent\", policies=[\"read_only\"])\n\n# Your agent runs with policy enforcement\nresult = await kernel.execute(\n    action=\"database_query\",\n    params={\"query\": \"SELECT * FROM users\"},\n    context=ctx\n)\n\n# ✅ Safe queries execute\n# ❌ \"DROP TABLE users\" → Blocked by kernel\n```\n\nThat's it! Your agent now has deterministic policy enforcement. [Learn more →](#what-is-agent-os)\n\n**🎬 See all features in action:**\n```bash\ngit clone https://github.com/imran-siddique/agent-os \u0026\u0026 python agent-os/demo.py\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📋 More examples (click to expand)\u003c/b\u003e\u003c/summary\u003e\n\n### Policy enforcement with custom rules\n\n```python\nfrom agent_os import StatelessKernel\n\nkernel = StatelessKernel()\nkernel.load_policy_yaml(\"\"\"\nversion: \"1.0\"\nname: api-safety\nrules:\n  - name: block-destructive-sql\n    condition: \"action == 'database_query'\"\n    action: deny\n    pattern: \"DROP|TRUNCATE|DELETE FROM .* WHERE 1=1\"\n  - name: rate-limit-api\n    condition: \"action == 'api_call'\"\n    limit: \"100/hour\"\n\"\"\")\n\nresult = await kernel.execute(action=\"database_query\", params={\"query\": \"DROP TABLE users\"})\n# ❌ Blocked: Matched rule 'block-destructive-sql'\n```\n\n### Audit logging\n\n```python\nfrom agent_os import KernelSpace\n\nkernel = KernelSpace()\n\n# Every kernel action is automatically recorded\nresult = await kernel.execute(action=\"read_file\", params={\"path\": \"/data/report.csv\"})\n\n# Query the flight recorder\nentries = kernel.flight_recorder.query(agent_id=\"agent-001\", limit=10)\nfor entry in entries:\n    print(f\"{entry.timestamp} | {entry.action} | {entry.outcome}\")\n```\n\n### Governed chatbot with memory\n\n```python\nfrom agent_os import KernelSpace\nfrom agent_os.emk import EpisodicMemory\n\nkernel = KernelSpace(policy_file=\"policies.yaml\")\nmemory = EpisodicMemory(max_turns=50)\n\n@kernel.register\nasync def chat(message: str, conversation_id: str = \"default\") -\u003e str:\n    history = memory.get_history(conversation_id)\n    response = await call_llm(history + [{\"role\": \"user\", \"content\": message}])\n    memory.add_turn(conversation_id, message, response)\n    return response\n# Outputs are checked against content policies; violations trigger SIGSTOP\n```\n\nSee [examples/](examples/) for 20+ runnable demos including SQL agents, GitHub reviewers, and compliance bots.\n\u003c/details\u003e\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/demo-terminal.svg\" alt=\"Agent OS Terminal Demo\" width=\"700\"/\u003e\n\u003c/p\u003e\n\n---\n\n## 🎯 What You'll Build in 5 Minutes\n\n```python\nfrom agent_os import stateless_execute\n\n# 1. Define safety policies (not prompts — actual enforcement)\n\n# 2. Actions are checked against policies before execution\nresult = await stateless_execute(\n    action=\"database_query\",\n    params={\"query\": \"SELECT revenue FROM sales\"},\n    agent_id=\"analyst-001\",\n    policies=[\"read_only\"]\n)\n# ✅ Safe queries execute\n# ❌ \"DROP TABLE users\" → BLOCKED (not by prompt, by kernel)\n```\n\n**Result:** Defined policies are deterministically enforced by the kernel—not by hoping the LLM follows instructions.\n\nFor the full kernel with signals, VFS, and protection rings:\n\n```python\nfrom agent_os import KernelSpace, AgentSignal, AgentVFS\n\n# Requires: pip install agent-os-kernel[full]\nkernel = KernelSpace()\nctx = kernel.create_agent_context(\"agent-001\")\nawait ctx.write(\"/mem/working/task.txt\", \"Hello World\")\n```\n\n\u003e **Note:** `KernelSpace`, `AgentSignal`, and `AgentVFS` require installing the control-plane module: `pip install agent-os-kernel[full]`\n\n---\n\n## What is Agent OS?\n\nAgent OS applies operating system concepts to AI agent governance. Instead of relying on prompts to enforce safety (\"please don't do dangerous things\"), it provides application-level middleware that intercepts and validates agent actions before execution.\n\n\u003e **Note:** This is application-level enforcement (Python middleware), not OS kernel-level isolation. Agents run in the same process. For true isolation, run agents in containers.\n\n```\n┌─────────────────────────────────────────────────────────┐\n│              USER SPACE (Agent Code)                    │\n│   Your agent code runs here. The kernel intercepts      │\n│   actions before they execute.                          │\n├─────────────────────────────────────────────────────────┤\n│              KERNEL SPACE                               │\n│   Policy Engine │ Flight Recorder │ Signal Dispatch     │\n│   Actions are checked against policies before execution │\n└─────────────────────────────────────────────────────────┘\n```\n\n## The Idea\n\n**Prompt-based safety** asks the LLM to follow rules. The LLM decides whether to comply.\n\n**Kernel-based safety** intercepts actions before execution. The policy engine decides, not the LLM.\n\nThis is the same principle operating systems use: applications request resources, the kernel grants or denies access based on permissions.\n\n---\n\n## Architecture\n\n```mermaid\ngraph TB\n    subgraph \"Layer 4: Intelligence\"\n        SCAK[Self-Correcting Agent Kernel]\n        MUTE[Mute Agent]\n    end\n    \n    subgraph \"Layer 3: Control Plane\"\n        KERNEL[🎯 THE KERNEL\u003cbr/\u003ePolicy Engine + Signals]\n        OBS[Observability\u003cbr/\u003ePrometheus + OTEL]\n    end\n    \n    subgraph \"Layer 2: Infrastructure\"\n        AMB[Agent Message Bus]\n        IATP[Inter-Agent Trust Protocol]\n        ATR[Agent Tool Registry]\n    end\n    \n    subgraph \"Layer 1: Primitives\"\n        PRIM[Base Types + Failures]\n        CMVK[Cross-Model Verification]\n        CAAS[Context-as-a-Service]\n        EMK[Episodic Memory Kernel]\n    end\n    \n    SCAK --\u003e KERNEL\n    MUTE --\u003e KERNEL\n    KERNEL --\u003e AMB\n    KERNEL --\u003e IATP\n    KERNEL --\u003e OBS\n    AMB --\u003e PRIM\n    IATP --\u003e PRIM\n    ATR --\u003e PRIM\n    CMVK --\u003e PRIM\n    EMK --\u003e PRIM\n    CAAS --\u003e PRIM\n```\n\n### Directory Structure\n\n```\nagent-os/\n├── src/agent_os/             # Core Python package\n│   ├── __init__.py           # Public API (re-exports from all layers)\n│   ├── stateless.py          # StatelessKernel (zero-dependency core)\n│   ├── base_agent.py         # BaseAgent, ToolUsingAgent classes\n│   ├── agents_compat.py      # AGENTS.md parser (OpenAI/Anthropic standard)\n│   ├── cli.py                # CLI (agent-os check, review, init, etc.)\n│   └── integrations/         # Framework adapters (LangChain, OpenAI, etc.)\n├── modules/                  # Kernel Modules (4-layer architecture)\n│   ├── primitives/           # Layer 1: Base types and failures\n│   ├── cmvk/                 # Layer 1: Cross-model verification\n│   ├── emk/                  # Layer 1: Episodic memory kernel\n│   ├── caas/                 # Layer 1: Context-as-a-Service\n│   ├── amb/                  # Layer 2: Agent message bus\n│   ├── iatp/                 # Layer 2: Inter-agent trust protocol\n│   ├── atr/                  # Layer 2: Agent tool registry\n│   ├── observability/        # Layer 3: Prometheus + OpenTelemetry\n│   ├── control-plane/        # Layer 3: THE KERNEL (policies, signals)\n│   ├── scak/                 # Layer 4: Self-correcting agent kernel\n│   ├── mute-agent/           # Layer 4: Face/Hands architecture\n│   ├── nexus/                # Experimental: Trust exchange network\n│   └── mcp-kernel-server/    # Integration: MCP protocol support\n├── extensions/               # IDE \u0026 AI Assistant Extensions\n│   ├── mcp-server/           # ⭐ MCP Server (Copilot, Claude, Cursor)\n│   ├── vscode/               # VS Code extension\n│   ├── copilot/              # GitHub Copilot extension\n│   ├── jetbrains/            # IntelliJ/PyCharm plugin\n│   ├── cursor/               # Cursor IDE extension\n│   ├── chrome/               # Chrome extension\n│   └── github-cli/           # gh CLI extension\n├── examples/                 # Working examples\n├── docs/                     # Documentation\n├── tests/                    # Test suite (organized by layer)\n├── notebooks/                # Jupyter tutorials\n├── papers/                   # Research papers\n└── templates/                # Policy templates\n```\n\n---\n\n## Core Modules\n\n| Module | Layer | PyPI Package | Description | Status |\n|--------|-------|-------------|-------------|--------|\n| [`primitives`](modules/primitives/) | 1 | `agent-primitives` | Base failure types, severity levels | ✅ Stable |\n| [`cmvk`](modules/cmvk/) | 1 | `cmvk` | Cross-model verification, drift detection | ✅ Stable |\n| [`emk`](modules/emk/) | 1 | `emk` | Episodic memory kernel (append-only ledger) | ✅ Stable |\n| [`caas`](modules/caas/) | 1 | `caas-core` | Context-as-a-Service, RAG pipeline | ✅ Stable |\n| [`amb`](modules/amb/) | 2 | `amb-core` | Agent message bus (async pub/sub) | ✅ Stable |\n| [`iatp`](modules/iatp/) | 2 | `inter-agent-trust-protocol` | Sidecar trust protocol, typed IPC pipes | ✅ Stable |\n| [`atr`](modules/atr/) | 2 | `agent-tool-registry` | Tool registry with LLM schema generation | ✅ Stable |\n| [`control-plane`](modules/control-plane/) | 3 | `agent-control-plane` | **THE KERNEL** — Policy engine, signals, VFS | ✅ Stable |\n| [`observability`](modules/observability/) | 3 | `agent-os-observability` | Prometheus metrics + OpenTelemetry tracing | ⚠️ No tests |\n| [`scak`](modules/scak/) | 4 | `scak` | Self-correcting agent kernel | ✅ Stable |\n| [`mute-agent`](modules/mute-agent/) | 4 | `mute-agent` | Decoupled reasoning/execution architecture | ⚠️ No tests |\n| [`nexus`](modules/nexus/) | — | *Not published* | Trust exchange network | 🔬 Prototype |\n| [`mcp-kernel-server`](modules/mcp-kernel-server/) | Int | `mcp-kernel-server` | MCP server for Claude Desktop | ⚠️ No tests |\n| [**`hypervisor`**](https://github.com/imran-siddique/agent-hypervisor) | **⭐** | `agent-hypervisor` | **Runtime supervisor — Execution Rings, Joint Liability, Saga Orchestrator** ([own repo](https://github.com/imran-siddique/agent-hypervisor)) | **✅ 184 tests** |\n\n---\n\n## ⭐ Star Feature: Agent Hypervisor\n\n\u003e **Runtime supervisor for multi-agent collaboration** — think \"VMware for AI agents.\"\n\u003e \n\u003e **Now its own repo: [`agent-hypervisor`](https://github.com/imran-siddique/agent-hypervisor)** — 184 tests, 268μs full pipeline, zero dependencies beyond pydantic.\n\nJust as OS hypervisors isolate virtual machines and enforce resource boundaries, the Agent Hypervisor isolates AI agent sessions and enforces **governance boundaries** at sub-millisecond latency.\n\n```\n┌────────────────────────────────────────────────────────────┐\n│                    AGENT HYPERVISOR                         │\n│                                                            │\n│   Ring 0 (Root)      ← SRE Witness required                │\n│   Ring 1 (Privileged)← σ_eff \u003e 0.95 + consensus           │\n│   Ring 2 (Standard)  ← σ_eff \u003e 0.60                        │\n│   Ring 3 (Sandbox)   ← Default for unknown agents          │\n│                                                            │\n│   ┌──────────┐  ┌───────────┐  ┌────────────────────────┐  │\n│   │  Joint    │  │  Semantic  │  │  Merkle-Chained        │  │\n│   │ Liability │  │   Saga     │  │  Delta Audit Trail     │  │\n│   │  Engine   │  │ Orchestr.  │  │  (Tamper-Evident)      │  │\n│   └──────────┘  └───────────┘  └────────────────────────┘  │\n└────────────────────────────────────────────────────────────┘\n```\n\n### Key Capabilities\n\n| Feature | Description | Latency |\n|---------|-------------|---------|\n| **Execution Rings** | 4-level privilege model (Ring 0–3) based on trust score | **0.3μs** |\n| **Joint Liability** | High-trust agents vouch for low-trust agents with bonded reputation | **7μs** |\n| **Saga Orchestrator** | Multi-step transactions with timeout, retry, and auto-compensation | **151μs** |\n| **Delta Audit** | Merkle-chained semantic diffs with blockchain commitment | **27μs** |\n| **Full Pipeline** | Session + join + audit + saga + terminate | **268μs** |\n\n### Quick Start\n\n```bash\npip install agent-hypervisor\n```\n\n```python\nfrom hypervisor import Hypervisor, SessionConfig, ConsistencyMode\n\nhv = Hypervisor()\n\n# Create a governed multi-agent session\nsession = await hv.create_session(\n    config=SessionConfig(consistency_mode=ConsistencyMode.EVENTUAL, max_participants=5),\n    creator_did=\"did:mesh:admin\",\n)\n\n# Agents are automatically assigned privilege rings based on trust score\nring = await hv.join_session(session.sso.session_id, \"did:mesh:agent-alpha\", sigma_raw=0.85)\n# → Ring 2 (Standard) — can execute reversible actions\n\n# Multi-step saga with automatic timeout and compensation\nsaga = session.saga.create_saga(session.sso.session_id)\nstep = session.saga.add_step(\n    saga.saga_id, \"draft_email\", \"did:mesh:agent-alpha\",\n    execute_api=\"/api/draft\", undo_api=\"/api/undo-draft\",\n    timeout_seconds=30, max_retries=2,\n)\n\n# Terminate — returns tamper-evident Merkle root Summary Hash\nmerkle_root = await hv.terminate_session(session.sso.session_id)\n```\n\n📖 **[Full Hypervisor documentation →](https://github.com/imran-siddique/agent-hypervisor)**\n\n---\n\n## IDE \u0026 CLI Extensions\n\n| Extension | Description | Status |\n|-----------|-------------|--------|\n| [`mcp-server`](extensions/mcp-server/) | ⭐ **MCP Server** — Works with Claude, Copilot, Cursor (`npx agentos-mcp-server`) | ✅ Published (v1.0.1) |\n| [`vscode`](extensions/vscode/) | VS Code extension with real-time policy checks, enterprise features | ✅ Published (v1.0.1) |\n| [`copilot`](extensions/copilot/) | GitHub Copilot extension (Vercel/Docker deployment) | ✅ Published (v1.0.0) |\n| [`jetbrains`](extensions/jetbrains/) | IntelliJ, PyCharm, WebStorm plugin (Kotlin) | ✅ Built (v1.0.0) |\n| [`cursor`](extensions/cursor/) | Cursor IDE extension (Composer integration) | ✅ Built (v0.1.0) |\n| [`chrome`](extensions/chrome/) | Chrome extension for GitHub, Jira, AWS, GitLab | ✅ Built (v1.0.0) |\n| [`github-cli`](extensions/github-cli/) | `gh agent-os` CLI extension | ⚠️ Basic |\n\n---\n\n## Install\n\n```bash\npip install agent-os-kernel\n```\n\nOr with optional components:\n\n```bash\npip install agent-os-kernel[cmvk]           # + cross-model verification\npip install agent-os-kernel[iatp]           # + inter-agent trust\npip install agent-os-kernel[observability]  # + Prometheus/OpenTelemetry\npip install agent-os-kernel[nexus]          # + trust exchange network\npip install agent-os-kernel[full]           # Everything\n```\n\n### One-Command Quickstart\n\n**macOS/Linux:**\n```bash\ncurl -sSL https://raw.githubusercontent.com/imran-siddique/agent-os/main/scripts/quickstart.sh | bash\n```\n\n**Windows (PowerShell):**\n```powershell\niwr -useb https://raw.githubusercontent.com/imran-siddique/agent-os/main/scripts/quickstart.ps1 | iex\n```\n\n---\n\n## Quick Example\n\n### Stateless API (Always Available — Zero Dependencies Beyond Pydantic)\n\n```python\nfrom agent_os import stateless_execute\n\n# Execute with policy enforcement\nresult = await stateless_execute(\n    action=\"database_query\",\n    params={\"query\": \"SELECT * FROM users\"},\n    agent_id=\"analyst-001\",\n    policies=[\"read_only\"]\n)\n```\n\n### Full Kernel API (Requires `pip install agent-os-kernel[full]`)\n\n```python\nfrom agent_os import KernelSpace, AgentSignal, PolicyRule\n\nkernel = KernelSpace()\n\n# Create agent context with VFS\nctx = kernel.create_agent_context(\"agent-001\")\nawait ctx.write(\"/mem/working/task.txt\", \"analyze this data\")\n\n# Policy enforcement\nfrom agent_os import PolicyEngine\nengine = PolicyEngine()\nengine.add_rule(PolicyRule(name=\"no_sql_injection\", pattern=\"DROP|DELETE|TRUNCATE\"))\n```\n\n---\n\n## POSIX-Inspired Primitives\n\nAgent OS borrows concepts from POSIX operating systems:\n\n| Concept | POSIX | Agent OS |\n|---------|-------|----------|\n| Process control | `SIGKILL`, `SIGSTOP` | `AgentSignal.SIGKILL`, `AgentSignal.SIGSTOP` |\n| Filesystem | `/proc`, `/tmp` | VFS with `/mem/working`, `/mem/episodic` |\n| IPC | Pipes (`\\|`) | Typed IPC pipes between agents |\n| Syscalls | `open()`, `read()` | `kernel.execute()` |\n\n### Signals\n\n```python\n# Requires: pip install agent-os-kernel[full]\nfrom agent_os import SignalDispatcher, AgentSignal\n\ndispatcher = SignalDispatcher()\ndispatcher.signal(agent_id, AgentSignal.SIGSTOP)  # Pause\ndispatcher.signal(agent_id, AgentSignal.SIGCONT)  # Resume\ndispatcher.signal(agent_id, AgentSignal.SIGKILL)  # Terminate\n```\n\n### VFS (Virtual File System)\n\n```python\n# Requires: pip install agent-os-kernel[full]\nfrom agent_os import AgentVFS\n\nvfs = AgentVFS(agent_id=\"agent-001\")\nvfs.write(\"/mem/working/task.txt\", \"Current task\")\nvfs.read(\"/policy/rules.yaml\")  # Read-only from user space\n```\n\n---\n\n## Framework Integrations\n\nWrap existing frameworks with Agent OS governance:\n\n```python\n# LangChain\nfrom agent_os.integrations import LangChainKernel\ngoverned = LangChainKernel().wrap(my_chain)\n\n# OpenAI Assistants\nfrom agent_os.integrations import OpenAIKernel\ngoverned = OpenAIKernel().wrap_assistant(assistant, client)\n\n# Semantic Kernel\nfrom agent_os.integrations import SemanticKernelWrapper\ngoverned = SemanticKernelWrapper().wrap(sk_kernel)\n\n# CrewAI\nfrom agent_os.integrations import CrewAIKernel\ngoverned = CrewAIKernel().wrap(my_crew)\n\n# AutoGen\nfrom agent_os.integrations import AutoGenKernel\ngoverned = AutoGenKernel().wrap(autogen_agent)\n\n# OpenAI Agents SDK\nfrom agent_os.integrations import OpenAIAgentsSDKKernel\ngoverned = OpenAIAgentsSDKKernel().wrap(agent)\n```\n\n\u003e **Note:** These adapters use lazy interception — they don't require the target framework to be installed until you call `.wrap()`.\n\nSee [integrations documentation](docs/integrations.md) for full details.\n\n### Integration Comparison\n\n| Framework | Governance Level | Async Support | Status | Adapter File |\n|-----------|-----------------|---------------|--------|-------------|\n| **LangChain** | Chain/Agent/Runnable | ✅ `ainvoke` | ✅ Stable | `integrations/langchain_adapter.py` |\n| **OpenAI Assistants** | Run/Thread/Tool Call | ✅ Streaming | ✅ Stable | `integrations/openai_adapter.py` |\n| **AutoGen** | Multi-Agent Orchestration | ❌ Sync only | ✅ Stable | `integrations/autogen_adapter.py` |\n| **Semantic Kernel** | Function/Plugin/Memory | ✅ Native async | ✅ Stable | `integrations/semantic_kernel_adapter.py` |\n| **CrewAI** | Crew/Agent/Task | ❌ Sync only | ✅ Stable | `integrations/crewai_adapter.py` |\n| **OpenAI Agents SDK** | Agent/Tool/Handoff | ✅ Native async | ✅ Stable | `integrations/openai_agents_sdk_adapter.py` |\n\n---\n\n## Examples\n\nThe `examples/` directory contains demos at various levels:\n\n### Getting Started\n\n| Demo | Description | Command |\n|------|-------------|---------|\n| [demo-app](examples/demo-app/) | Uses the stateless API (most reliable) | `cd examples/demo-app \u0026\u0026 python demo.py` |\n| [hello-world](examples/hello-world/) | Minimal example | `cd examples/hello-world \u0026\u0026 python agent.py` |\n| [quickstart](examples/quickstart/) | Quick intro | `cd examples/quickstart \u0026\u0026 python my_first_agent.py` |\n\n### Domain Examples (Self-Contained)\n\nThese examples are self-contained and don't require external Agent OS imports:\n\n| Demo | Description |\n|------|-------------|\n| [healthcare-hipaa](examples/healthcare-hipaa/) | HIPAA-compliant agent |\n| [customer-service](examples/customer-service/) | Customer support agent |\n| [legal-review](examples/legal-review/) | Legal document analysis |\n| [crewai-safe-mode](examples/crewai-safe-mode/) | CrewAI with safety wrappers |\n\n### Production Demos (with Docker + Observability)\n\n| Demo | Description | Command |\n|------|-------------|---------|\n| [carbon-auditor](examples/carbon-auditor/) | Multi-model verification | `cd examples/carbon-auditor \u0026\u0026 docker-compose up` |\n| [grid-balancing](examples/grid-balancing/) | Multi-agent coordination | `cd examples/grid-balancing \u0026\u0026 docker-compose up` |\n| [defi-sentinel](examples/defi-sentinel/) | Real-time attack detection | `cd examples/defi-sentinel \u0026\u0026 docker-compose up` |\n| [pharma-compliance](examples/pharma-compliance/) | Document analysis | `cd examples/pharma-compliance \u0026\u0026 docker-compose up` |\n\nEach production demo includes:\n- **Grafana dashboard** on port 300X\n- **Prometheus metrics** on port 909X\n- **Jaeger tracing** on port 1668X\n\n```bash\n# Run carbon auditor with full observability\ncd examples/carbon-auditor\ncp .env.example .env  # Optional: add API keys\ndocker-compose up\n\n# Open dashboards\nopen http://localhost:3000  # Grafana (admin/admin)\nopen http://localhost:16686 # Jaeger traces\n```\n\n---\n\n## Safe Tool Plugins\n\nAgent OS includes pre-built safe tools via the Agent Tool Registry:\n\n```python\n# Requires: pip install agent-os-kernel[full]\nfrom atr import ToolRegistry, tool\n\n@tool(name=\"safe_http\", description=\"Rate-limited HTTP requests\")\nasync def safe_http(url: str) -\u003e dict:\n    # Tool is automatically registered and sandboxed\n    ...\n\nregistry = ToolRegistry()\nregistry.register(safe_http)\n\n# Generate schemas for any LLM\nopenai_tools = registry.to_openai_schema()\nanthropic_tools = registry.to_anthropic_schema()\n```\n\n---\n\n## Message Bus\n\nConnect agents using the async message bus:\n\n```python\n# Requires: pip install agent-os-kernel[full]\nfrom amb_core import MessageBus, Message\n\nbus = MessageBus()\nawait bus.subscribe(\"tasks\", handler)\nawait bus.publish(\"tasks\", Message(payload={\"task\": \"analyze\"}))\n```\n\nBroker adapters available for Redis, Kafka, and NATS (requires optional dependencies).\n\n---\n\n## CLI Tool\n\nAgent OS includes a CLI for terminal workflows:\n\n```bash\n# Check files for safety violations\nagentos check src/app.py\n# ✓ src/app.py: No violations\n# OR\n# ⚠️  2 violation(s) found in src/app.py:\n#   Line 12: DROP TABLE users;\n#     Violation: Destructive SQL: DROP operation detected\n#     Policy: block-destructive-sql\n\n# Check staged git files (ideal for pre-commit hooks)\nagentos check --staged\n# ✓ No violations in staged files\n\n# Machine-readable JSON output (for CI pipelines)\nagentos check src/app.py --format json\n\n# CI mode (no colors, strict exit codes)\nagentos check --staged --ci\n```\n\n```bash\n# Initialize Agent OS in a project\nagentos init\n# Initialized Agent OS in .agents/\n#   - agents.md: Agent instructions (OpenAI/Anthropic standard)\n#   - security.md: Kernel policies (Agent OS extension)\n#   - Template: strict\n\n# Choose a permissive or audit-only template\nagentos init --template permissive\nagentos init --template audit\n\n# Overwrite an existing .agents/ directory\nagentos init --force\n```\n\n```bash\n# Enable kernel governance and verify the configuration\nagentos secure\n# Securing agents in .\n#   [PASS] kernel version\n#   [PASS] signals defined\n#   [PASS] policies defined\n# Security configuration valid.\n```\n\n```bash\n# Audit agent security configuration\nagentos audit\n# Auditing .\n#   [OK] agents.md\n#   [OK] security.md\n# No issues found.\n\n# JSON output for CI\nagentos audit --format json\n```\n\n```bash\n# Show kernel status (version, installed packages)\nagentos status\n# Agent OS Kernel Status\n# ========================================\n#   Version: 1.2.0\n#   Status: Installed\n#   Project: /home/user/myproject\n#   Agents: Configured (.agents/ found)\n```\n\n```bash\n# Multi-model code review with CMVK consensus\nagentos review src/app.py --cmvk\n# 🔍 Reviewing src/app.py with CMVK...\n# Multi-Model Review (3 models):\n#   ✅ gpt-4: No issues\n#   ⚠️  claude-sonnet-4: 1 potential issue(s)\n#   ✅ gemini-pro: No issues\n# Consensus: 67%\n\n# Specify models\nagentos review src/app.py --cmvk --models \"gpt-4,claude-sonnet-4\"\n```\n\n```bash\n# Validate policy YAML files\nagentos validate\n#   Checking .agents/policy.yaml... OK\n# ✓ All 1 policy file(s) valid.\n\n# Validate specific files in strict mode\nagentos validate policies/*.yaml --strict\n```\n\n```bash\n# Install git pre-commit hook\nagentos install-hooks\n# ✓ Installed pre-commit hook: .git/hooks/pre-commit\n# Agent OS will now check staged files before each commit.\n\n# Append to an existing hook\nagentos install-hooks --append\n```\n\n```bash\n# Start the HTTP API server\nagentos serve --port 8080\n# Agent OS API server starting on 0.0.0.0:8080\n# Endpoints:\n#   GET  /health              Health check\n#   GET  /status              Kernel status\n#   GET  /agents              List agents\n#   POST /agents/{id}/execute  Execute agent action\n```\n\n```bash\n# Output Prometheus-style metrics\nagentos metrics\n# # HELP agentos_policy_violations_total Total policy violations.\n# # TYPE agentos_policy_violations_total counter\n# agentos_policy_violations_total 0\n# ...\n```\n\n---\n\n## MCP Integration (Claude Desktop, GitHub Copilot, Cursor)\n\nAgent OS provides an MCP server that works with any MCP-compatible AI assistant:\n\n```bash\n# Quick install via npx\nnpx agentos-mcp-server\n```\n\n**npm:** [`agentos-mcp-server`](https://www.npmjs.com/package/agentos-mcp-server)  \n**MCP Registry:** `io.github.imran-siddique/agentos`\n\nAdd to your config file:\n\n**Claude Desktop** (`%APPDATA%\\Claude\\claude_desktop_config.json` on Windows):\n```json\n{\n  \"mcpServers\": {\n    \"agentos\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"agentos-mcp-server\"]\n    }\n  }\n}\n```\n\n**Features:** 10 tools for agent creation, policy enforcement, compliance checking (SOC 2, GDPR, HIPAA), human-in-the-loop approvals, and audit logging.\n\nSee [MCP server documentation](extensions/mcp-server/README.md) for full details.\n\n---\n\n## Documentation\n\n### Tutorials\n- [5-Minute Quickstart](docs/tutorials/5-minute-quickstart.md) — Get running fast\n- [30-Minute Deep Dive](docs/tutorials/30-minute-deep-dive.md) — Comprehensive walkthrough\n- [Building Your First Governed Agent](docs/tutorials/first-governed-agent.md) — Complete tutorial\n- [Using Message Bus Adapters](docs/tutorials/message-bus-adapters.md) — Connect agents\n- [Creating Custom Tools](docs/tutorials/custom-tools.md) — Build safe tools\n- [Cheatsheet](docs/cheatsheet.md) — Quick reference\n\n### Interactive Notebooks\n\n| Notebook | Description | Time |\n|----------|-------------|------|\n| [Hello Agent OS](notebooks/01-hello-agent-os.ipynb) | Your first governed agent | 5 min |\n| [Episodic Memory](notebooks/02-episodic-memory-demo.ipynb) | Agent memory that persists | 15 min |\n| [Time-Travel Debugging](notebooks/03-time-travel-debugging.ipynb) | Replay and debug decisions | 20 min |\n| [Cross-Model Verification](notebooks/04-cross-model-verification.ipynb) | Detect hallucinations | 15 min |\n| [Multi-Agent Coordination](notebooks/05-multi-agent-coordination.ipynb) | Trust between agents | 20 min |\n| [Policy Engine](notebooks/06-policy-engine.ipynb) | Deep dive into policies | 15 min |\n\n### Reference\n- [Quickstart Guide](docs/quickstart.md) — 60 seconds to first agent\n- [Framework Integrations](docs/integrations.md) — LangChain, OpenAI, etc.\n- [Kernel Internals](docs/kernel-internals.md) — How the kernel works\n- [Architecture Overview](docs/architecture.md) — System design\n- [CMVK Algorithm](docs/cmvk-algorithm.md) — Cross-model verification\n- [RFC-003: Agent Signals](docs/rfcs/RFC-003-Agent-Signals.md) — POSIX-style signals\n- [RFC-004: Agent Primitives](docs/rfcs/RFC-004-Agent-Primitives.md) — Core primitives\n\n---\n\n## Status \u0026 Maturity\n\nThis is a research project exploring kernel concepts for AI agent governance.\n\n### ✅ Production-Ready\n\nThese components are fully implemented and tested:\n\n| Component | Tests |\n|-----------|-------|\n| **StatelessKernel** — Zero-dependency policy enforcement (`src/agent_os/`) | ✅ Full coverage |\n| **Policy Engine** — Deterministic rule enforcement | ✅ Tested |\n| **Flight Recorder** — SQLite-based audit logging | ✅ Tested |\n| **CLI** — `agent-os check`, `init`, `secure`, `validate` | ✅ Tested |\n| **Framework Adapters** — LangChain, OpenAI, Semantic Kernel, CrewAI, AutoGen, OpenAI Agents SDK | ✅ Implemented |\n| **AGENTS.md Parser** — OpenAI/Anthropic standard agent config | ✅ Full coverage |\n| **Primitives** (`agent-primitives`) — Failure types, severity levels | ✅ Tested |\n| **CMVK** (`cmvk`) — Drift detection, distance metrics (955+ lines) | ✅ Tested |\n| **EMK** (`emk`) — Episodic memory with JSONL storage | ✅ 8 test files |\n| **AMB** (`amb-core`) — Async message bus, DLQ, tracing | ✅ 6 test files |\n| **IATP** (`inter-agent-trust-protocol`) — Sidecar trust, typed IPC | ✅ 9 test files |\n| **ATR** (`agent-tool-registry`) — Multi-LLM schema generation | ✅ 6 test files |\n| **Control Plane** (`agent-control-plane`) — Signals, VFS, protection rings | ✅ 18 test files |\n| **SCAK** (`scak`) — Self-correcting agent kernel | ✅ 23 test files |\n\n### ⚠️ Experimental (Code Exists, Tests Missing or Incomplete)\n\n| Component | What's Missing |\n|-----------|----------------|\n| **Mute Agent** (`mute-agent`) | No tests; all layer dependencies use mock adapters |\n| **Observability** (`agent-os-observability`) | No tests; Prometheus metrics, Grafana dashboards, OTel tracing implemented |\n| **MCP Kernel Server** (`mcp-kernel-server`) | No tests; 1173-line implementation |\n| **GitHub CLI Extension** | Single bash script with simulated output |\n| **Control Plane MCP Adapter** | Placeholder — returns canned responses |\n| **Control Plane A2A Adapter** | Placeholder — negotiation accepts all params |\n\n### 🔬 Research Prototype\n\n| Component | What's Missing |\n|-----------|----------------|\n| **Nexus Trust Exchange** | No `pyproject.toml`, no tests, placeholder cryptography (XOR — **not secure**), all signature verification stubbed, in-memory storage only |\n\n### Known Architectural Limitations\n\n| Limitation | Impact | Mitigation |\n|------------|--------|------------|\n| **Application-level only** | Direct stdlib calls (`subprocess`, `open`) bypass kernel | Pair with container isolation for production |\n| **Blocklist-based policies** | Novel attack patterns not in rules will pass | Add AST-level parsing (#32), use defense in depth |\n| **Shadow Mode single-step** | Multi-step agent simulations diverge from reality | Use for single-turn validation only |\n| **No tamper-proof audit** | Flight Recorder SQLite can be modified by compromised agent | Write to external sink for critical audits |\n| **Provider-coupled adapters** | Each SDK needs separate adapter | Abstract interface planned (#47) |\n\nSee [GitHub Issues](https://github.com/imran-siddique/agent-os/issues) for the full roadmap.\n\n---\n\n## FAQ\n\n### How is this different from prompt-based safety?\n\nPrompt-based safety relies on instructing the LLM to follow rules via system prompts. This approach is probabilistic — the model may still produce unsafe outputs under certain conditions.\n\nAgent OS enforces policies at the middleware layer. Actions are intercepted and validated before execution, making enforcement deterministic rather than dependent on model compliance.\n\n### What frameworks are supported?\n\nAgent OS can wrap and govern agents built with popular frameworks including LangChain, CrewAI, AutoGen, Semantic Kernel, and the OpenAI SDK. It also supports MCP-based integrations.\n\n### Can I use this in production?\n\nCore components such as the **StatelessKernel** and **Policy Engine** are production-ready. However, Agent OS provides application-level enforcement. For high-security environments, it should be combined with infrastructure isolation (e.g., containers).\n\n### How do I write custom policies?\n\nCustom policies can be defined programmatically in Python or declaratively using YAML. Policies define rules that inspect and allow or deny agent actions before execution.\n\n### What is the performance overhead?\n\nPolicy checks are lightweight and typically introduce only minimal latency per action. The overhead depends on the number and complexity of rules configured.\n\n---\n\n## Troubleshooting\n\n### Common Issues\n\n**ModuleNotFoundError: No module named 'agent_os'**\n```bash\n# Install from source\ngit clone https://github.com/imran-siddique/agent-os.git\ncd agent-os\npip install -e .\n```\n\n**Optional modules not available**\n```bash\n# Check what's installed\npython -c \"from agent_os import check_installation; check_installation()\"\n\n# Install everything\npip install -e \".[full]\"\n```\n\n**Permission errors on Windows**\n```bash\n# Run PowerShell as Administrator, or use --user flag\npip install --user -e .\n```\n\n**Docker not working**\n```bash\n# Build with Dockerfile (no Docker Compose needed for simple tests)\ndocker build -t agent-os .\ndocker run -it agent-os python examples/demo-app/demo.py\n```\n\n**Tests failing with API errors**\n```bash\n# Most tests work without API keys — mock mode is default\npytest tests/ -v\n\n# For real LLM tests, set environment variables\nexport OPENAI_API_KEY=sk-...\nexport ANTHROPIC_API_KEY=sk-ant-...\n```\n\n---\n\n## Frequently Asked Questions\n\n**What is the difference between Agent OS and prompt-based guardrails?**\nPrompt-based guardrails ask the LLM to self-police, which fails 26.67% of the time. Agent OS enforces governance at the system level using deterministic policy engines and POSIX-inspired access controls, achieving 0% policy violations. It controls what agents *can* do (capability-based), not just what they *should not* do (filter-based).\n\n**How does Agent OS work with other frameworks?**\nAgent OS integrates with 14+ frameworks via adapters. Install the governance layer alongside your existing framework: use `langgraph-trust` for LangGraph, `openai-agents-trust` for OpenAI Agents, or the MCP server for any MCP-compatible client. Agent OS acts as a kernel layer underneath your agent framework.\n\n**What is the Agent Governance Ecosystem?**\nAgent OS is part of a suite of four projects: Agent OS (policy kernel), [AgentMesh](https://github.com/imran-siddique/agent-mesh) (trust network), [Agent Hypervisor](https://github.com/imran-siddique/agent-hypervisor) (runtime supervisor), and [Agent SRE](https://github.com/imran-siddique/agent-sre) (reliability platform). Together they provide 4,310+ tests across 17 modules.\n\n**Can I use Agent OS in production?**\nYes. Agent OS has 1,500+ tests, a VS Code extension, PyPI package (`pip install agent-os-kernel`), and is integrated into production frameworks like Dify (65K stars) and LlamaIndex (47K stars). It supports Python 3.9+ and runs on any platform.\n\n---\n\n## Contributing\n\n```bash\ngit clone https://github.com/imran-siddique/agent-os.git\ncd agent-os\npip install -e \".[dev]\"\npytest\n```\n\n---\n\n## License\n\nMIT — See [LICENSE](LICENSE)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Exploring kernel concepts for AI agent safety.**\n\n[GitHub](https://github.com/imran-siddique/agent-os) · [Docs](docs/)\n\n\u003c/div\u003e\n","funding_links":["https://github.com/sponsors/imran-siddique","https://ko-fi.com/imransiddique","https://buymeacoffee.com/imransiddique"],"categories":["Lista de Habilidades","Frameworks","🔒 Security","Cloud Infrastructure","Applications","🌟 Community Excellence"],"sub_categories":["Habilidades de la Comunidad","🔒 Security","Tools","Integration \u0026 Advanced Patterns"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimran-siddique%2Fagent-os","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimran-siddique%2Fagent-os","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimran-siddique%2Fagent-os/lists"}