diff --git a/CHANGELOG.md b/CHANGELOG.md index 2b6cefc..129bc6c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,30 @@ [简体中文](./CHANGELOG.zh-CN.md) +## 3.3.0 + +OpenCode 2 support. Upgrade every machine before or together with OpenCode 2; +see **Upgrading to OpenCode 2** in the README. + +### Security +- **OpenCode 2's `service.json` is never committed.** OpenCode 2 writes it into the config folder (service settings and a password) and into the state folder (URL, process id and a password). The config folder is the repository, so 3.2.0 committed the first, and the state mirror carried the second. Both are now ignored, removed from the repository on the next push, and this machine's own copy survives pulling an older commit that still has another machine's. Lock files, prompt history and recent-file lists (`_state/locks/`, `prompt-history.jsonl`, `frecency.jsonl`) are machine-local for the same reason. The files stay in the repository's history; the password only opens the local background service on that machine. + +### Added +- **OpenCode 2 sessions.** Sessions are exported from and imported into OpenCode 2's own tables (`session_v2`, `session_message`, `session_part`, instruction and attachment rows, and the message counter a continued conversation needs). A fresh OpenCode 2 database has no `session` table, so 3.2.0 failed every push there with `no such table: session`. OpenCode 2 sessions travel as format 2 shards; OpenCode 1 and OpenCode 2 machines can share a repository, each importing its own kind and leaving the other's recent shards in place. +- **Imported sessions show up in `/session`.** OpenCode 2 lists only the current project's sessions, so each imported session is placed in the project OpenCode 2 uses for its folder on this machine, creating it the way OpenCode 2 would. A folder under the other machine's home folder is matched to the same folder under this one; a folder this machine does not have puts the session in the home folder's project. +- **`opencode-sync repair-sessions [--apply]`** moves sessions OpenCode 2 migrated from 1.x into the project where `/session` looks for them (the synthetic `global` project and stale project rows of the same repository hide them). Preview by default. +- **Credentials on OpenCode 2.** OpenCode 2 keeps accounts in its database and reads `auth.json` at most once (a database it creates fresh never reads it). With credential sync on, the account picked in OpenCode is written to `auth.json` before a push, and incoming accounts are applied to the database after a pull; a running OpenCode sees them on its next request. A renewed OAuth token updates the account in place, the later expiry wins a conflict, an account missing from an incoming copy never logs a machine out, and logging out on a machine removes the account from the shared copy. Change detection keeps only hashes, in `opencode-sync-credentials.json` next to the database. +- **One machine renews a shared ChatGPT login.** Refreshing an OpenAI OAuth login invalidates its old refresh token, so machines sharing one login logged each other out. With credential sync on, the scheduled job now claims `refs/leases/openai` in the sync repository (an atomic compare-and-swap on the server) and only the winner refreshes, three days before expiry; the next sync hands the new token to the others. Set `"openaiRefreshLease": false` to turn it off. +- **`cli.json`** (OpenCode 2's interface preferences) is part of the main config. Plugin entries that point into this machine's global plugins folder, which the 1.x-to-2 migration writes there, are dropped before sharing; OpenCode 2 finds those plugins without them. + +### Changed +- OpenCode 2 reloads configuration by itself, so the restart hint now says a restart is needed only on OpenCode 1 or after a plugin changed. +- The database is opened with a 10-second busy timeout, because OpenCode 2's background service keeps it open. +- Repository links point to `lazyalex616/opencode-github-sync` (the account was renamed; the old links redirect). + +### Fixed +- A received OpenCode 2 session is no longer exported back by the machine that received it. + ## 3.2.0 ### Added diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md index 49cab2d..5ee8bcd 100644 --- a/CHANGELOG.zh-CN.md +++ b/CHANGELOG.zh-CN.md @@ -2,6 +2,29 @@ [English](./CHANGELOG.md) +## 3.3.0 + +支持 OpenCode 2。请在升级 OpenCode 2 之前或同时,把每台电脑都升到这个版本;具体步骤见 README 的**升级到 OpenCode 2**。 + +### 安全 +- **OpenCode 2 的 `service.json` 永远不会提交。** OpenCode 2 会在配置目录里写一份(服务设置和一个密码),在状态目录里再写一份(地址、进程号和一个密码)。配置目录本身就是仓库,所以 3.2.0 会把第一份提交上去,状态目录镜像又带上了第二份。现在两份都被忽略,下次推送时会从仓库里删掉;拉取到旧版本留下的、别的电脑的那份时,本机自己的副本也不会被覆盖。锁文件、输入历史和最近文件列表(`_state/locks/`、`prompt-history.jsonl`、`frecency.jsonl`)同理改为只留在本机。这些文件仍留在仓库历史里;里面的密码只能打开那台电脑本地的后台服务。 + +### 新增 +- **OpenCode 2 会话同步。** 会话直接从 OpenCode 2 自己的表导出和导入(`session_v2`、`session_message`、`session_part`、指令和附件数据,以及继续对话时需要的消息计数器)。全新的 OpenCode 2 数据库根本没有 `session` 表,所以 3.2.0 在那里每次推送都报 `no such table: session`。OpenCode 2 的会话用第 2 版格式保存;OpenCode 1 和 OpenCode 2 的电脑可以共用一个仓库,各自只导入自己那一类,不会删掉对方最近的会话。 +- **导入的会话能在 `/session` 里看到。** OpenCode 2 只列出当前项目的会话,所以每个导入的会话都会放进本机 OpenCode 2 为那个文件夹使用的项目里,必要时按 OpenCode 2 的规则新建项目。另一台电脑用户目录下的文件夹会对应到本机用户目录下的同名文件夹;本机没有的文件夹,会话放进用户目录的项目里。 +- **`opencode-sync repair-sessions [--apply]`**:把 OpenCode 2 从 1.x 迁移过来、在 `/session` 里看不到的会话移回所属项目(合成的 `global` 项目、同一仓库的旧项目记录都会让它们隐身)。默认只预览。 +- **OpenCode 2 的登录凭据。** OpenCode 2 把账号存在数据库里,最多只读一次 `auth.json`(它新建的数据库一次都不读)。开启凭据同步后,推送前会把 OpenCode 里选中的账号写进 `auth.json`,拉取后再把收到的账号写进数据库,正在运行的 OpenCode 下一次请求就能用上。OAuth 令牌续期后原地更新,冲突时以到期更晚的为准;传过来的副本里缺了某个账号不会把本机登出;在某台电脑上退出登录,会从共享副本里删掉这个账号。判断哪边变了只保存哈希值,存在数据库旁边的 `opencode-sync-credentials.json` 里。 +- **共用的 ChatGPT 登录只由一台电脑续期。** 刷新 OpenAI OAuth 登录会让旧的刷新令牌失效,所以共用同一个登录的电脑会互相挤掉。开启凭据同步后,定时任务会先在同步仓库里抢占 `refs/leases/openai`(在服务器上原子比较并交换),只有抢到的那台在到期前三天刷新,下一次同步再把新令牌带给其他电脑。设 `"openaiRefreshLease": false` 可以关掉。 +- **`cli.json`**(OpenCode 2 的界面偏好)归入主配置一起同步。从 1.x 迁移到 2 时写进去的、指向本机全局插件文件夹的插件条目,会在共享前去掉;OpenCode 2 不靠这些条目也能找到那些插件。 + +### 变更 +- OpenCode 2 会自动重新读取配置,所以“重启 OpenCode”的提示改为:只有 OpenCode 1 或插件变化后才需要重启。 +- 打开数据库时最多等待 10 秒,因为 OpenCode 2 的后台服务会一直开着它。 +- 仓库链接改为 `lazyalex616/opencode-github-sync`(账号改了名,旧链接会自动跳转)。 + +### 修复 +- 收到的 OpenCode 2 会话,不会再被接收它的电脑原样导出推回去。 + ## 3.2.0 ### 新增 diff --git a/README.md b/README.md index db18ad1..189d12a 100644 --- a/README.md +++ b/README.md @@ -1,218 +1,268 @@

- opencode-github-sync: one config, every machine + opencode-github-sync: one config, every machine

npm - CI - license + CI + license platform + OpenCode

- 简体中文 + 简体中文  ·  Install  ·  - Setup + OpenCode 2  ·  - Autosync + Autosync  ·  - Commands + Commands  ·  Troubleshooting

--- -You use OpenCode on more than one computer. Your config, agents, commands, -skills and MCP servers end up wherever you last touched them. +You use OpenCode on more than one computer, and every machine drifts: a new +agent here, an MCP server there, a skill you installed on the laptop and forgot +on the desktop. + +**opencode-github-sync** keeps all of them on one setup through a private +GitHub repository. Run it by hand when you want, or let your everyday machines +sync themselves in the background. It works with OpenCode 1 and OpenCode 2, +and both can share the same repository. + +**What you get** + +- Config, instruction files, agents, commands, plugins, themes and skills on + every machine. +- Optionally your logins and your recent conversations, too. +- Settings that belong to one machine stay on that machine. +- Nothing is overwritten without a copy kept first, and a broken sync can be + repaired from the command line even when OpenCode will not start. + +## Contents + +- [Install](#install) +- [First run](#first-run) +- [What gets synced](#what-gets-synced) +- [OpenCode 2](#opencode-2) +- [Autosync](#autosync) +- [Per-machine overrides](#per-machine-overrides) +- [Sessions](#sessions) +- [Credentials](#credentials) +- [Safety](#safety) +- [The menu](#the-menu) +- [OpenCode plugin](#opencode-plugin) +- [Commands](#commands) +- [Settings file](#settings-file) +- [Troubleshooting](#troubleshooting) +- [Upgrading](#upgrading) +- [Development](#development) -**opencode-github-sync** keeps every machine on the same setup through a -private GitHub repository. Run it by hand, or let one machine sync itself in -the background. +--- ## Install **macOS / Linux** ```bash -curl -fsSL https://raw.githubusercontent.com/doomsday616/opencode-github-sync/main/install.sh | sh +curl -fsSL https://raw.githubusercontent.com/lazyalex616/opencode-github-sync/main/install.sh | sh ``` **Windows** (PowerShell 5.1 or 7) ```powershell -irm https://raw.githubusercontent.com/doomsday616/opencode-github-sync/main/install.ps1 | iex +irm https://raw.githubusercontent.com/lazyalex616/opencode-github-sync/main/install.ps1 | iex ``` The installer checks for Node.js 18+ and git. If one is missing it shows the command that would install it and asks before running anything. Then it runs `npm install -g opencode-github-sync@latest` and opens the menu. -Already have Node.js? `npm install -g opencode-github-sync` and then -`opencode-sync` does the same thing. +Already have Node.js? This does the same: + +```bash +npm install -g opencode-github-sync +opencode-sync +``` + +**Requirements** + +| | Needed for | +| --- | --- | +| Node.js 18 or newer | everything | +| Node.js 22.5 or newer | sessions, and credentials on OpenCode 2 (they use Node's built-in SQLite) | +| git | everything | +| GitHub CLI (`gh`), signed in | only `init`, which creates the repository for you | +| OpenCode 1.3.4+ or 2.x | the optional plugin | ### Set up a machine in one line -Pass options to skip the questions, for example when provisioning a new +Pass options to skip every question, for example when preparing a new machine: ```bash -curl -fsSL https://raw.githubusercontent.com/doomsday616/opencode-github-sync/main/install.sh | sh -s -- --mode auto --repo you/my-opencode-config +curl -fsSL https://raw.githubusercontent.com/lazyalex616/opencode-github-sync/main/install.sh | sh -s -- --mode auto --repo you/my-opencode-config ``` ```powershell -& ([scriptblock]::Create((irm https://raw.githubusercontent.com/doomsday616/opencode-github-sync/main/install.ps1))) -Mode auto -Repo you/my-opencode-config +& ([scriptblock]::Create((irm https://raw.githubusercontent.com/lazyalex616/opencode-github-sync/main/install.ps1))) -Mode auto -Repo you/my-opencode-config ``` | Option | Meaning | | --- | --- | -| `--mode cli` / `-Mode cli` | Install the command only | +| `--mode cli` | Install the command only | | `--mode link` | Link `--repo` and sync once | | `--mode auto` | Link, sync once and turn on autosync | | `--repo owner/name` | The repository (a git URL works too); created as private if it does not exist | | `--interval N` | Autosync every N minutes (minimum 2, default 5) | | `--lang en` / `zh-CN` | Interface language | | `--proxy URL` | Proxy for npm and git, during install and for later syncs | -| `--yes` | Install missing Node.js or git without asking | +| `--yes` | Install a missing Node.js or git without asking | | `--package SPEC` | npm package spec to install (default `opencode-github-sync@latest`) | | `--dry-run` | Print what would run, change nothing | -On Windows each option is the same word with a leading dash: `-Repo`, -`-Interval`, `-Lang`, `-Proxy`, `-Yes`, `-Package`, `-DryRun`. - -When the repository already has content and this machine also has its own -files, setup takes the repository's version and keeps the replaced files in a -[recovery folder](#safety-features). +On Windows each option is the same word with one leading dash: `-Mode`, +`-Repo`, `-Interval`, `-Lang`, `-Proxy`, `-Yes`, `-Package`, `-DryRun`. --- -## Pick your setup +## First run

- Command only, or primary device with autosync + Command only, or primary device with autosync

-The first time you run `opencode-sync` it asks how this machine should work. +The first time you run `opencode-sync` it asks how this machine should work: | | Command only | Primary device + autosync | | --- | --- | --- | -| How it syncs | You run `opencode-sync push` / `pull`, or the plugin pulls at startup | The operating system runs a sync every few minutes, even when OpenCode is closed | +| How it syncs | You run `opencode-sync push` / `pull`, or the plugin pulls when OpenCode starts | The operating system syncs every few minutes, even while OpenCode is closed | | Good for | A machine you use now and then, a shared or locked-down machine | The machines you work on every day | | Background job | None | Task Scheduler, launchd or a systemd timer | -You can change your mind any time from the **Autosync** menu. Autosync is -opt-in per machine: turning it on here never turns it on anywhere else. - ---- +Then it links a repository: -## The menu +- **No repository yet?** It creates a private one with `gh` (or run + `opencode-sync init`). +- **Already have one?** Pick it from the list, or give `owner/name` or any git + URL (or run `opencode-sync link owner/name`). -Run `opencode-sync` with no arguments. - -

- The opencode-sync menu -

- -Arrow keys or the shown hotkey pick an item, space ticks a checkbox, Enter -confirms and Esc goes back. When the input is not a terminal (a pipe, a script, -CI) every prompt becomes a numbered question, so the menu can be driven from a -file. - -| Item | What you can do there | -| --- | --- | -| **Sync now** | Push and receive, receive only, push only, or preview first | -| **What to sync** | Tick main config, instruction files, agents, commands, plugins, skills, credentials, sessions; set session limits; add extra paths | -| **Autosync** | Turn it on or off, choose 5/10/15/30/60 minutes or your own interval, pause it, run while signed out (Windows), notifications | -| **Update** | Check npm for a newer version, upgrade, update automatically once a day | -| **This machine's overrides** | Open the overrides file in your editor, see what it changes | -| **Diagnostics** | git, node, gh, repository access, the scheduled job, the last log lines; export a support bundle | -| **Danger zone** | Make this machine match the repository, or the other way round (you type `overwrite` to confirm) | -| **Uninstall** | Remove the scheduled job, optionally unlink and remove the command. Your configuration is never deleted | -| **Network proxy** | A proxy for git, gh and npm, used only by opencode-sync | -| **Restore a file from history** | Pick a file, pick a version, put it back | -| **Devices** | Every machine that has synced and when, and renaming this one | -| **Large-change guard** | The limits that make a big push stop and ask | -| **Language** | English, 简体中文 or automatic | +If the repository already has content and this machine has its own files, the +menu shows the differences and lets you pick a side. The losing side's files +are copied to the [recovery folder](#safety) first. -Every command from earlier versions still works and is still scriptable. +You can change your mind any time under **Autosync**. Autosync is per machine: +turning it on here never turns it on anywhere else. --- ## What gets synced

- Each machine pushes and pulls through one private repository + Each machine pushes and pulls through one private repository

Your `~/.config/opencode` folder becomes a working copy of the repository. -Everything else is mirrored into a folder inside it. +Everything that lives elsewhere is mirrored into a folder inside it. | On your machine | In the repository | What it holds | | --- | --- | --- | -| `~/.config/opencode/` | the root | config, agents, commands, plugins, themes, instruction files | -| `~/.local/share/opencode/` | `_data/` | project metadata, and credentials if you opt in | -| `~/.local/state/opencode/` | `_state/` | model cache, recent files, prompt history | +| `~/.config/opencode/` | the root | `opencode.json(c)`, `tui.json(c)`, OpenCode 2's `cli.json`, agents, commands, plugins, themes, instruction files | +| `~/.local/share/opencode/` | `_data/` | project metadata; logins if you [opt in](#credentials) | +| `~/.local/state/opencode/` | `_state/` | model cache and other interface state | | `~/.agents/skills/` | `_agents/` | skills installed with the `skills` CLI | -| selected sessions | `_sessions/` | one small compressed file per session | -| your extra paths | `_extra/` | anything else you add | +| selected sessions | `_sessions/` | one small compressed file per session, if you [opt in](#sessions) | +| your extra paths | `_extra/` | any other file or folder you add, such as `.config/gh/config.yml` | Each part can be switched off under **What to sync**. A part you switch off stays local in both directions: your edits are not sent, and other machines' versions do not replace yours. -**Never synced:** the `opencode.db` database, tool output, snapshots, logs, -`node_modules` and other generated folders, and opencode-sync's own settings -and overrides files. +**Never synced** + +- The `opencode.db` database itself, tool output, snapshots and logs. Sessions + travel as separate small files instead. +- `node_modules` and other generated folders. +- opencode-sync's own settings and overrides files. +- Anything that describes one machine rather than your setup: OpenCode 2's + `service.json` (one in the config folder and one in the state folder; each + holds the local background service's password), lock files, prompt history, + recent-file lists, and `cli.json` plugin entries that point into this + machine's home folder. --- -## How autosync works +## OpenCode 2 + +opencode-github-sync 3.3.0 and later support OpenCode 2 (`@opencode/cli`) fully. +Machines on OpenCode 1 and OpenCode 2 can use one repository side by side. + +What is different on OpenCode 2, and what this tool does about it: + +| OpenCode 2 changed | What opencode-sync does | +| --- | --- | +| Sessions live in new tables, and a fresh OpenCode 2 database has no old ones | Reads and writes OpenCode 2's own tables. OpenCode 1 machines keep their own format; each side imports only its own kind and leaves the other's in place | +| `/session` lists only the sessions of the current folder's project | Each imported session is placed in the project OpenCode 2 uses for that folder on the receiving machine, so it appears in `/session` | +| Sessions migrated from 1.x can vanish from `/session` | `opencode-sync repair-sessions` moves them back where `/session` looks | +| Logins live in the database, and `auth.json` is read at most once | With credential sync on, logins are copied between the two around every sync | +| Interface preferences moved to `cli.json` | Shared as part of the main config, without this machine's plugin paths | +| A `service.json` with a password sits in the config folder | Never committed, and removed from repositories an older version wrote it into | +| Configuration reloads by itself | The "restart OpenCode" hint only appears where a restart is still needed: OpenCode 1, or a changed plugin | + +To move a machine from OpenCode 1 to 2, see [Upgrading to OpenCode 2](#upgrading-to-opencode-2). + +--- + +## Autosync

- Each machine syncs on its own schedule, waits while you edit, and backs off on errors + Each machine syncs on its own schedule, waits while you edit, and backs off on errors

When autosync is on, the operating system starts `opencode-sync autosync run` -every few minutes and at sign-in (on Windows also when you unlock or reconnect -over Remote Desktop). Each run makes one decision: +every few minutes and at sign-in (on Windows also when you unlock the screen or +reconnect over Remote Desktop). Each run makes one decision: -1. **Is it quiet?** If any file in your config or skills folders changed in the +1. **Is it quiet?** If a file in your config or skills folders changed in the last minute, something is still being written. Sending now could publish a half-saved file, so the push waits. -2. **Can it at least receive?** While busy, it still takes other machines' - changes, but only when this machine has nothing of its own waiting. - Otherwise it leaves everything for the next run. -3. **Push and receive.** Your changes go up, other machines' changes come down, - in one step. - -The rules that keep this safe: - -- **Machines take turns.** Each machine waits a fixed few seconds based on its - name, so two machines on the same schedule do not collide every time. If - another machine still gets there first, this one picks up the new commit and - tries again; that does not count as an error. -- **It backs off, but never gives up.** After three failures in a row - (typically no network) it waits 30 minutes, then an hour between attempts. - The first success puts it back on schedule. -- **It only interrupts you twice.** One notification when it starts backing - off, one when it recovers. Nothing for ordinary syncs. -- **It never runs twice at once.** A lock is shared by the scheduled job, the - CLI, the menu and every OpenCode window; if one is busy, the others skip. -- **It never confirms a large change.** Anything that trips the - [large-change guard](#safety-features) is held back and you get a - notification. +2. **Can it at least receive?** While you are busy it still takes other + machines' changes, but only when this machine has nothing of its own + waiting. Otherwise everything waits for the next run. +3. **Push and receive.** Your changes go up and other machines' changes come + down in one step. + +The rules that keep it safe: + +- **Machines take turns.** Each machine waits a few seconds, fixed per machine, + so two machines on the same schedule do not collide every time. If another + machine still gets there first, this one takes the new commit and tries + again; that does not count as an error. +- **It backs off but never gives up.** After three failures in a row (usually + no network) it waits 30 minutes, then an hour between attempts. The first + success puts it back on schedule. +- **It interrupts you twice at most.** One notification when it starts backing + off, one when it recovers. Ordinary syncs are silent. +- **It never runs twice at once.** One lock is shared by the scheduled job, the + command, the menu and every OpenCode window; whoever finds it busy skips. +- **It never approves a large change by itself.** Anything that trips the + [large-change guard](#safety) is held back and you get a notification. +- **It renews a shared ChatGPT login.** See [Credentials](#credentials). | Platform | Scheduler | Notes | | --- | --- | --- | -| Windows | Task Scheduler | Runs hidden. To run while signed out, turn that on in the menu and install from an administrator terminal | +| Windows | Task Scheduler | Runs hidden. To run while signed out, turn it on in the menu and install from an administrator terminal | | macOS | launchd agent | `~/Library/LaunchAgents/com.opencode-github-sync.autosync.plist` | | Linux | systemd user timer | Falls back to a crontab line. On a server, run `loginctl enable-linger` so it runs while you are logged out | -`opencode-sync autosync status` shows the last run, the last error and when it -will try next. With autosync on, the OpenCode plugin stops pushing on idle so -the two never compete; it still pulls when OpenCode starts. +`opencode-sync autosync status` shows the last run, the last error and the next +attempt. With autosync on, the plugin stops pushing on idle so the two never +compete; it still pulls when OpenCode starts. --- @@ -240,16 +290,16 @@ overrides** in the menu: ``` Objects merge key by key, lists and plain values replace, and `null` removes a -key. Before every push, any key the overrides file claims is put back to the +key. Before every push, each key the overrides file claims is put back to the repository's value, so your machine-only values never reach other machines. -Without an overrides file, the config is copied exactly as written, comments +Without an overrides file the config is copied exactly as written, comments and all. --- ## Sessions -Off by default. Only turn it on for a private repository: conversations are +Off by default. Turn it on only for a private repository: conversations are private. ```bash @@ -260,45 +310,94 @@ opencode-sync sessions exclude ses_0ba19b4e7ffeMbSmWYi3Nj6xfZ # never sync this ``` Sessions are not synced by committing the database. A real OpenCode database -grows to several gigabytes, mostly tool output, and git cannot merge it. Each -session is exported on its own as a small compressed file instead: - -- **Small.** Only recent sessions (7 days and 50 sessions by default), and any - single session over 5 MB is skipped. -- **No conflicts in practice.** Two machines working on different sessions - touch different files. The same session edited in two places keeps the newer - version. -- **Safe to import.** Importing runs in one transaction, so a failure leaves - your database as it was. +grows to several gigabytes, mostly tool output, and git cannot merge it. +Instead each session is exported on its own as a small compressed file: + +- **Small.** Only recent sessions travel (7 days and 50 sessions by default), + and any single session over 5 MB is skipped. +- **Conflicts are rare and resolved.** Two machines working on different + sessions touch different files. When one session changed on two machines, the + newer copy wins; on OpenCode 2 the replaced local copy is saved to the + recovery folder first if it had messages the newer one lacks. +- **Never disturbs a running conversation.** A session that is busy on this + machine is not replaced, and runtime state (busy, compacting, retry counters) + is never carried over, so a receiving machine never resumes a conversation on + its own. +- **Lands in the right place.** On OpenCode 2 an imported session is placed in + the project OpenCode 2 uses for its folder here. A folder under the other + machine's home is matched to the same folder under yours; a folder this + machine does not have puts the session in your home folder's project. +- **Safe to import.** Each session is imported in one transaction, so a failure + leaves your database as it was. Window, count and size limits are under **What to sync → Session settings**. -Session sync needs Node.js 22.5 or newer. +Sessions need Node.js 22.5 or newer. + +**Sessions missing from `/session` after upgrading to OpenCode 2?** OpenCode's +own migration leaves some of them in a project `/session` never shows. Their +content is intact: + +```bash +opencode-sync repair-sessions # preview: what would move where +opencode-sync repair-sessions --apply # move them +``` --- -## Safety features +## Credentials + +Off by default, and refused outright when the repository is public. Turn it on +under **What to sync → Credentials** or with `"includeCredentials": true`. + +On OpenCode 1, `auth.json` is synced as a file. On OpenCode 2, which keeps +logins in its database, opencode-sync also copies between the database and +`auth.json` around every sync: + +- The account you pick in OpenCode (for example after `/connect` or switching + accounts) is what the other machines receive. A running OpenCode picks up an + incoming account on its next request, without a restart. +- A renewed login updates the existing account instead of adding a copy. When + both sides changed, the one that expires later wins. +- An account missing from an incoming copy never logs this machine out. + Logging out on a machine removes that account from the shared copy. +- A broken or half-written `auth.json` is never overwritten. +- To tell which side changed, only hashes of the last synced values are kept, + in `opencode-sync-credentials.json` next to the database. Never the secrets. + +**Shared ChatGPT login.** Renewing an OpenAI login invalidates the previous +one, so machines that each renew the same login log each other out. With +credential sync on, only one machine renews it: the scheduled job claims a +lease in the sync repository (an atomic operation on GitHub's side), renews +three days before the login expires, and the next sync hands the new login to +every other machine. A claim older than 15 minutes is considered abandoned and +can be taken over. Set `"openaiRefreshLease": false` to turn this off. + +--- + +## Safety

- One sync at a time, all-or-nothing writes, restore earlier versions, large-change guard + One sync at a time, all-or-nothing writes, restore earlier versions, large-change guard

-- **Atomic replace.** Files are written beside their target and then swapped - in, so a crash mid-sync cannot leave a half-written config that stops +- **All-or-nothing writes.** Files are written beside their target and then + swapped in, so a crash mid-sync cannot leave a half-written config that stops OpenCode from starting. - **Push verification.** After pushing, the remote is read back. `git push` can report success without the remote changing; that is checked, not assumed. -- **One sync at a time.** A lock shared by the plugin, the CLI, the menu and - the scheduled job. +- **One sync at a time.** A lock shared by the plugin, the command, the menu + and the scheduled job. - **Large-change guard.** A push that adds more than 300 files, more than 10 MB in total, or any single file over 2 MB stops and asks. The limits are adjustable. Generated folders such as `node_modules`, `.venv`, `venv`, `__pycache__`, `dist` and `.cache` are never sent. -- **Recovery folder.** Before a forced pull, a "repository wins" first link, - or a restore from history, the files about to be replaced are copied to +- **Recovery folder.** Before a forced pull, a "repository wins" first link, a + restore from history, or replacing a session that was continued on both + machines, what is about to be replaced is copied to `~/.local/share/opencode/opencode-sync-recovery/