agentweave-ai 0.9.5

Multi-agent AI collaboration framework (Claude, Kimi, Gemini, Codex, and more)

AgentWeave

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):

agentweave hub setup

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

Option B — manually:

# 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:

# 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:

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

pip install "agentweave-ai[mcp]"

---

Step 3 — Initialize your project

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:

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

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

# 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)

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)

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)

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

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

Delegation

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

Tasks

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

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

Transport

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)

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

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)

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

# 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

---

MIT License