> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enagrams.com/llms.txt
> Use this file to discover all available pages before exploring further.

# sync

> Report agent activity and receive full workspace context in one round-trip

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

| Parameter    | Type   | Required | Description                                                                     |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------- |
| `task`       | string | **Yes**  | Brief description of the current task                                           |
| `session_id` | string | No       | Session ID from a previous `sync` response — enables per-tab session tracking   |
| `files`      | string | No       | Comma-separated file paths the agent currently plans to work on                 |
| `branch`     | string | No       | Current git branch                                                              |
| `agent_type` | string | No       | One of `cursor`, `claude_code`, `windsurf`, `copilot`, `custom`                 |
| `plan`       | string | No       | JSON string: `{ goal, approach, patterns_needed, files_planned, dependencies }` |

## Response

```json theme={null}
{
  "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

| Field              | Description                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------- |
| `session_id`       | Pass back on the next `sync` call to maintain session continuity                            |
| `agents`           | Other active agents in the workspace                                                        |
| `decisions`        | Recent architectural decisions                                                              |
| `conflicts`        | File overlaps and proximity warnings                                                        |
| `reserved_files`   | Files locked by other agents                                                                |
| `your_work`        | Work packages claimed by this user                                                          |
| `branch_directive` | Current team branch and whether a pull is needed                                            |
| `meeting_context`  | Summary from the most recent meeting                                                        |
| `learnings`        | Team learnings surfaced since your last sync                                                |
| `contracts`        | Shared interface contracts other agents have published                                      |
| `stale_decisions`  | Decisions whose linked symbols have drifted                                                 |
| `conventions`      | Active conventions that may gate your edits (see [`convention_list`](/mcp/convention-list)) |

## Example

```json theme={null}
{
  "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`

<Tip>
  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.
</Tip>