npm package: @openweavr/weavr
Description: Self-hosted workflow automation with AI agents. Weave your workflows together.
Latest version: 0.1.5

<p align="center">
  <img src="./assets/openweavr-logo-text.png" alt="Openweavr" width="400" />
</p>

<p align="center">
  <strong>Self-hosted workflow automation with AI agents.</strong><br/>
  <em>Weave your workflows together.</em>
</p>

<p align="center">
  <a href="https://github.com/openweavr/Openweavr/actions/workflows/ci.yml"><img src="https://github.com/openweavr/Openweavr/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
  <a href="https://github.com/openweavr/Openweavr/releases"><img src="https://img.shields.io/github/v/release/openweavr/Openweavr?include_prereleases&sort=semver" alt="Release" /></a>
  <a href="https://www.npmjs.com/package/@openweavr/weavr"><img src="https://img.shields.io/npm/v/@openweavr/weavr" alt="npm" /></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-22%2B-green.svg" alt="Node.js 22+" /></a>
</p>

<p align="center">
  <img src="./assets/dashboard-screenshot.png" alt="Openweavr Dashboard" width="800" />
</p>

---

Weavr connects AI agents with your developer tools—GitHub, Linear, Notion, Slack, databases, CI/CD, and more. Think Zapier/n8n, but with native AI agent support and full data sovereignty.

## ✨ Features

- **🏠 Self-hosted** — Your workflows, your data, your infrastructure
- **🤖 AI Agents** — Autonomous agents with web search, tool use, and multi-step reasoning
- **🔌 Plugin ecosystem** — Extensible integrations for any tool
- **📡 Real-time** — WebSocket-powered event streaming
- **🎯 DAG execution** — Parallel steps, retries, error handling
- **🖥️ CLI + Web UI** — Terminal power users and visual builders welcome
- **💬 Messaging** — Built-in WhatsApp, Telegram, and iMessage support

## 🚀 Quick Start

```bash
# Install
npm install -g @openweavr/weavr

# Setup
weavr onboard

# Start the gateway
weavr serve

# Create your first workflow
weavr create
```

## 🍎 macOS Menu Bar Launcher (Installer Assets)

Build a minimal macOS menu bar app that starts/stops the server and opens the web UI:

```bash
./scripts/macos/build-launcher.sh
./scripts/macos/build-dmg.sh    # Optional DMG
./scripts/macos/build-pkg.sh    # Optional PKG installer
```

Requires Xcode Command Line Tools (for `xcrun`/`swiftc`).

Optional: start the server automatically at login:

```bash
./scripts/macos/install-launchagent.sh
./scripts/macos/uninstall-launchagent.sh
```

## 📖 Example Workflows

### AI Research Agent

```yaml
name: daily-market-research
description: AI agent researches market data and sends a report

trigger:
  type: cron.schedule
  with:
    expression: "0 9 * * *"  # Every day at 9am

steps:
  - id: research
    action: ai.agent
    with:
      tools: "web_search,web_fetch"
      task: |
        Research current market conditions:
        - Gold and silver prices vs USD
        - Top investment opportunities
        - Key financial news from reliable sources
        Compile into an easy-to-read report.

  - id: notify
    action: whatsapp.send
    needs: [research]
    with:
      to: "+1234567890"
      text: "{{ steps.research.result }}"
```

### GitHub to Slack Notifications

```yaml
name: bug-to-slack
description: Notify Slack when GitHub issues are labeled 'bug'

trigger:
  type: github.issue.labeled
  with:
    label: bug

steps:
  - id: notify
    action: slack.post
    with:
      channel: "#bugs"
      message: "🐛 New bug: {{ trigger.issue.title }}\n{{ trigger.issue.html_url }}"
```

See more examples in the [examples/](./examples) directory.

## 🛠️ CLI Commands

```bash
# Setup & Diagnostics
weavr onboard          # Interactive setup wizard
weavr doctor           # Diagnose configuration issues

# Server
weavr serve            # Start gateway server
weavr serve --port 3847

# Workflows
weavr list             # List all workflows
weavr run <name>       # Run a workflow manually
weavr create           # Create new workflow (interactive)

# AI (coming soon)
weavr ask "When PR is merged, deploy to staging"
```

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                      Gateway Server                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  HTTP API   │  │  WebSocket  │  │  Webhook Receiver   │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
      ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
      │   Engine    │ │   Plugins   │ │  AI Agent   │
      │ (DAG exec)  │ │  (GitHub,   │ │  (Natural   │
      │             │ │  Slack...)  │ │  language)  │
      └─────────────┘ └─────────────┘ └─────────────┘
```

## ⚙️ Configuration

### AI Provider
Configure your AI provider during onboarding or in Settings:
- **Anthropic** (Claude) - Recommended
- **OpenAI** (GPT-4)
- **Ollama** (Local models)

### Web Search (for AI Agents)
AI agents need a search API to browse the web. Get a free Brave Search API key:

1. Sign up at [brave.com/search/api](https://brave.com/search/api/)
2. Choose "Data for Search" plan (2,000 free queries/month)
3. Add your API key in Settings or set `BRAVE_API_KEY` environment variable

## 📁 Project Structure

```
~/.weavr/
├── config.yaml        # Global configuration
├── workflows/         # Your workflow definitions
├── plugins/           # Installed plugins
├── logs/              # Execution logs
└── scheduler.db       # Scheduler queue/state (configurable)
```

You can override the scheduler database location in `~/.weavr/config.yaml`:

```yaml
scheduler:
  dbPath: /path/to/scheduler.db
```

## 🔌 Creating Plugins

```typescript
import { definePlugin, defineAction } from 'weavr/plugins';

export default definePlugin({
  name: 'my-plugin',
  version: '1.0.0',

  actions: [
    defineAction({
      name: 'greet',
      execute: async (ctx) => {
        const name = ctx.config.name as string;
        ctx.log(`Hello, ${name}!`);
        return { greeted: name };
      },
    }),
  ],
});
```

## 🤝 Contributing

We welcome contributions! AI-assisted PRs are explicitly encouraged.

See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for guidelines.

## 📜 License

MIT © Weavr Contributors