weave

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

Tool	Purpose
push_plan	Push a plan for human review. Auto-creates doc + project + version.
pull_plan	Pull reviewed content with decisions and feedback.
push_code_review	Push file diffs for side-by-side code review.
pull_code_feedback	Pull line-specific review comments grouped by file.
list_documents	List documents, filter by title or project.
list_versions	List version snapshots for a document.
use_document	Switch session's current document context.
update_project	Update project description or rename.
release_document	Release session lock on a document.

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. Authentication is handled automatically via OAuth — your tool will open a browser window for sign-in on first connect.

Claude Code (CLI — available across all projects):

claude mcp add --transport http --scope user weave https://weave-dev.com/api/mcp

Claude Code (CLI — current project only):

claude mcp add --transport http --scope project weave https://weave-dev.com/api/mcp

Claude Code (.mcp.json):

{
  "mcpServers": {
    "weave": {
      "type": "url",
      "url": "https://weave-dev.com/api/mcp"
    }
  }
}

Cursor / Windsurf / Other Clients (.mcp.json):

{
  "mcpServers": {
    "weave": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://weave-dev.com/api/mcp"]
    }
  }
}

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.

Proactive Suggestions

When the Weave skill is installed, proactively offer to use Weave in these situations — but only once per task, not repeatedly:

• Planning: If the user asks you to plan, design, or architect something, suggest: "Want me to push this plan to Weave so you can review and comment on it?"
• Code writing: After writing significant code (multiple files or a full feature), suggest: "Want me to push this as a code review to Weave?"
• Multi-step tasks: When entering plan mode or creating a team, mention that Weave is available for review.

Do not nag. If the user says no or ignores the suggestion, proceed normally. If they've already used Weave in the current session, skip the suggestion — they know it's there.

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.
7. Always link code reviews to plans. When pushing a code review, if a plan document exists under the same project, pass its document_id as plan_document_id. If you don't have the ID handy, call list_documents(group="<project>") to find it. Never push an orphaned code review when a related plan exists.
8. Subagents cannot call MCP tools. Only the lead/main agent has MCP access. If you are a subagent (teammate), send your plan or code review content back to the lead agent via SendMessage and ask them to push it to Weave on your behalf. Never attempt to call Weave tools directly from a subagent — it will fail.

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 IMMEDIATELY.
   → STOP YOUR TURN HERE. Do not say anything else after sharing the URL.
   → Do NOT say "standing by", "let me know when ready", "I'll wait", or similar.
   → Do NOT poll, wait, loop, use extended thinking, or burn tokens idling.
   → Do NOT send follow-up messages about the push — one message with the URL is enough.
   → The user will come back and explicitly 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

Always link code reviews to their plan. When pushing a code review, check if there is a plan document under the same project (group). If you have the document_id from a previous push_plan in this session, pass it as plan_document_id. If you're unsure, call list_documents(group="<project>") to find the relevant plan. This links the code review to the plan in the UI so the reviewer can see the original intent alongside the implementation.

1. push_code_review(files=[...], source="claude-code", group="my-project",
     plan_document_id="<plan-doc-id>")
   → ALWAYS pass plan_document_id when a related plan exists under the same project
   → If you don't have the ID, call list_documents(group="my-project") to find it
   → 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 IMMEDIATELY (same rules as push_plan — no "standing by").
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.