---
name: codex-task-server-sync
description: Migrate a macOS Codex workspace or running task to a Linux server, create or reuse a Gitea repo, sync it into /root/continue/project-name, and keep local and remote changes synchronized for uninterrupted continuation.
---

# Auto Sync Codex Task To Server

Use this skill when a local macOS Codex task needs to keep running from a Linux server without manually re-copying files or rebuilding context each time.

## Do This

1. Run the bootstrap script against the target workspace.
2. Let the script create or reuse the Gitea repo, push the current workspace snapshot, provision the server checkout, and install background sync on both hosts.
3. Continue work from the server by reading `.codex-sync/handoff.md` and resuming inside the migrated checkout.

## Command

```bash
./scripts/run.sh \
  --project-dir /absolute/path/to/workspace \
  --project-name workspace-slug \
  --gitea-token "$GITEA_TOKEN"
```

Use `--gitea-token-file` instead of `--gitea-token` when the token already lives on disk.

## What The Bootstrap Writes

- `.codex-sync/manifest.json`
- `.codex-sync/handoff.md`
- `.codex-sync/README.md`
- `.codex-sync/bin/sync-once.sh`
- `.codex-sync/bin/continue-task.sh`

The runtime directory `.codex-sync/runtime/` is created on demand and stays ignored by git.

## Recovery

- Inspect `.codex-sync/runtime/status.json` first when sync stops.
- Inspect `.codex-sync/runtime/last-error.log` next when the status says `blocked` or `error`.
- Clear a resolved conflict by removing `.codex-sync/runtime/blocked` and re-running `.codex-sync/bin/sync-once.sh`.
- Continue on the server with:

```bash
cd /root/continue/<project>
./.codex-sync/bin/continue-task.sh
```

Read [references/recovery.md](./references/recovery.md) for the exact recovery flow and service commands.