agent-os

# Agent OS — Persistent Agent Operating System

Agents that remember. Learn. Coordinate.

## What It Does

Agent OS enables multi-agent project execution with persistent memory:

- **Agent Memory** — Each agent remembers past tasks, lessons learned, success rates
- **Task Decomposition** — Break high-level goals into executable task sequences
- **Smart Routing** — Assign tasks to agents based on capability fit
- **Execution Tracking** — Live progress board showing what every agent is doing
- **State Persistence** — Project state survives restarts (resume mid-project)

## Quick Start

### Installation

```bash
clawhub install nova/agent-os
```

### Basic Usage

```javascript
const { AgentOS } = require('agent-os');

const os = new AgentOS('my-project');

// Register agents with capabilities
os.registerAgent('research', '🔍 Research', ['research', 'planning']);
os.registerAgent('design', '🎨 Design', ['design', 'planning']);
os.registerAgent('dev', '💻 Development', ['development']);

os.initialize();

// Run a project
const result = await os.runProject('Build a feature', [
  'planning',
  'design',
  'development',
]);

console.log(result.progress); // 100
```

## Core Concepts

### Agent
Persistent worker with:
- **Memory** — Past tasks, lessons learned, success rates
- **State** — Current task, progress, blockers
- **Capabilities** — What it's good at (research, design, development, etc.)

### TaskRouter
Decomposes goals into executable tasks:
- Breaks "Build a feature" into: plan → design → develop → test
- Matches tasks to agents based on capability fit
- Tracks dependencies (task A must finish before task B)

### Executor
Runs tasks sequentially:
- Assigns tasks to agents
- Tracks progress in real-time
- Persists state so projects survive restarts
- Handles blockers and errors

### AgentOS
Orchestrates everything:
- Register agents
- Initialize system
- Run projects
- Get status

## Architecture

```
AgentOS (top-level orchestration)
├── Agent (persistent worker...

# Agent OS v0.1

**Persistent agent operating system for OpenClaw**

Agents remember across sessions. Learn from experience. Coordinate on complex projects without duplicate work.

---

## What It Does

Agent OS enables multi-agent project execution with:

- **Agent Memory**: Each agent persists knowledge (past tasks, lessons learned, capabilities)
- **Task Decomposition**: Break high-level goals into executable task sequences
- **Smart Routing**: Assign tasks to agents based on capability fit
- **Execution Tracking**: Live progress board showing what every agent is doing
- **State Persistence**: Project state survives restarts (resume mid-project)

## Quick Start

### 1. Install

```bash
npm install agent-os
```

Or clone the repo:

```bash
git clone https://github.com/openclaw/agent-os.git
cd agent-os
npm install
```

### 2. Run the Example

```bash
npm start
```

This runs the canonical example: planning + designing + building a feature with 3 agents.

Expected output:

```
🤖 AGENT OS v0.1
Multi-Agent Project Execution Framework

✅ Registered agent: 🔍 Research (research, planning)
✅ Registered agent: 🎨 Design (design, planning)
✅ Registered agent: 💻 Development (development, research)
✅ AgentOS initialized (Project: clawdgym-feature-2026-02-24)

📋 Initializing project: "Build AI-powered trial member follow-up system for ClawdGym"
   Task types: planning, design, development

📑 Task Plan:
  [1] Break down goal → 🔍 Research (20m)
  [2] Identify risks → 🔍 Research (15m)
  ...

🚀 Starting execution...

⏳ [Task 1] Break down goal (🔍 Research)
[🔍 Research]   Progress: 25%
[🔍 Research]   Progress: 50%
[🔍 Research]   Progress: 75%
[🔍 Research]   Progress: 100%
✅ [Task 1] Complete

...

✅ Project complete! All tasks finished.
```

### 3. View the Dashboard

Open the live dashboard (coming in v0.2 with HTTP server):

```bash
npm run dashboard
```

Then visit: `http://localhost:3000/dashboard`

---

## Architecture

### Core Classes

**`Agent`** — Persi...