opencode-relocate-cli

A standalone CLI tool for managing OpenCode session locations, no LLM required. Runs as a plain Bash script, directly manipulating the OpenCode SQLite database. No OpenCode session, no Bun runtime, and no LLM round-trips needed.

Quick Reference

Command	What it does	When to use it
opencode-relocate relocate	Moves the project directory and updates all references	You moved or renamed a repo on disk
opencode-relocate move-sessions	Reassigns selected sessions to another project	Sessions were started in the wrong project
opencode-relocate split-project	Creates a new project and moves sessions into it	You split a repo or want to reorganize history
opencode-relocate relink	Re-links a project after its initial commit was recreated	You reset/recreated the root commit and lost session history

Installation

Option 1: Symlink to PATH

ln -s "$(pwd)/opencode-relocate" /usr/local/bin/opencode-relocate

Option 2: Copy to PATH

cp opencode-relocate /usr/local/bin/opencode-relocate
chmod +x /usr/local/bin/opencode-relocate

Option 3: Run directly

./opencode-relocate <command> [args...]

Requirements

• sqlite3 — pre-installed on macOS and most Linux distributions
• git — required for split-project and relink (derives project IDs from root commits)
• jq — optional; used for JSON updates when available, falls back to sed

Commands

relocate — Move a project to a new path

opencode-relocate relocate <old-path><new-path>

Moves the project directory and updates all internal OpenCode references (SQLite database and project JSON file).

# Example: rename a project directory
opencode-relocate relocate ~/Projects/my-app ~/Projects/my-app-v2

What happens:

1. Backs up the database (timestamped .bak file)
2. Moves the directory with mv
3. Updates project.worktree and session.directory in SQLite
4. Updates the project JSON in OpenCode's storage
5. Verifies all changes

After relocation, restart OpenCode from the new path:

cd~/Projects/my-app-v2 && opencode

---

move-sessions — Reassign sessions between projects

opencode-relocate move-sessions <source-path><target-path> [options]

Move sessions from one OpenCode project to another. Both projects must already exist in OpenCode (opened at least once).

The source can be a non-git directory — in that case, sessions are stored under the global project and are filtered by directory prefix so only sessions matching the source path are shown.

Three modes:

# Interactive (default) — checkbox-style session selector
opencode-relocate move-sessions ~/Projects/repo-a ~/Projects/repo-b
# List only — inspect sessions without moving
opencode-relocate move-sessions ~/Projects/repo-a ~/Projects/repo-b --list
# Scripted — provide session IDs directly
opencode-relocate move-sessions ~/Projects/repo-a ~/Projects/repo-b \
--session-ids "ses_abc123,ses_def456"

Interactive selector controls:

Key	Action
↑ / ↓ (or k / j)	Navigate up / down
Space	Toggle current session
a	Toggle all sessions
Enter	Confirm selection
q / Esc	Cancel

The selector shows [x] / [ ] checkboxes, highlights the current row, scrolls automatically for long lists, and displays a live count of selected sessions.

Child/subagent sessions are moved automatically with their parent.

---

split-project — Create a new project from sessions

opencode-relocate split-project <source-path><target-path> [options]

Like move-sessions, but the target doesn't need to exist as an OpenCode project. If the target directory has never been opened in OpenCode, a new project entry is created automatically.

If the target directory doesn't exist, split-project will prompt you to create it (mkdir -p). If it's not a git repository (or has no commits), you'll be prompted to initialize it (git init + initial empty commit). The source can be either a git-backed project or a non-git directory (global project — sessions are filtered by directory prefix).

# Interactive (checkbox selector)
opencode-relocate split-project ~/Projects/monorepo ~/Projects/new-service
# Split sessions from a non-git directory into a git-backed project
opencode-relocate split-project ~/Projects/sandbox ~/Projects/new-repo
# List only
opencode-relocate split-project ~/Projects/monorepo ~/Projects/new-service --list
# Scripted
opencode-relocate split-project ~/Projects/monorepo ~/Projects/new-service \
--session-ids "ses_abc123,ses_def456"

Same interactive controls as move-sessions (arrow keys, Space, Enter).

When to use split-project vs move-sessions:

Scenario	Command
Target project already exists in OpenCode	Either works
Target directory was never opened in OpenCode	split-project
Source is a non-git directory (global project)	Either works (filtered by directory)
Target directory is not a git repo	split-project (will offer to git init)

---

relink — Re-link a project after its initial commit changed

opencode-relocate relink <path> [options]

OpenCode identifies a project by the hash of its first root commit (git rev-list --max-parents=0 HEAD). If you reset or recreate the initial commit — e.g. squashing history, git update-ref -d HEAD, or rebuilding the repo — that hash changes, and OpenCode treats the repo as a brand-new project. All previous sessions become orphaned.

relink migrates the existing project from the old ID to the new root-commit-derived ID: sessions, workspaces, permissions, on-disk JSON artifacts, and the .git/opencode cache file.

# Auto-detect old and new IDs and relink
opencode-relocate relink ~/Projects/my-app
# Preview changes without writing anything
opencode-relocate relink ~/Projects/my-app --dry-run
# Specify IDs explicitly
opencode-relocate relink ~/Projects/my-app \
--old-id eca18ff587da0906289bd984d8b0fd7622b69604 \
--new-id b761b3048a1c1129822fcfaaf9252db49dace055

Auto-detection:

• New ID is derived from the repo's current root commit hash.
• Old ID is found by looking up the project whose worktree matches <path> but whose ID differs from the new ID, falling back to the cached value in .git/opencode.

Merge behavior: If a project row for the new ID already exists (e.g. you reopened OpenCode after the reset, so it created a fresh project), the old sessions are merged into it. Otherwise a new project row is created as a copy of the old one.

What happens:

1. Backs up the database (timestamped .bak file)
2. Re-points session, workspace, and permission rows to the new ID
3. Creates or merges into the new project row, then deletes the old one
4. Migrates storage/project/<id>.json and storage/session/<id>/ artifacts
5. Updates the .git/opencode cache to the new ID
6. Verifies the migration

Sessions keep their existing directory — only the project ID changes. Use --dry-run first if you want to preview the exact changes.

Safety

Automatic backups

Every command backs up opencode.db (plus WAL/SHM files) before making changes. Backups are timestamped:

~/.local/share/opencode/opencode.db.20260408_143022.bak

Interactive confirmation

All destructive operations require [y/N] confirmation before proceeding.

What's preserved

• All session content: messages, tool calls, parts, todos
• Session metadata: titles, timestamps, summaries
• Parent-child session relationships (subagent sessions move with their parent)

What's NOT preserved

• Undo/redo snapshots — stored per-project, not per-session

Recovery

Restore from backup:

cp ~/.local/share/opencode/opencode.db.20260408_143022.bak \
~/.local/share/opencode/opencode.db

Limitations

• After relocate, the current OpenCode session breaks (restart required).
• move-sessions requires the target to already exist as an OpenCode project.
• Undo/redo snapshots are not moved.
• Clones of the same repository share the same project ID (same root commit), so you cannot move sessions between clones of the same repo.
• The global project cannot be used as a target — only as a source (sessions are filtered by directory prefix).
• relink derives the new project ID from git rev-list --max-parents=0 HEAD and updates the .git/opencode cache; the repo must have at least one commit.

Disclaimer

This is an independent, community-built tool. It is not built by the OpenCode team and is not affiliated with OpenCode in any way. The "opencode" in the name refers only to the tool's purpose of managing OpenCode session data.