Weave

Weave is an AI-to-human review bridge. AI agents push proposed plans and code diffs via MCP; humans review, comment, and approve via a rich web editor.

MCP Tools

See references/tools-plan.md, references/tools-code-review.md, and references/tools-management.md for full parameter docs.

Setup

Add Weave’s MCP server to your agent config. See references/setup.md for per-agent instructions.

Claude Code (.mcp.json):

{
  "mcpServers": {
    "weave": {
      "type": "streamable-http",
      "url": "https://your-weave-instance.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Generate a token at Settings > Auth Tokens in the Weave web UI.

Golden Rule

New user request = new project. Always omit document_id on the first push. The server auto-creates a fresh document every time you call push_plan without document_id. Never look up or reuse document IDs from previous conversations or tasks.

Key Principles

1. Push any plan the user asks for. Weave is a general-purpose plan review tool, not limited to code. Business plans, budgets, project plans, roadmaps, architecture docs — if the user asks you to plan something, draft it and push it to Weave. Never refuse a plan request because it’s “not a software engineering task.”
2. Native MCP calls only. Never write scripts or temp files to interact with Weave.
3. Always set source. Identify yourself (e.g. “claude-code”, “backend-dev”) so the human knows which agent produced each document.
4. context must be informative on every push. Summarize the user’s goal, relevant decisions, and why this change matters. The web UI’s AI uses this to make better suggestions — make it useful and insightful, not mechanical. Never describe the MCP action itself (e.g. “re-pushing to update”) — always describe the intent behind the work.
5. New task = omit document_id. push_plan without document_id always creates a new document. Only pass document_id when re-pushing to the same document within the same task after receiving feedback.
6. Always pass document_id explicitly on pull_plan, push_plan (updates), and pull_code_feedback. Do not rely on the session remembering your current document — sessions can be lost.

Quick Workflow

1. push_plan(plan="...", source="claude-code", group="my-project", context="...")
   → Creates NEW document + project, returns document_id + URL
   → NEVER pass document_id here — let the server create a fresh document
2. Share the document URL with the user and STOP.
   → Do NOT poll, wait, loop, or use extended thinking while waiting.
   → Do NOT "stand by" for review — just tell the user the URL and finish your turn.
   → The user will come back and ask you to pull when they are ready.
3. pull_plan(document_id="<id-from-step-1>")  (only when the user asks)
   → Always pass document_id explicitly — don't rely on session memory
   → Returns markdown (readable plan), decisions (resolved threads), feedback (open threads to address)
4. Address any feedback, then proceed with the approved plan
5. If human requests changes:
   push_plan(document_id="<id-from-step-1>", plan="...", context="Updated based on feedback...")
   → Always pass document_id to update the SAME document

Code Review Workflow

1. push_code_review(files=[...], source="claude-code", group="my-project",
     plan_document_id="<plan-doc-id>")
   → Always pass plan_document_id if this code review is associated with a plan
   → Links the code review to the plan in the UI for traceability
   → Returns code_review_id + URL
2. Share the URL with the user and STOP (same rules as push_plan).
3. pull_code_feedback(code_review_id="<id-from-step-1>")
   → Always pass code_review_id explicitly
   → Returns threads grouped by file_path with line ranges and comments
4. Address feedback, re-push with code_review_id to update the same review.

See references/plan-workflow.md for re-push, versioning, and advanced patterns. See references/code-review-workflow.md for the code review lifecycle. See references/multi-agent-teams.md for team/swarm coordination.

Core Concepts

• Projects group related documents via the group param. Auto-created, session-sticky. See references/projects-and-sessions.md.
• Session locking prevents terminal session conflicts (30-min TTL). See references/projects-and-sessions.md.
• Web editing guard blocks terminal pushes while a human is editing (5-min TTL). Human is never locked out.
• Code reviews use side-by-side Monaco diffs with line-specific threaded comments. See references/code-review-workflow.md.

Session Recovery

MCP sessions are in-memory — lost after /clear, /compact, dev server restart, or deploy. The server auto-recovers expired sessions transparently, but convenience state (currentDocumentId, sessionGroup) resets to null.

Always pass IDs explicitly — document_id on pull_plan/push_plan updates, code_review_id on pull_code_feedback, and group on every push. This makes your calls fully resilient to session loss with zero recovery steps needed.