# JARVIS - Autonomous AI Assistant System

**Vision:** Ironman's Jarvis – proactive, autonomous infrastructure management

## Components

### 1. System Health Monitor (`jarvis-health-check.sh`)

**Purpose:** Proactively monitor all infrastructure and alert on issues

**Checks:**

- ✅ Core services (Gateway, Kanban, Voice Surface, Kamoer)
- ✅ Smart Home (Home Assistant, Chromecast, Roborock, Shelly)
- ✅ Network (NAS, Office Server, UniFi, Printer)
- ✅ Databases (MariaDB)
- ✅ Raspberry Pi (SSH, disk, memory)
- ✅ Messaging (Discord)

**Schedule:** Every hour (via cron)

**Usage:**

```bash
bash /home/alex/clawd/tools/jarvis-health-check.sh
```

### 2. Auto-Delegation (`jarvis-delegate.sh`)

**Purpose:** Autonomously route Kanban tasks to specialist agents

**Features:**

- 🤖 Reads tasks with `agent:*` tags
- 🎯 Maps agent tags to models (gemini-flash, nvidia, deepseek, etc.)
- ⏱️ Size-based timeouts (xs=5min, s=10min, m=30min, l=1h, xl=2h)
- 🔄 Max 3 concurrent tasks
- 📊 Auto-updates Kanban status
- **🔧 Self-healing:** Auto-retry with Claude Sonnet diagnosis (max 3 attempts)

**Schedule:** Every 30 minutes (via cron)

**Usage:**

```bash
bash /home/alex/clawd/tools/jarvis-delegate.sh
```

### 2b. Self-Healing System (NEW! 🔥)

**Purpose:** Automatically detect, diagnose, and fix agent task failures

**Three-tier architecture:**

**Tier 1: Error Daemon** (`jarvis-error-daemon.sh`)

- Continuous monitoring of all agent sessions (every 30s)
- Extracts error bundles on failure
- Spawns Claude Sonnet for diagnosis
- Auto-retry with fixes (max 3 attempts)

**Tier 2: Healing Wrapper** (`delegate-with-healing.sh`)

- Manual task delegation with auto-healing
- Per-task retry logic
- Healing agent analysis on failure
- Success/failure reporting

**Tier 3: Jarvis Integration** (built into `jarvis-delegate.sh`)

- Auto-healing in automated delegation
- Exit code + pattern matching for failures
- Claude Sonnet troubleshooting
- Task returns to queue if max retries exceeded

**Inspired by:** [Reddit - Self-healing feedback loop](https://www.reddit.com/r/openclaw/comments/1r5t6e9/)

**Key benefit:** 95% token cost reduction (cheap agents for work, Sonnet only for healing)

**Documentation:** See `SELF-HEALING.md` for full details

**Usage:**

```bash
# Start error daemon (continuous monitoring)
./tools/jarvis-error-daemon.sh monitor

# Manual delegation with healing
./tools/delegate-with-healing.sh 335 gemini-flash

# Jarvis auto-delegation (healing built-in)
./tools/jarvis-delegate.sh
```

### 3. Status Dashboard (`jarvis-status.sh`)

**Purpose:** Real-time overview of Jarvis automation

**Shows:**

- System health summary
- Agent-ready tasks count
- Tasks in progress
- Automation schedule
- Recent activity

**Usage:**

```bash
bash /home/alex/clawd/tools/jarvis-status.sh
```

## Quick Commands

```bash
# Check system health
jarvis-health-check.sh

# Run delegation
jarvis-delegate.sh

# View status
jarvis-status.sh

# View delegation log
tail -f /home/alex/clawd/logs/jarvis-delegation.log
```

## Agent Tag Reference

Add these tags to Kanban tasks for auto-delegation:

| Tag                  | Model            | Best For                         |
| -------------------- | ---------------- | -------------------------------- |
| `agent:gemini-flash` | Gemini 3 Flash   | Quick tasks, research, summaries |
| `agent:gemini-pro`   | Gemini 3 Pro     | Complex analysis, planning       |
| `agent:nvidia`       | Qwen3 235B       | Code, technical writing          |
| `agent:deepseek`     | DeepSeek V3.2    | Deep reasoning, architecture     |
| `agent:llama4`       | Llama 4 Maverick | Specialized tasks                |

## Size Tags (for timeout calculation)

| Tag       | Timeout | Use For           |
| --------- | ------- | ----------------- |
| `size:xs` | 5 min   | Quick wins        |
| `size:s`  | 10 min  | Simple tasks      |
| `size:m`  | 30 min  | Medium complexity |
| `size:l`  | 1 hour  | Complex tasks     |
| `size:xl` | 2 hours | Large projects    |

## Cron Schedule

**Health Monitor:** Every hour

- Checks all infrastructure
- Alerts on critical issues
- HEARTBEAT_OK when healthy

**Auto-Delegation:** Every 30 minutes

- Scans for agent-ready tasks
- Spawns isolated agents
- Updates Kanban status

**GitHub Scanner:** Daily at 16:00

- Finds new OpenClaw builds
- Filters for quality (2+ stars)
- Auto-imports to Kanban

## Logs

- **Delegation log:** `/home/alex/clawd/logs/jarvis-delegation.log`
- **Health checks:** via cron isolated agents
- **GitHub scans:** `/tmp/github-openclaw-daily.jsonl`

## Architecture

```
┌─────────────────────────────────────────────┐
│              JARVIS SYSTEM                  │
├─────────────────────────────────────────────┤
│                                             │
│  ┌──────────────┐       ┌───────────────┐  │
│  │ Health Check │──────▶│ Discord Alert │  │
│  │  (hourly)    │       │  (on issues)  │  │
│  └──────────────┘       └───────────────┘  │
│                                             │
│  ┌──────────────┐       ┌───────────────┐  │
│  │ Kanban Scan  │──────▶│ Spawn Agents  │  │
│  │  (30 min)    │       │  (isolated)   │  │
│  └──────────────┘       └───────────────┘  │
│                                             │
│  ┌──────────────┐       ┌───────────────┐  │
│  │ GitHub Scan  │──────▶│ Import Tasks  │  │
│  │   (daily)    │       │  (filtered)   │  │
│  └──────────────┘       └───────────────┘  │
│                                             │
└─────────────────────────────────────────────┘
```

### 4. Auto-Healing (`jarvis-auto-heal.sh`)

**Purpose:** Automatically restart failed services

**Features:**

- 🔄 Auto-restart Gateway on failure
- 🔄 Auto-restart Kanban API on failure
- 🔄 Auto-restart Home Assistant via SSH
- 🔄 Auto-restart MariaDB on failure
- 📝 Logs all healing attempts
- 🚨 Alerts if restart fails

**Schedule:** Every 5 minutes (via cron)

**Usage:**

```bash
bash /home/alex/clawd/tools/jarvis-auto-heal.sh
```

### 5. Predictive Alerts (`jarvis-predict.sh`)

**Purpose:** Learn patterns and alert before failures

**Tracks:**

- 📊 Pi disk usage trends → Alert if approaching 90%
- 📊 Pi memory usage → Alert if > 85%
- 📊 Gateway response time → Alert if > 2s
- 📊 Kanban response time → Alert if > 1s
- 📊 System crash patterns in syslog

**Schedule:** Every 30 minutes (via cron)

**Data retention:** 30 days in `/home/alex/clawd/data/metrics/`

**Usage:**

```bash
bash /home/alex/clawd/tools/jarvis-predict.sh
```

### 6. Context Learning (`jarvis-context-tracker.sh`)

**Purpose:** Deep context memory - learn preferences and patterns

**Learns:**

- 🧠 Active Kanban projects & tags
- 🧠 Git commit patterns
- 🧠 Working hours patterns
- 🧠 Most used commands
- 🧠 Preferred agents for delegation
- 🧠 Project decision history

**Schedule:** Every hour (via cron)

**Memory:** Stored in `/home/alex/clawd/data/context/memory.json`

**Usage:**

```bash
bash /home/alex/clawd/tools/jarvis-context-tracker.sh
```

## System Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    JARVIS CONTROL LOOP                  │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────┐ │
│  │ Health Check │───▶│ Auto-Healing │───▶│ Discord  │ │
│  │  (hourly)    │    │  (5 min)     │    │  Alert   │ │
│  └──────────────┘    └──────────────┘    └──────────┘ │
│         │                                               │
│         ▼                                               │
│  ┌──────────────┐    ┌──────────────┐                 │
│  │ Predictive   │───▶│ Trend        │                 │
│  │ Analysis     │    │ Reports      │                 │
│  │ (30 min)     │    │              │                 │
│  └──────────────┘    └──────────────┘                 │
│         │                                               │
│         ▼                                               │
│  ┌──────────────┐    ┌──────────────┐                 │
│  │ Context      │───▶│ Memory DB    │                 │
│  │ Learning     │    │ (JSON)       │                 │
│  │ (hourly)     │    │              │                 │
│  └──────────────┘    └──────────────┘                 │
│                                                         │
│  ┌──────────────┐    ┌──────────────┐                 │
│  │ Auto-Delegate│───▶│ Spawn Agents │                 │
│  │ (30 min)     │    │ (isolated)   │                 │
│  └──────────────┘    └──────────────┘                 │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

## Logs & Data

**Logs:**

- Health: `/home/alex/clawd/logs/jarvis-health.log`
- Auto-healing: `/home/alex/clawd/logs/jarvis-auto-heal.log`
- Alerts: `/home/alex/clawd/logs/jarvis-alerts.log`
- Predictive: `/home/alex/clawd/logs/jarvis-predict.log`
- Context: `/home/alex/clawd/logs/jarvis-context.log`
- Delegation: `/home/alex/clawd/logs/jarvis-delegation.log`

**Data:**

- Metrics: `/home/alex/clawd/data/metrics/*.dat`
- Context memory: `/home/alex/clawd/data/context/memory.json`

## Completed Evolution Steps

- [x] **System Health Monitor** - Proactive monitoring every hour
- [x] **Auto-Delegation** - Autonomous task routing every 30 min
- [x] **GitHub Scanner** - Daily build discovery (16:00)
- [x] **Predictive Alerts** - Learn patterns, alert before failures
- [x] **Auto-Healing** - Restart services on failure (every 5 min)
- [x] **Context Memory** - Deep project/preference understanding (hourly)

## Remaining Steps

- [ ] **Voice integration** - Jarvis voice interface (requires whisper-cli)
- [ ] **Resource optimization** - Suggest infrastructure improvements
- [ ] **Project planning** - Autonomous roadmap generation
- [ ] **Advanced ML** - Real linear regression for predictions

---

**"All systems operational and learning, sir." 🦾**