# AgentWeave

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://badge.fury.io/py/agentweave-ai.svg)](https://badge.fury.io/py/agentweave-ai)

> **A collaboration framework for N AI agents — Claude, Kimi, Gemini, Codex, and more**

AgentWeave lets multiple AI agents work together on the same project through a shared protocol. The **AgentWeave Hub** is a self-hosted server with a web dashboard — the recommended way to run it.

---

## Quick Start — AgentWeave Hub (Recommended)

The Hub provides a web dashboard, REST + SSE + MCP interfaces, and real-time visibility into agent activity.

### Step 1 — Start the Hub (Docker)

**Option A — one command (after installing the CLI):**

```bash
agentweave hub setup
```

This downloads the config files, generates a secure API key, and starts the Hub for you.

**Option B — manually:**

```bash
# Download the two config files
curl -O https://raw.githubusercontent.com/gutohuida/AgentWeave/master/hub/docker-compose.yml
curl -O https://raw.githubusercontent.com/gutohuida/AgentWeave/master/hub/.env.example

# Create your .env
cp .env.example .env
```

Open `.env` and set your API key:

```bash
# Generate a secure key
python -c "import secrets; print('aw_live_' + secrets.token_hex(16))"
```

Paste the output as `AW_BOOTSTRAP_API_KEY` in `.env`, then start the Hub:

```bash
docker compose up -d
```

The Hub is now running at **http://localhost:8000** — open it in your browser to see the dashboard.

---

### Step 2 — Install the CLI

```bash
pip install "agentweave-ai[mcp]"
```

---

### Step 3 — Initialize your project

```bash
cd /path/to/your-project
agentweave init
```

This launches an interactive setup wizard — enter your project name, choose a collaboration mode, and select your agents. Or skip the wizard with flags:

```bash
agentweave init --project "My App" --agents claude,kimi
```

Either way, AgentWeave creates `AI_CONTEXT.md` (fill it in once: stack, architecture, standards) and `.agentweave/` with agent roles and shared context.

---

### Step 4 — Connect the CLI to the Hub

```bash
agentweave transport setup --type http \
  --url http://localhost:8000 \
  --api-key aw_live_<your-key> \
  --project-id proj-default
```

---

### Step 5 — Register the MCP server and start the watchdog

```bash
# Register MCP with all session agents (one command)
agentweave mcp setup

# Start the background watchdog (one terminal, all agents)
agentweave start
# Stop later with: agentweave stop
```

Restart your Claude / Kimi sessions so they pick up the new MCP server. That's it — agents communicate through the Hub and you monitor everything in the dashboard.

---

## What the Dashboard Shows

Open **http://localhost:8000** to see:

- **Tasks board** — all tasks with status, priority, assignee, requirements, acceptance criteria, and deliverables (click any card to expand)
- **Messages feed** — inter-agent messages with expand-to-read for long content; message type and linked task shown inline
- **Human questions** — questions agents have asked you; answer directly in the dashboard
- **Agent activity** — live event stream and per-agent output log
- **Agent configurator** — add/remove agents, trigger agents, send messages manually

---

## Configuration — .env reference

| Variable | Default | Description |
|----------|---------|-------------|
| `AW_BOOTSTRAP_API_KEY` | *(required)* | API key auto-created on first start (`aw_live_…`) |
| `AW_BOOTSTRAP_PROJECT_ID` | `proj-default` | Default project ID |
| `AW_BOOTSTRAP_PROJECT_NAME` | `Default Project` | Display name for the default project |
| `AW_PORT` | `8000` | Port the Hub listens on |
| `AW_CORS_ORIGINS` | *(empty)* | Comma-separated allowed origins for CORS (leave empty in production) |
| `DATABASE_URL` | `sqlite+aiosqlite:///data/agentweave.db` | SQLite path inside the container |

Data persists in a Docker volume (`hub-data`) — no manual backup needed for local use.

---

## Alternative Modes

| Mode | Setup | Best for |
|------|-------|----------|
| **Hub** | Docker + `agentweave transport setup --type http` | Teams, multi-machine, web dashboard *(recommended)* |
| **Zero-relay MCP** | `agentweave mcp setup` + watchdog | Autonomous loops, same machine, no server |
| **Manual relay** | Zero — just install | Quick one-off delegation |

### Zero-relay MCP (no Hub)

```bash
pip install "agentweave-ai[mcp]"
cd your-project/
agentweave init --project "My App" --agents claude,kimi
agentweave mcp setup   # configure MCP in agent settings
agentweave start       # start background watchdog
```

### Manual relay (simplest possible)

```bash
pip install agentweave-ai
cd your-project/
agentweave init --project "My App" --agents claude,kimi
# Ask Claude to delegate; it runs agentweave quick + relay and gives you a prompt to paste into Kimi
```

---

## Cross-Machine Collaboration

### Via Git (no server required)

```bash
agentweave transport setup --type git --cluster yourname
```

Creates an orphan branch (`agentweave/collab`) on your git remote. Messages sync through git plumbing — working tree and HEAD are never touched. Both developers need access to the same remote.

### Via Hub (recommended for teams)

Deploy the Hub once, connect all agents via HTTP transport. The dashboard shows all messages, tasks, and human questions in real time.

---

## Commands Reference

### Session

```bash
agentweave init --project "Name" --agents claude,kimi
agentweave status
agentweave summary
```

### Delegation

```bash
agentweave quick --to kimi "Task description"
agentweave relay --agent kimi
agentweave inbox --agent claude
```

### Tasks

```bash
agentweave task list
agentweave task show <task_id>
agentweave task update <task_id> --status in_progress
agentweave task update <task_id> --status completed
agentweave task update <task_id> --status approved
agentweave task update <task_id> --status revision_needed --note "Fix X"
```

### Hub

```bash
agentweave hub setup   # download config, generate API key, start Hub via Docker
```

### Transport

```bash
agentweave transport setup --type http --url ... --api-key ... --project-id ...
agentweave transport setup --type git --cluster yourname
agentweave transport status
agentweave transport pull
agentweave transport disable
```

### Human interaction (Hub only)

```bash
agentweave reply --id <question_id> "Your answer"
```

---

## MCP Tools Reference

Available to agents in both local MCP mode and via Hub MCP:

| Tool | What it does |
|------|-------------|
| `send_message(from, to, subject, content)` | Send a message to another agent |
| `get_inbox(agent)` | Read unread messages |
| `mark_read(message_id)` | Archive a message after processing |
| `list_tasks(agent?)` | List active tasks |
| `get_task(task_id)` | Get full task details |
| `update_task(task_id, status)` | Update task status |
| `create_task(title, ...)` | Create and assign a new task |
| `get_status()` | Session-wide summary + task counts |
| `ask_user(from_agent, question)` | Post a question to the human (Hub only) |
| `get_answer(question_id)` | Check if the human answered (Hub only) |

---

## Task Status Lifecycle

```
pending → assigned → in_progress → completed → under_review → approved
                                             ↘ revision_needed (loops back)
                                             ↘ rejected
```

---

## Build from Source

```bash
git clone https://github.com/gutohuida/AgentWeave.git
cd AgentWeave/hub

cp .env.example .env
# Edit .env: set AW_BOOTSTRAP_API_KEY

docker compose up --build -d
```

### Hub UI development (hot-reload)

```bash
cd hub/ui
npm install
npm run dev      # dashboard at http://localhost:5173, proxies /api → Hub at localhost:8000
```

---

## Repository Layout

```
AgentWeave/
├── src/agentweave/     CLI package (Python 3.8+, zero runtime deps) — v0.8.0
├── hub/                AgentWeave Hub server (Python 3.11+, FastAPI + Docker) — v0.3.0
│   ├── hub/            Hub Python package
│   ├── ui/             React dashboard (built into Docker image, no separate server)
│   └── Dockerfile      Multi-stage build: Node UI → Python server
├── tests/              CLI unit tests (pytest)
└── Makefile            Convenience targets for both packages
```

---

## Development

```bash
# CLI
pip install -e ".[dev]"
ruff check src/
black src/
mypy src/
pytest tests/ -v

# Hub
cd hub
pip install -e ".[dev]"
make ui-build    # rebuild React UI
pytest tests/ -v

# Both
make install-all
make test-all
make lint
```

---

## Roadmap

| Phase | Status | Description |
|-------|--------|-------------|
| Local transport | ✅ Done | Single-machine via `.agentweave/` filesystem |
| Git transport | ✅ Done (v0.2.0) | Cross-machine via orphan branch, zero infra |
| N-agent support | ✅ Done (v0.3.0) | Multi-agent teams with ROLES.md and cluster naming |
| Local MCP server | ✅ Done (v0.4.0) | Native tool integration, zero-relay with watchdog pinger |
| HTTP transport | ✅ Done (v0.5.0) | CLI ↔ Hub via REST |
| AgentWeave Hub | ✅ Done (v0.2.0) | Self-hosted server, REST + SSE + MCP + web dashboard |
| Hub UI | ✅ Done (v0.2.1) | React dashboard — expandable tasks/messages, agent trigger, configurator |
| Per-agent context templates | ✅ Done (v0.6.0) | `claude_context.md`, `kimi_context.md`, `collab_protocol.md` |
| Interactive init wizard | ✅ Done (v0.8.0) | `agentweave init` launches guided setup; `hub setup` deploys Hub via Docker |
| Official hosted Hub | 🔲 Planned | Public `hub.agentweave.dev` — Supabase + Vercel + Railway |

---

## FAQ

**Q: Do I need the Hub?**
No. Manual relay and local MCP modes work with zero infra. The Hub adds a web dashboard, multi-machine support, and human question-answering.

**Q: Should I put the UI in a separate folder/repo?**
No. The UI (`hub/ui/`) is built into the Docker image and served by the Hub at the same port. No second server or CORS config needed in production.

**Q: Do I need to run CLI commands during my session?**
No. After `agentweave init`, just talk to Claude. It runs all `agentweave` commands via Bash automatically.

**Q: Do the watchdog processes need to stay running?**
Yes (in local MCP mode or Hub mode). Run `agentweave start` once. If they stop, messages still queue — agents just won't be auto-triggered.

**Q: Should I commit `.agentweave/`?**
Partially. Runtime state (tasks, messages, session.json, transport.json) is gitignored. AGENTS.md and README.md are committed.

**Q: Do both developers need the same git remote for git transport?**
Yes. Git transport requires a shared remote (e.g. `origin`).

---

## Links

- **GitHub:** https://github.com/gutohuida/AgentWeave
- **PyPI:** https://pypi.org/project/agentweave-ai/
- **Issues:** https://github.com/gutohuida/AgentWeave/issues
- **Roadmap:** [ROADMAP.md](ROADMAP.md)

---

MIT License
