> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/settings/synchronization/trackers/crosswatch.md).

# CrossWatch

Local Tracker adapter notes for syncing watchlist, ratings, history, and progress.

CrossWatch Local Tracker stores and synchronizes tracker data locally. It supports watchlist, ratings, history, and progress.

{% hint style="info" %}
Connect CrossWatch Local Tracker first. Use [CrossWatch Local Tracker (Authentication provider)](/crosswatch/settings/connections/trackers/crosswatch.md).
{% endhint %}

{% hint style="warning" %}
Local Tracker data and snapshots live in `/config`. Use persistent storage for `/config`.
{% endhint %}

### What it supports

* Direction: source or target in a pair, one-way or two-way
* Features:
  * **Watchlist**
  * **Ratings**
  * **History**
  * **Progress**
  * **Collection** (source or target, one-way only)
  * **Playlists** (not supported)
* Delta sync: no remote delta feed is required. CW reads local state and detects changes during normal pair synchronization.
* IDs: stores identifiers supplied by CW. Watchlist items with an IMDb ID can gain a TMDb ID through metadata resolution.

Each pair keeps separate local tracker state. Additional Local Tracker profiles use separate storage.

{% hint style="info" %}
This adapter reads and writes local files. Provider API rate limits do not apply.
{% endhint %}

### Watchlist behavior

* **Read:** reads the current local watchlist state.
* **Write:** adds or removes movies and shows.
* Stores canonical CW item data and available provider identifiers.
* Resolves a missing TMDb ID from an IMDb ID when metadata resolution is available.

### Collection behavior

CrossWatch Local Tracker can be a Collection source or target. Collection sync is one-way only.

The first run creates a baseline. Later runs process changes since that baseline.

### Ratings behavior

* **Read:** reads locally stored ratings.
* **Write:** upserts or removes ratings.
* Supports movies, shows, seasons, and episodes.
* Retains rating values and timestamps from the synchronization engine.

### History behavior

* **Read:** reads locally stored watched state.
* **Write:** marks items watched or removes watched state.
* Supports movies, shows, seasons, and episodes.
* Retains watch timestamps when available.

### Progress behavior

* **Read:** reads locally stored playback progress.
* **Write:** adds, updates, or removes playback progress.
* Stores positions in milliseconds with available timestamp and duration data.

The **Continue Watching** interface can read local progress. It can update progress, remove it, or mark an item watched.

### Snapshots

CW can create a snapshot before changing local tracker data. Snapshots are stored separately for Watchlist, Ratings, History, and Progress.

* Default retention: `30` days
* Default maximum: `64` snapshots per feature
* Retention: `0` keeps snapshots indefinitely.
* Maximum snapshots: `0` allows unlimited snapshots.
* Restore selection defaults to **Latest** for each feature.

### Settings (advanced)

#### Root directory

Default: `/config/.cw_provider`

Additional profiles use `/config/.cw_provider/profiles/<profile>`.

#### Retention days

Default: `30`

Controls how long snapshots remain available.

#### Auto snapshot

Default: enabled

Creates a snapshot before local tracker data changes.

#### Maximum snapshots

Default: `64` per feature

Controls retained snapshots for watchlist, ratings, history, and progress.

#### Restore snapshot

Default: **Latest**

Select a snapshot separately for each feature.

### Limitations

* Local Tracker is CW storage. It is not a cloud tracker or backup service.
* Removing the CW configuration volume can remove tracker state and snapshots.
* Capacity depends on storage, snapshot retention, and tracker data volume.
* Playlists are not supported.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://wiki.crosswatch.app/crosswatch/settings/synchronization/trackers/crosswatch.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.