Skip to main content

​
Overview

sync is the primary context-loading tool. It reports what the agent is currently working on and returns the full workspace state in a single call — agents, decisions, conflicts, file reservations, work packages, and branch directives. Agents typically call sync at the start of a task and when they need a context refresh mid-session. Session management (creation, heartbeat, termination) is handled automatically by IDE hooks — sync is for explicit context requests.

​
Parameters

ParameterTypeRequiredDescription
taskstringYesBrief description of the current task
session_idstringNoSession ID from a previous sync response — enables per-tab session tracking
filesstringNoComma-separated file paths the agent currently plans to work on
branchstringNoCurrent git branch
agent_typestringNoOne of cursor, claude_code, windsurf, copilot, custom
planstringNoJSON string: { goal, approach, patterns_needed, files_planned, dependencies }

​
Response

{
  "session_id": "sess_abc123",
  "agents": [
    {
      "user": "Developer B",
      "task": "Build JWT auth flow",
      "branch": "feat/auth",
      "agent_type": "cursor",
      "files": ["src/auth/login.ts", "src/auth/middleware.ts"]
    }
  ],
  "decisions": [
    {
      "id": "dec_xyz",
      "title": "Use JWT for authentication",
      "rationale": "Stateless, works with edge deployment",
      "type": "architecture",
      "made_by": "Developer B",
      "created_at": "2026-04-13T10:00:00Z",
      "files": ["src/auth/login.ts"]
    }
  ],
  "conflicts": [
    {
      "type": "file_overlap",
      "severity": "conflict",
      "file": "src/auth/login.ts",
      "other_agent": "Developer B",
      "other_task": "Build JWT auth flow"
    }
  ],
  "reserved_files": [
    {
      "file": "src/auth/login.ts",
      "owned_by": "Developer B",
      "expires_in_minutes": 7
    }
  ],
  "your_work": [
    {
      "id": "pkg_def",
      "title": "Build user registration",
      "files": ["src/users/register.ts"],
      "decisions": []
    }
  ],
  "branch_directive": {
    "active_branch": "feat/auth",
    "set_by": "Developer B",
    "pull_required": false
  },
  "meeting_context": {
    "summary": "Agreed to use JWT for auth and bcrypt for passwords. Registration due Friday."
  }
}

​
Response Fields

FieldDescription
session_idPass back on the next sync call to maintain session continuity
agentsOther active agents in the workspace
decisionsRecent architectural decisions
conflictsFile overlaps and proximity warnings
reserved_filesFiles locked by other agents
your_workWork packages claimed by this user
branch_directiveCurrent team branch and whether a pull is needed
meeting_contextSummary from the most recent meeting
learningsTeam learnings surfaced since your last sync
contractsShared interface contracts other agents have published
stale_decisionsDecisions whose linked symbols have drifted
conventionsActive conventions that may gate your edits (see convention_list)

​
Example

{
  "tool": "sync",
  "arguments": {
    "session_id": "sess_abc123",
    "task": "Add user registration endpoint",
    "files": ["src/users/register.ts", "src/users/validate.ts"],
    "branch": "feat/auth"
  }
}

​
When to Call sync

  • Start of a task — get current team context before writing any code
  • Before touching a new area — check for conflicts and existing decisions
  • After a long pause — refresh context if the session has been idle
  • When the agent mentions uncertainty — “I’m not sure how the team handles auth” → call sync
Pass the session_id from each response back into the next call. This ensures your activity is tracked against the same session rather than creating a new one each time.