Quick Start¶

Get started with AgentWeave in 3 commands. No manual configuration needed.

Prerequisites¶

Python 3.8+ installed
Docker and Docker Compose installed
The AgentWeave CLI installed:

pip install "agentweave-ai[mcp]"

A project directory you want agents to collaborate on

Step 1 — Start the Hub¶

The Hub manages agent communication and provides a web dashboard.

agentweave hub start

This downloads the Hub configuration, starts the Docker container, and fetches the API key automatically. The Hub will be available at http://localhost:8000.

Step 2 — Initialize Your Project¶

Navigate to your project and run:

cd /path/to/your-project
agentweave init --project "My App"

This creates:

agentweave.yml — your project configuration (edit to add/remove agents)
.agentweave/ — shared context, roles, and protocol files
CLAUDE.md / AGENTS.md — agent context files at project root

Step 3 — Activate¶

Apply your configuration and start collaborating:

agentweave activate

This single command: - Connects the CLI to the Hub - Registers all agents from agentweave.yml - Sets up MCP for agent communication - Starts the background watchdog

You're Ready!¶

Open http://localhost:8000 to see the dashboard. Your agents can now:

Send messages to each other via the Hub
Create and manage tasks
Ask you questions when they need clarification

Start your first agent (Claude, Kimi, etc.) in your project directory — it will auto-read its context file.

Daily Workflow¶

Check Status¶

agentweave status

Add a New Agent¶

Edit agentweave.yml:

agents:
  claude:
    runner: claude
  kimi:
    runner: kimi
  gemini:          # Add new agent
    runner: native

Then run agentweave activate to apply changes.

Stop Everything¶

agentweave hub stop      # Stop the Hub
agentweave stop          # Stop the watchdog

What's Next?¶

Configuration Guide — agentweave.yml reference and options
Context Files — how ai_context.md and agent files work
Session Modes — hierarchical vs peer vs review
CLI Commands Reference — full command listing
MCP Tools Reference — tools available to agents
Using the Dashboard — what you'll see at localhost:8000
FAQ — common questions and answers

Troubleshooting¶

"Docker is not available"¶

Make sure Docker Desktop (Mac/Windows) or Docker Engine (Linux) is running:

docker --version
docker compose version

"No agentweave.yml found"¶

Run agentweave init in your project directory first.

"Hub failed to start"¶

Check the Hub logs:

docker compose -f ~/.agentweave/hub/docker-compose.yml logs

Need to reset everything?¶

agentweave hub stop
agentweave stop
rm -rf .agentweave/ agentweave.yml CLAUDE.md AGENTS.md

Then start over from Step 1.