OSTwin

How It Works

OSTwin turns a markdown plan into a fully-orchestrated multi-agent execution. No custom agent code required.

  PLAN.md ──► Engine ──► DAG ──► War-Rooms ──► Agents
     │                    │          │            │
     │  "Build a game"   │  Waves   │  Channels  │  Skills
     │                    │  of      │  Memory    │  MCP Tools
     ▼                    ▼  epics   ▼  Lifecycle ▼
  Goal + Epics      Dependency    Isolated      Role-based
  + Constraints     resolution    execution     specialists

Three Axes of Agent Identity

Every agent in OSTwin is defined by three orthogonal axes. This is what makes agents composable rather than monolithic.

Identity (WHO)

Defined by role.json + ROLE.md. Sets personality, constraints, and communication style. An architect thinks differently than an engineer.

Expertise (WHAT)

Loaded from SKILL.md files on demand. Domain knowledge injected into context only when needed. Skills are portable across roles.

Execution (HOW)

MCP servers provide isolated tool access. Each war-room gets its own tool boundary. No agent can reach outside its sandbox.

Five Architectural Pillars

Zero-Agent Pattern No persistent agent processes. Agents are ephemeral sessions composed at runtime from Role + Skills + Tools.

Composable Skills Modular SKILL.md files that inject domain expertise into any agent session. Portable, testable, versionable.

MCP Isolation Each war-room gets dedicated MCP server instances. Tool access is scoped. No cross-contamination between execution contexts.

War-Rooms Isolated execution environments for each epic. Own filesystem, channel, memory, lifecycle. The unit of parallelism.

Layered Memory Three-tier memory: session (context window), war-room (shared ledger), global (cross-room). Publish/query/search API.

Quick Start

Write a plan, run it, watch agents collaborate:

# 1. Install OSTwin
git clone https://github.com/igot-ai/os-twin.git
cd os-twin && pwsh Install.ps1

# 2. Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."

# 3. Write a plan
cat > my-plan/PLAN.md << 'EOF'
# My First Plan
## Config
provider: anthropic
model: claude-sonnet-4-20250514
## Goal
Build a REST API with authentication and tests.
## Epic 1: Auth System
### DoD
- JWT auth working with login/register endpoints
### Tasks
- TASK-001: Implement user model and auth routes
EOF

# 4. Run it
pwsh Engine.ps1 -PlanPath ./my-plan/PLAN.md

Explore the Docs

Installation Get OSTwin running locally in under 5 minutes.

Quick Start Run your first plan and watch agents collaborate.

Dev Mode Set up the full development environment with dashboard and live monitoring.

Architecture Deep dive into the engine internals, DAG execution, and coordination model.