@ashdev/codex-plugin-sync-anilist

A Codex plugin for syncing manga reading progress between Codex and AniList. Supports push/pull of reading status, volumes/chapters read, scores, dates, and notes.

Features

• Two-way sync of manga reading progress with AniList
• Push reading status, progress, scores, dates, and notes to AniList
• Pull updates from AniList back to Codex
• Configurable progress unit (volumes or chapters)
• Auto-pause/auto-drop stale series based on reading inactivity
• Rate limit handling with automatic retry
• Highest-progress-wins conflict resolution (progress only moves forward)
• External ID matching via AniList API IDs (api:anilist)

Authentication

This plugin supports two authentication methods:

OAuth (Recommended)

If your Codex administrator has configured OAuth:

1. Go to Settings > Integrations
2. Click Connect with AniList Sync
3. Authorize Codex on AniList
4. You're connected!

Personal Access Token

If OAuth is not configured by the admin:

1. Go to AniList Developer Settings
2. Click Create New Client
3. Set the redirect URL to https://anilist.co/api/v2/oauth/pin
4. Click Save, then Authorize your new client
5. Copy the token shown on the pin page
6. In Codex, go to Settings > Integrations
7. Paste the token in the access token field and click Save Token

Admin Setup

Adding the Plugin to Codex

1. Log in to Codex as an administrator
2. Navigate to Settings > Plugins
3. Click Add Plugin
4. Fill in the form:
   • Name: sync-anilist
   • Display Name: AniList Sync
   • Command: npx
   • Arguments: -y @ashdev/[email protected]
5. Click Save
6. Click Test Connection to verify the plugin works

Configuring OAuth (Optional)

To enable OAuth login for your users:

1. Go to AniList Developer Settings
2. Click Create New Client
3. Set the redirect URL to {your-codex-url}/api/v1/user/plugins/oauth/callback
4. Save and copy the Client ID
5. In Codex, go to Settings > Plugins > click the gear icon on AniList Sync
6. Go to the OAuth tab
7. Paste the Client ID (and optionally the Client Secret)
8. Click Save Changes

Without OAuth configured, users can still connect by pasting a personal access token.

npx Options

| Configuration | Arguments | Description | |--------------|-----------|-------------| | Latest version | -y @ashdev/codex-plugin-sync-anilist | Always uses latest | | Pinned version | -y @ashdev/[email protected] | Recommended for production | | Fast startup | -y --prefer-offline @ashdev/[email protected] | Skips version check if cached |

Configuration

Codex Sync Settings

These settings are managed in the Sync Settings section of the plugin settings modal. They control which data the Codex server sends to the plugin and are shared across all sync plugins.

| Setting | Default | Description | |---------|---------|-------------| | Include completed series | On | Include series where all local books are read | | Include in-progress series | On | Include series where at least one book has been started | | Count partially-read books | Off | Whether partially-read books count toward the progress number | | Sync ratings & notes | On | Include user ratings and notes in sync |

Plugin-Specific Settings

These settings are specific to the AniList plugin and appear under Plugin Settings in the settings modal.

| Setting | Type | Default | Description | |---------|------|---------|-------------| | Progress Unit | string | volumes | Whether each Codex book counts as a "volume" or "chapter" on AniList. Use "volumes" to avoid misleading "Read chapter X" activity on AniList. | | Auto-Pause After Days | number | 0 (disabled) | Number of days without reading activity before an in-progress series is set to Paused on AniList | | Auto-Drop After Days | number | 0 (disabled) | Number of days without reading activity before an in-progress series is set to Dropped on AniList |

Using the Plugin

Once connected, the sync plugin works automatically:

1. Go to Settings > Integrations
2. Click Sync Now to trigger a manual sync
3. View sync status including pulled/pushed/applied counts

The plugin matches Codex series to AniList entries using external IDs stored in the series_external_ids table with the api:anilist source.

Sync Behavior

Sync Modes

You can configure which direction data flows in Settings > Integrations > Settings:

| Mode | Description | |------|-------------| | Pull & Push (default) | Import progress from AniList, then export Codex progress to AniList | | Pull Only | Import progress from AniList without writing anything back | | Push Only | Export Codex progress to AniList without importing |

How Sync Works

When sync runs in Pull & Push mode, it executes two phases in order:

1. Pull — Fetches your reading list from AniList, matches entries to Codex series via external IDs, and marks the corresponding books as read in Codex.
2. Push — Reads your current Codex reading progress and sends it to AniList, overwriting the remote entry.

Conflict Resolution

Codex uses a highest progress wins strategy. There is no manual conflict resolution — instead, progress can only move forward:

| Scenario | Result | |----------|--------| | AniList ahead (e.g., 5 vols read) and Codex behind (3 vols read) | Pull marks books 4–5 as read in Codex. Push sends 5 to AniList. Both agree. | | Codex ahead (5 vols read) and AniList behind (3 vols read) | Pull tries to mark first 3 as read — already completed, skipped. Push sends 5 to AniList. Codex wins. | | Both changed differently | Pull applies remote progress first (additive only), then Push sends local state to AniList. Effectively Codex wins because push runs last. |

Key behaviors:

• Pull is additive only — it marks unread books as read but never un-reads a book. If you lower your chapter count on AniList, that change is ignored.
• Push overwrites the remote — after pulling, Codex sends its current state to AniList, which may overwrite changes made directly on AniList.
• Progress is monotonic — once a book is marked as read, sync will not undo it. Progress only moves forward.

Completed Status

The plugin is conservative about marking series as "Completed" on AniList:

• A series is pushed as Completed only when all local books are read and the series metadata includes a total_book_count that matches.
• Otherwise, the series is pushed as Reading — even if all local books are read — because Codex can't be sure the library contains the full series.

Rating & Notes Sync

When Sync Ratings & Notes is enabled in plugin settings:

• Push: Codex ratings (1-100 scale) and notes are sent to AniList, converted to the user's chosen AniList score format (auto-detected from their profile).
• Pull: AniList scores and notes are imported into Codex, but only when Codex has no existing rating for that series. Existing Codex ratings are never overwritten (Codex wins).
• Notes without a score are skipped on pull (Codex requires a rating to store notes).

Auto-Pause & Auto-Drop

You can configure automatic status changes for series you haven't read in a while:

| Configuration | Behavior | |--------------|----------| | Pause=5, Drop=0 | Not read in 5 days -> Paused | | Pause=5, Drop=7 | Not read in 5 days -> Paused; not read in 7 days -> Dropped | | Pause=5, Drop=3 | Not read in 3 days -> Dropped (drop fires first since threshold is shorter) | | Pause=0, Drop=4 | Not read in 4 days -> Dropped (no pause step) | | Pause=0, Drop=0 | Disabled (default) |

Key behaviors:

• Only affects in-progress series — completed series are never auto-paused or auto-dropped.
• Based on last reading activity — the timer resets every time you read any book in the series.
• Drop takes priority — if both pause and drop thresholds are met, the series is dropped (not paused).

Development

# Install dependencies
npm install

# Build the plugin
npm run build

# Type check
npm run typecheck

# Run tests
npm test

# Lint
npm run lint

Project Structure

plugins/sync-anilist/
├── src/
│   ├── index.ts          # Plugin entry point & staleness logic
│   ├── index.test.ts     # Staleness logic tests
│   ├── manifest.ts       # Plugin manifest
│   ├── anilist.ts        # AniList API client & utility functions
│   └── anilist.test.ts   # API client & utility tests
├── dist/
│   └── index.js          # Built bundle (excluded from git)
├── package.json
├── tsconfig.json
└── README.md

License

MIT